DocsDocumentation

Nexy documentation

Nexy is a fullstack Python meta-framework: FastAPI and Starlette serve the app, Vite builds the client. A route is a file under src/routes/ - .nexy is a page, .py is an API handler.

What Nexy gives you

  • A page from a file: .nexy, Markdown and MDX routes, layouts, metadata. Pages
  • A Python API: FastAPI handlers named after the HTTP method, validation, WebSocket. Route handlers
  • A client framework: React, Vue, Svelte, Solid and Preact, mixed in one project. Views
  • Control over rendering: SSR, ISR, CSR and islands, per page. Rendering
  • A typed call to Python: Actions, from a form or from TypeScript. Actions
  • A structured backend: Modular router with injection, guards and metadata. Modular routing
  • A product ready for the world: i18n, sessions, middleware, databases. Guides
  • A fast loop: Dev server, browser error overlay, dev toolbar. Dev toolbar
  • A deployable build: nx build and nx start, no Node at runtime. Deploy
  • Help from a coding agent: Project rules for Claude Code, Codex and OpenCode. Coding agents

Start with the task you have, not with the architecture. Every page is plain Markdown, written from the code.

Where to start

  • I want to see it work: Quick start, then the Tutorial.
  • I am building a feature: open Build and follow the task.
  • I must pick an option: open Choose (router, rendering mode, client framework).
  • I need an exact name or flag: open Reference.

Getting started

Page What you will do
Installation Requirements, uvx, uv tool install
Quick start Create a project, run it, build it
Tutorial A page, an endpoint and a production build in 10 minutes
How Nexy works The mental model: who builds what, and one request
Project structure Know what every folder is for
Coming from another framework Map FastAPI, Next.js and Express to Nexy
Upgrading to 2.2 What changes for an existing project

Build

Page What you will do
File-based routing Turn a file path into a URL
Pages Write a page
Dynamic routes [slug], [...path], route groups
Page metadata Title, description and share image of a page
Layouts Share a frame between pages
Route handlers Add a Python endpoint
Validation and errors 422, 404, HTTPException
Actions Call a Python function from a form or a typed TypeScript function
Linking and navigating Link, client navigation, prefetch
Hooks Read the path, query, cookies and session
Views Choose the format of a page
.nexy files Write a page with Python, Jinja2 and props
Markdown and MDX Write content pages
Components Use Image, Link, Audio, Video, Import
WebSocket Handle a SOCKET connection
i18n Internationalize an application
Databases ORMs and migrations
Recipes Sign in with a session, a JSON API and a file upload, all tested

Choose

Page What you will decide
Routing The file-based or the modular router
Modular routing Controllers and modules
Rendering Which rendering mode fits a page
SSR Server rendering, the default
ISR Cache pages with stale-while-revalidate
CSR Client-side routing
Islands Hydrate on idle, visible or media query
Server mode and client mode useCSR, and what each mode allows
React Use React in a page
Vue Use Vue in a page
Svelte Use Svelte in a page
Solid Use Solid in a page
Preact Use Preact in a page
Nexy and NestJS What matches and what is missing

Go deeper

Page What you will do
Inheritance Layouts, dependencies and error pages in one table
layout.nexy The server-mode layout
layout.tsx The React client-mode layout that owns <html>
layout.vue, layout.svelte Nested layouts for Vue and Svelte
Dependencies and guards dependencies.py and its inheritance
Middleware files middleware.py, inherited by directory
Error pages notfound.nexy, errors.nexy, JSON errors
Error pages per folder Answer 404, 500, 403 and 401 from a folder
Dependency injection Services, scopes, the container
Guards and metadata Protect and document routes

Guides

Page What you will do
Middleware and security CORS, GZip, trusted hosts, sessions
Frontend Vite, styling and the client build
Testing pytest, TestClient and vitest
Dev toolbar The toolbar of nexy dev, and how to turn it off
Coding agents Give Claude Code, Codex and OpenCode the rules of your project
Troubleshooting The first problems people hit, and the fix
Deploy Build, containerise and serve
Performance Defaults, measurements and tuning

Reference

Page What it lists
CLI Commands and flags
Config Every nexyconfig.py field and its default
Python API Every name Nexy exports, by module
Exceptions and errors Every failure, its status, and the file that answers it
File conventions Reserved files and routing rules
Glossary The words these docs use
Security Version floors, rules Nexy follows, audits
Agents Invariants of a Nexy project, for AI agents

Layout

docs/
├─ README.md
├─ getting-started/     installation, quick start, tutorial, project structure, migration
├─ routing/
│  ├─ fbr/              file-based routing
│  │  ├─ modes.md       server mode and client mode
│  │  ├─ inheritance.md layouts, dependencies, error pages
│  │  ├─ pages/         pages, dynamic routes, route groups
│  │  ├─ layouts/       layout.nexy, layout.tsx, layout.vue, layout.svelte
│  │  ├─ handlers/      .py route handlers, validation and errors
│  │  ├─ dependencies/  dependencies.py, guards
│  │  ├─ middleware/    middleware.py
│  │  ├─ errors/        not-found and error pages
│  │  ├─ navigation/    links, hooks
│  │  └─ realtime/      WebSocket
│  └─ modular/          controllers, injection, guards, NestJS comparison
├─ rendering/           SSR, ISR, CSR, islands
├─ views/               .nexy, Markdown, components, one page per client framework
├─ guides/              actions, i18n, databases, middleware, frontend, testing
├─ deployment/          deploy, performance
└─ reference/           CLI, config, file conventions, security, agents

How these pages are written

  • Plain Markdown, rendered by GitHub. No site generator, no build step, no second repository.
  • One question per page. A directory when a feature needs several pages, a file otherwise.
  • A page earns its place in this order: what you will be able to do, the rule in one sentence, a picture when the feature has moving parts, an example you can run, the details, then the tables.
  • Every claim is checked against nexy/. When a page and the code disagree, the code wins.
  • An image in docs/assets/ is an illustration: the site draws the SVG inside the page, so it takes the colours of the theme, and GitHub shows the file itself.
  • Every page ends with the pages that answer the next question.
  • English, like the rest of the repository.

Elsewhere

Edit on GitHub

Enter opens the result, Esc closes.