DocsGetting started

Project structure

Every file in a Nexy project has one job. This page says which.

Top level

my-app/
├─ src/
│  ├─ routes/            file-based routes (FBR)
│  │  ├─ index.nexy      → /
│  │  ├─ layout.nexy     shared layout, not a route
│  │  └─ api/hello.py    → /api/hello
│  ├─ apps/              modular router, decorators (optional, next to routes/)
│  ├─ components/        imported components (a convention, not enforced)
│  └─ globale.css        global styles (created by `nexy new`)
├─ public/               served at /
├─ nexyconfig.py         project configuration
├─ pyproject.toml
├─ package.json          only with a client framework
├─ vite.config.ts        only with a client framework
└─ __nexy__/             build output - generated, never edited

To choose a folder, ask what the file is:

Something the browser can open - a route: src/routes/.
A piece used by several routes - a component or a module: src/components/, src/.
A file served as it is - public/.
A controller of the modular router - src/apps/.
Generated - __nexy__/; never edit it.

`src/routes/`

Every file becomes a route, except the reserved names below. The file path minus the extension is the URL - see routing.

File	Role
`layout.nexy`	wraps sibling and child pages
`errors.nexy`	500 page for the directory
`notfound.nexy`	404 page for the directory
`dependencies.py`	shared FastAPI dependencies for the directory
`__init__.py`	Python package marker
`loading.nexy`	reserved - excluded from routes, but it has no runtime effect yet

Each page name also exists per framework. With react() configured, layout.jsx and layout.tsx are reserved exactly like layout.nexy. The lists are built in nexy/core/config.py (LAYOUT_FILE_NAMES, ERROR_FILE_NAMES, NOTFOUND_FILE_NAMES, LOADING_FILE_NAMES).

`src/apps/`

The directory nexy new uses for the modular router: controllers, modules and providers register their routes through decorators from nexy.decorators, then the aggregate APIRouter is mounted with useRouter in nexyconfig.py.

A project can have both routers: useRouter mounts the modular router, and src/routes/ is scanned whenever that directory exists. See modular routing.

`public/`

Files here are served from the site root: /favicon.ico, /robots.txt, images, fonts.

`nexy/`

Generated by nx build (and by nx dev for the parts it needs). It contains:

the compiled route modules, as a Python package (__nexy__/src/routes/...);
the generated client entry points (main.ts, vite.ts, *.auto.ts);
client/ after a Vite build - assets, manifest, pre-rendered HTML;
build-cache.json.

Treat the whole directory as disposable: delete it, rebuild it. Editing it by hand loses the change on the next build. Add it to .gitignore.

Next steps

Routing: how a path becomes a URL
Config: every project option
Frontend: Vite, styling and the client build

Edit on GitHub