The folders and files in a Bini.js project, and how they turn into routes.
Bini.js uses a file-system router. Everything the router reads lives in src/app: add a file there and you get a page, add a file to src/app/api and you get an endpoint. There is no router configuration to write.
A project has three kinds of files: routing files that turn into URLs, top-level files that configure tooling, and everything else - components, helpers, and data - which you organize however you like.
This is the src folder created by npx create-bini-app@latest.
| Path | What it does |
|---|---|
| src/app | Your routes and layouts. The router scans this folder. |
| src/app/api | API handlers. hello.ts is served at /api/hello. |
| src/app/layout.tsx | Root layout. Wraps every page and holds global metadata. |
| src/app/page.tsx | The home page, served at /. |
| src/app/globals.css | Global styles imported by the root layout. |
| src/main.tsx | App entry point. Mounts the app in the browser and handles hydration. |
| public | Static assets served from the site root, such as favicon.ico and site.webmanifest. |
Files in the project root configure tooling. None of them affect routing.
| File | Purpose |
|---|---|
| vite.config.ts | Vite configuration. Registers the router, environment plugin, and other tooling. |
| package.json | Dependencies and scripts such as dev, build, and deploy. |
| .env | Environment variables. BINI_* is exposed to the browser, everything else stays on the server. |
| .oxlintrc.json | Oxlint configuration. |
| .oxfmtrc.json | Oxfmt configuration. |
Some file names have a fixed job inside src/app. A routing file applies to its own folder and every folder below it. A file in a subfolder overrides the same file from a parent, and if none exists Bini.js falls back to a built-in default.
These files wrap a page in a fixed order. The layout is outermost. Inside it, an error boundary catches errors and shows error.tsx, and a Suspense boundary shows loading.tsx while the page loads. The template wraps the page itself, and the page is the innermost piece. not-found.tsx is not part of this wrapper. It renders when no route matches, inside the same layout chain.
| File | Purpose |
|---|---|
| page.tsx | The UI for a route. Can also be .mdx or .md. |
| layout.tsx | Shared UI for a folder and its children. Renders children through <Outlet />. |
| template.tsx | Like a layout, but wraps each page individually. |
| loading.tsx | Fallback shown while a page or layout loads. |
| error.tsx | Fallback shown when something in the folder throws. |
| not-found.tsx | UI for URLs that match no route under the folder. |
| default.tsx | Fallback for a parallel route slot with no match. |
page files can be MDX or Markdown. Every other routing file must be .tsx, .jsx, .ts, or .js.Folders define URL segments, and nesting folders nests segments. A file becomes a route in two ways: a page file inside a folder, or a flat file placed directly in a folder. A file named index is treated the same as page and maps to its parent folder.
A page.tsx in the root is the home page. A flat file such as about.tsx becomes /about without needing its own folder. Inside blog, page.tsx maps to /blog, and [slug].tsx is a dynamic route where :slug matches any value. A layout.tsx has no URL of its own. It wraps its folder's routes and everything below them.
You can keep components, helpers, and data files next to the routes that use them. Anything starting with _ or . is skipped by the router, along with everything inside it. Prefix a folder with an underscore, such as _components, to mark it as a private implementation detail.
Files inside a private folder, like button.tsx and constants.ts, never produce a URL. The same goes for files with an underscore prefix, like _nav.tsx and _db.ts. The routable files next to them, page.tsx and hello.ts, keep working as normal, so a route can hold its own helpers without exposing them.
Wrap a folder name in parentheses, such as (marketing), to organize routes without changing their URLs. The group name is dropped from the path, and the group can have its own layout, loading, and error files.
Because the group name is dropped, the pages get plain URLs: /about and /cart. Each group's layout.tsx only wraps the routes inside that group, so marketing pages and shop pages can share one URL space while looking completely different.
Create your first pages and wrap them in shared layouts.
Define routes from the filesystem with folder-based and file-based conventions.
Add backend endpoints with plain functions or a full Hono app.
Pre-render every route to HTML at build time, ready for any static host.
Deploy to Node, Vercel, Netlify, Cloudflare, or Deno, or build native apps in CI.
Build for web, Windows, macOS, Linux, Android, or iOS from one codebase.
The folders and files in a Bini.js project, and how they turn into routes.
Bini.js uses a file-system router. Everything the router reads lives in src/app: add a file there and you get a page, add a file to src/app/api and you get an endpoint. There is no router configuration to write.
A project has three kinds of files: routing files that turn into URLs, top-level files that configure tooling, and everything else - components, helpers, and data - which you organize however you like.
This is the src folder created by npx create-bini-app@latest.
| Path | What it does |
|---|---|
| src/app | Your routes and layouts. The router scans this folder. |
| src/app/api | API handlers. hello.ts is served at /api/hello. |
| src/app/layout.tsx | Root layout. Wraps every page and holds global metadata. |
| src/app/page.tsx | The home page, served at /. |
| src/app/globals.css | Global styles imported by the root layout. |
| src/main.tsx | App entry point. Mounts the app in the browser and handles hydration. |
| public | Static assets served from the site root, such as favicon.ico and site.webmanifest. |
Files in the project root configure tooling. None of them affect routing.
| File | Purpose |
|---|---|
| vite.config.ts | Vite configuration. Registers the router, environment plugin, and other tooling. |
| package.json | Dependencies and scripts such as dev, build, and deploy. |
| .env | Environment variables. BINI_* is exposed to the browser, everything else stays on the server. |
| .oxlintrc.json | Oxlint configuration. |
| .oxfmtrc.json | Oxfmt configuration. |
Some file names have a fixed job inside src/app. A routing file applies to its own folder and every folder below it. A file in a subfolder overrides the same file from a parent, and if none exists Bini.js falls back to a built-in default.
These files wrap a page in a fixed order. The layout is outermost. Inside it, an error boundary catches errors and shows error.tsx, and a Suspense boundary shows loading.tsx while the page loads. The template wraps the page itself, and the page is the innermost piece. not-found.tsx is not part of this wrapper. It renders when no route matches, inside the same layout chain.
| File | Purpose |
|---|---|
| page.tsx | The UI for a route. Can also be .mdx or .md. |
| layout.tsx | Shared UI for a folder and its children. Renders children through <Outlet />. |
| template.tsx | Like a layout, but wraps each page individually. |
| loading.tsx | Fallback shown while a page or layout loads. |
| error.tsx | Fallback shown when something in the folder throws. |
| not-found.tsx | UI for URLs that match no route under the folder. |
| default.tsx | Fallback for a parallel route slot with no match. |
page files can be MDX or Markdown. Every other routing file must be .tsx, .jsx, .ts, or .js.Folders define URL segments, and nesting folders nests segments. A file becomes a route in two ways: a page file inside a folder, or a flat file placed directly in a folder. A file named index is treated the same as page and maps to its parent folder.
A page.tsx in the root is the home page. A flat file such as about.tsx becomes /about without needing its own folder. Inside blog, page.tsx maps to /blog, and [slug].tsx is a dynamic route where :slug matches any value. A layout.tsx has no URL of its own. It wraps its folder's routes and everything below them.
You can keep components, helpers, and data files next to the routes that use them. Anything starting with _ or . is skipped by the router, along with everything inside it. Prefix a folder with an underscore, such as _components, to mark it as a private implementation detail.
Files inside a private folder, like button.tsx and constants.ts, never produce a URL. The same goes for files with an underscore prefix, like _nav.tsx and _db.ts. The routable files next to them, page.tsx and hello.ts, keep working as normal, so a route can hold its own helpers without exposing them.
Wrap a folder name in parentheses, such as (marketing), to organize routes without changing their URLs. The group name is dropped from the path, and the group can have its own layout, loading, and error files.
Because the group name is dropped, the pages get plain URLs: /about and /cart. Each group's layout.tsx only wraps the routes inside that group, so marketing pages and shop pages can share one URL space while looking completely different.
Create your first pages and wrap them in shared layouts.
Define routes from the filesystem with folder-based and file-based conventions.
Add backend endpoints with plain functions or a full Hono app.
Pre-render every route to HTML at build time, ready for any static host.
Deploy to Node, Vercel, Netlify, Cloudflare, or Deno, or build native apps in CI.
Build for web, Windows, macOS, Linux, Android, or iOS from one codebase.