File-based routing for Bini.js, built on React Router's data router. Nested layouts, route groups, parallel and intercepting routes, MDX pages, and Web-standard API routes.
bini-router turns the files in src/app into a route tree with nested layouts, route groups, parallel and intercepting routes, MDX pages, and Web-standard API routes.
>= 8>= 18react-router-dom - a data-router releaseFor MDX and Markdown pages, add the MDX Rollup plugin as a dev dependency:
1. Register the plugin in your Bini.js config:
2. Mount the app in src/main.tsx:
3. Add a page at src/app/page.tsx:
Keep <div id="root"></div> in index.html. Do not import CSS from src/main.*; import global styles from src/app/layout.tsx or a page instead.
The app directory is src/app and the API directory is src/app/api. Neither is configurable.
Files and folders starting with _ or . are ignored, along with node_modules, *.test.*, *.spec.*, *.stories.*, and .md/.mdx docs like README.md. Segments may contain letters, digits,_, and - (up to 100 chars; slot names must start with a letter).
| Pattern | Example | URL |
|---|---|---|
| Static | dashboard/page.tsx or dashboard.tsx | /dashboard |
| Index | blog/index.tsx | /blog |
| Dynamic | blog/[slug].tsx | /blog/:slug |
| Catch-all | docs/[...path]/page.tsx | /docs/* (at least one segment) |
| Optional catch-all | docs/[[...path]]/page.tsx | /docs/* (zero or more) |
Read dynamic parameters with useParams(). For page routes, catch-all segments are exposed under React Router's * key (params['*']), not under the name written in the folder.
Matching order: static first, then dynamic :param, then required catch-alls *, then optional catch-alls **.
A folder wrapped in parentheses, such as (marketing), groups routes and can carry its own layout without adding a URL segment.
Folders using interception syntax (.), (..), (...) are not treated as groups.
A folder prefixed with @ defines a named slot. The slot is passed as a prop to the layout.* in the same directory as the @slot folder:
The slot renders the first entry matching the current URL, then the slot's own default.*, then a built-in empty fallback. A slot needs a receiving layout next to the @slot folder. Data exports in slot pages are not executed.
Folders or flat files prefixed with (.), (..), or (...) render alternative content at a URL when the previous in-app location matches the interceptor's source route. Direct visits and reloads render the real page.
| Prefix | Intercepts |
|---|---|
| (.)name | Sibling of current segment (same level) |
| (..)name | One level up |
| (...)name | Root of app |
If no real page exists at the target URL, the interceptor's page is registered as the route and the not-found page is shown for direct visits. Data exports in interceptors are not executed.
Layouts wrap every page in their directory and below. They receive params, any parallel-route slots, and children. Render either <Outlet /> or {children}.
A template.* file wraps each page inside the layout chain. Templates receive children only. The nearest usable template wins.
Layouts that contain an <html> element, or have no default export, are excluded from the chain. The same check applies to templates and to loading, error, not-found, global-error, and default files.
Pages and layouts can export loader, action, shouldRevalidate, ErrorBoundary, HydrateFallback / hydrateFallbackElement, and handle. They are wired into the generated data router.
Routes whose page or layouts have data exports are marked clientOnly and are not server-rendered: the static renderer does not run React Router lazy routes.
loading, error, and not-found files use nearest-wins resolution: a file in a subfolder applies to routes in that subfolder and shadows its ancestors. Built-in defaults are used when none is found.
| File | Behavior |
|---|---|
| loading.* | Suspense fallback for pages and layouts in scope. |
| not-found.* | Handles unmatched URLs under its folder (wrapped in that folder's layouts) and 404 responses thrown from routes. |
| error.* | Receives { error, reset } and catches render errors and route errors. Boundaries reset on navigation and HMR updates. |
| global-error.* | Fallback, in the app root, for errors that reach the root route. |
| default.* | Inside a @slot folder, renders when no slot route matches. |
In development, runtime errors are also dispatched as a __bini_error__ event on window.
Static extraction applies to .tsx, .jsx, .ts, and .js files. .mdx and .md pages do not support metadata, document, or CSS extraction.
Export metadata from any layout or page. It is statically extracted, merged from the outermost layout to the page, and removed from the client bundle. Object values are merged one level deep; later entries win.
Values must be statically evaluable: literals, template literals, arrays, objects, module-scope const references, TypeScript as / satisfies wrappers, and JSON.stringify of static values. Non-static properties are skipped.
Use document for head tags that must appear in both development and production, and for <html> / <body> attributes. The export is removed from the client bundle. The nearest document export (page first, then the closest layout) is used; documents are not merged.
| Key | Applied in dev | Applied at build |
|---|---|---|
| head | Yes | Yes |
| html, body | Yes | Yes |
| metadata | Title only (client-side) | Yes |
Attribute values and children must be static, otherwise they are dropped. dangerouslySetInnerHTML={{ __html: <static value> }} is supported for JSON-LD scripts.
| Export | Behavior |
|---|---|
| staticParams | A function (sync or async) exported from a dynamic page that lists the URLs to pre-render. |
| prerender = false | Marks a route as opted out of pre-rendering. |
Place .ts or .js files in src/app/api/. Every handler receives a standard Request and a context object: { params, searchParams, env, waitUntil? }.
| File | Route |
|---|---|
| api/users.ts | /api/users |
| api/users/route.ts | /api/users |
| api/posts/index.ts | /api/posts |
| api/posts/[id].ts | /api/posts/:id |
| api/[...catch].ts | /api/* |
| api/(internal)/health.ts | /api/health |
If a file exports method handlers, other methods receive 405 with an Allow header, and HEAD falls back to GET. Method exports take precedence over a default export. Routes in .fetch() objects are written without the /api prefix.
| Option | Type | Default | Description |
|---|---|---|---|
| cors | boolean | object | false | Adds CORS headers to API responses. true allows any origin with standard methods and Content-Type, Authorization, X-Request-ID headers. origin accepts a string or a list matched per request. |
| trustProxy | boolean | false | Builds the request origin from X-Forwarded-Host and X-Forwarded-Proto in dev and preview. The forwarded host must still pass the allow-list. |
| bodySizeLimit | number | false | 1048576 | Maximum API request body in bytes. false, 0, or Infinity disable the limit. |
Everything else is fixed by convention: directories, the router basename (derived from Vite's base), auto-import presets, MDX options, route prefetching, and the built-in SSR entry. Prefetching on link hover and focus can be disabled per link with data-no-prefetch.
File-based routing for Bini.js, built on React Router's data router. Nested layouts, route groups, parallel and intercepting routes, MDX pages, and Web-standard API routes.
bini-router turns the files in src/app into a route tree with nested layouts, route groups, parallel and intercepting routes, MDX pages, and Web-standard API routes.
>= 8>= 18react-router-dom - a data-router releaseFor MDX and Markdown pages, add the MDX Rollup plugin as a dev dependency:
1. Register the plugin in your Bini.js config:
2. Mount the app in src/main.tsx:
3. Add a page at src/app/page.tsx:
Keep <div id="root"></div> in index.html. Do not import CSS from src/main.*; import global styles from src/app/layout.tsx or a page instead.
The app directory is src/app and the API directory is src/app/api. Neither is configurable.
Files and folders starting with _ or . are ignored, along with node_modules, *.test.*, *.spec.*, *.stories.*, and .md/.mdx docs like README.md. Segments may contain letters, digits,_, and - (up to 100 chars; slot names must start with a letter).
| Pattern | Example | URL |
|---|---|---|
| Static | dashboard/page.tsx or dashboard.tsx | /dashboard |
| Index | blog/index.tsx | /blog |
| Dynamic | blog/[slug].tsx | /blog/:slug |
| Catch-all | docs/[...path]/page.tsx | /docs/* (at least one segment) |
| Optional catch-all | docs/[[...path]]/page.tsx | /docs/* (zero or more) |
Read dynamic parameters with useParams(). For page routes, catch-all segments are exposed under React Router's * key (params['*']), not under the name written in the folder.
Matching order: static first, then dynamic :param, then required catch-alls *, then optional catch-alls **.
A folder wrapped in parentheses, such as (marketing), groups routes and can carry its own layout without adding a URL segment.
Folders using interception syntax (.), (..), (...) are not treated as groups.
A folder prefixed with @ defines a named slot. The slot is passed as a prop to the layout.* in the same directory as the @slot folder:
The slot renders the first entry matching the current URL, then the slot's own default.*, then a built-in empty fallback. A slot needs a receiving layout next to the @slot folder. Data exports in slot pages are not executed.
Folders or flat files prefixed with (.), (..), or (...) render alternative content at a URL when the previous in-app location matches the interceptor's source route. Direct visits and reloads render the real page.
| Prefix | Intercepts |
|---|---|
| (.)name | Sibling of current segment (same level) |
| (..)name | One level up |
| (...)name | Root of app |
If no real page exists at the target URL, the interceptor's page is registered as the route and the not-found page is shown for direct visits. Data exports in interceptors are not executed.
Layouts wrap every page in their directory and below. They receive params, any parallel-route slots, and children. Render either <Outlet /> or {children}.
A template.* file wraps each page inside the layout chain. Templates receive children only. The nearest usable template wins.
Layouts that contain an <html> element, or have no default export, are excluded from the chain. The same check applies to templates and to loading, error, not-found, global-error, and default files.
Pages and layouts can export loader, action, shouldRevalidate, ErrorBoundary, HydrateFallback / hydrateFallbackElement, and handle. They are wired into the generated data router.
Routes whose page or layouts have data exports are marked clientOnly and are not server-rendered: the static renderer does not run React Router lazy routes.
loading, error, and not-found files use nearest-wins resolution: a file in a subfolder applies to routes in that subfolder and shadows its ancestors. Built-in defaults are used when none is found.
| File | Behavior |
|---|---|
| loading.* | Suspense fallback for pages and layouts in scope. |
| not-found.* | Handles unmatched URLs under its folder (wrapped in that folder's layouts) and 404 responses thrown from routes. |
| error.* | Receives { error, reset } and catches render errors and route errors. Boundaries reset on navigation and HMR updates. |
| global-error.* | Fallback, in the app root, for errors that reach the root route. |
| default.* | Inside a @slot folder, renders when no slot route matches. |
In development, runtime errors are also dispatched as a __bini_error__ event on window.
Static extraction applies to .tsx, .jsx, .ts, and .js files. .mdx and .md pages do not support metadata, document, or CSS extraction.
Export metadata from any layout or page. It is statically extracted, merged from the outermost layout to the page, and removed from the client bundle. Object values are merged one level deep; later entries win.
Values must be statically evaluable: literals, template literals, arrays, objects, module-scope const references, TypeScript as / satisfies wrappers, and JSON.stringify of static values. Non-static properties are skipped.
Use document for head tags that must appear in both development and production, and for <html> / <body> attributes. The export is removed from the client bundle. The nearest document export (page first, then the closest layout) is used; documents are not merged.
| Key | Applied in dev | Applied at build |
|---|---|---|
| head | Yes | Yes |
| html, body | Yes | Yes |
| metadata | Title only (client-side) | Yes |
Attribute values and children must be static, otherwise they are dropped. dangerouslySetInnerHTML={{ __html: <static value> }} is supported for JSON-LD scripts.
| Export | Behavior |
|---|---|
| staticParams | A function (sync or async) exported from a dynamic page that lists the URLs to pre-render. |
| prerender = false | Marks a route as opted out of pre-rendering. |
Place .ts or .js files in src/app/api/. Every handler receives a standard Request and a context object: { params, searchParams, env, waitUntil? }.
| File | Route |
|---|---|
| api/users.ts | /api/users |
| api/users/route.ts | /api/users |
| api/posts/index.ts | /api/posts |
| api/posts/[id].ts | /api/posts/:id |
| api/[...catch].ts | /api/* |
| api/(internal)/health.ts | /api/health |
If a file exports method handlers, other methods receive 405 with an Allow header, and HEAD falls back to GET. Method exports take precedence over a default export. Routes in .fetch() objects are written without the /api prefix.
| Option | Type | Default | Description |
|---|---|---|---|
| cors | boolean | object | false | Adds CORS headers to API responses. true allows any origin with standard methods and Content-Type, Authorization, X-Request-ID headers. origin accepts a string or a list matched per request. |
| trustProxy | boolean | false | Builds the request origin from X-Forwarded-Host and X-Forwarded-Proto in dev and preview. The forwarded host must still pass the allow-list. |
| bodySizeLimit | number | false | 1048576 | Maximum API request body in bytes. false, 0, or Infinity disable the limit. |
Everything else is fixed by convention: directories, the router basename (derived from Vite's base), auto-import presets, MDX options, route prefetching, and the built-in SSR entry. Prefetching on link hover and focus can be disabled per link with data-no-prefetch.