DocsPluginsShowcaseReleases
npmStar us on GitHub
overviewcreate-bini-appbini-deploybini-routerbini-envbini-nativebini-serverbini-overlaybini-ssgvite plugins↗hono plugins↗

A native React framework for building cross-platform applications from a single codebase.

Resources

  • Documentation
  • Plugins
  • Showcase
  • Releases

Community

  • GitHub Discussions
  • Reddit
  • Discord
  • LinkedIn

More

  • npm
  • GitHub
  • Issues
  • License

© 2026 Bini Cooperation.

bini-router

Official

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.

Overview

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.

Requirements

  • Vite >= 8
  • React >= 18
  • react-router-dom - a data-router release

Install

>_Terminal
$ npm install bini-router react-router-dom

For MDX and Markdown pages, add the MDX Rollup plugin as a dev dependency:

>_Terminal
$ npm install -D @mdx-js/rollup

Setup

1. Register the plugin in your Bini.js config:

vite.config.ts
import { defineConfig } from 'vite'
import react from '@vitejs/plugin-react'
import { biniroute } from 'bini-router'

export default defineConfig({
  plugins: [react(), biniroute()],
})

2. Mount the app in src/main.tsx:

src/main.tsx
import { createRoot } from 'react-dom/client'
import App, { rootOptions } from 'virtual:bini-app'

createRoot(document.getElementById('root')!, rootOptions).render(<App />)

3. Add a page at src/app/page.tsx:

src/app/page.tsx
export default function Home() {
  return <h1>Hello</h1>
}

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.

Project Structure

src
main.tsx
app
ƒlayout.tsx
ƒpage.tsx
about.mdx
(marketing)
ƒpricing/page.tsx
dashboard
ƒlayout.tsx
ƒpage.tsx
loading.tsx
ƒ[id]/page.tsx
inbox
ƒlayout.tsx
ƒpage.tsx
@sidebar
ƒdefault.tsx
ƒpage.tsx
blog
ƒindex.tsx
ƒ[slug].tsx
not-found.tsx
ƒdocs/[...path]/page.tsx
api
ƒusers.ts
ƒposts/[id].ts

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).

Routing

PatternExampleURL
Staticdashboard/page.tsx or dashboard.tsx/dashboard
Indexblog/index.tsx/blog
Dynamicblog/[slug].tsx/blog/:slug
Catch-alldocs/[...path]/page.tsx/docs/* (at least one segment)
Optional catch-alldocs/[[...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.

src/app/blog/[slug]/page.tsx
export default function Post() {
  const { slug } = useParams()
  return <h1>Post: {slug}</h1>
}

Matching order: static first, then dynamic :param, then required catch-alls *, then optional catch-alls **.

Route Groups

A folder wrapped in parentheses, such as (marketing), groups routes and can carry its own layout without adding a URL segment.

app
(marketing)
ƒlayout.tsx
ƒpricing/page.tsx
(app)
ƒlayout.tsx
ƒsettings/page.tsx

Folders using interception syntax (.), (..), (...) are not treated as groups.

Parallel Routes

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:

src/app/inbox/layout.tsx
export default function InboxLayout({ sidebar }) {
  return (
    <div className="grid">
      <aside>{sidebar}</aside>
      <main><Outlet /></main>
    </div>
  )
}
app
inbox
ƒlayout.tsx
ƒpage.tsx
@sidebar
ƒdefault.tsx
ƒpage.tsx

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.

Intercepting Routes

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.

PrefixIntercepts
(.)nameSibling of current segment (same level)
(..)nameOne level up
(...)nameRoot 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 and Templates

Layouts wrap every page in their directory and below. They receive params, any parallel-route slots, and children. Render either <Outlet /> or {children}.

src/app/dashboard/layout.tsx
export default function DashboardLayout({ params }) {
  return (
    <div className="dashboard">
      <aside>Sidebar</aside>
      <main><Outlet /></main>
    </div>
  )
}

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.

Route Data Exports

Pages and layouts can export loader, action, shouldRevalidate, ErrorBoundary, HydrateFallback / hydrateFallbackElement, and handle. They are wired into the generated data router.

src/app/users/page.tsx
export async function loader() {
  const res = await fetch('/api/users')
  return res.json()
}

export default function Users() {
  const users = useLoaderData()
  return <ul>{users.map((u) => <li key={u.id}>{u.name}</li>)}</ul>
}

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, Not Found, and Error Boundaries

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.

FileBehavior
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.

Metadata and Document

Static extraction applies to .tsx, .jsx, .ts, and .js files. .mdx and .md pages do not support metadata, document, or CSS extraction.

metadata

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.

src/app/layout.tsx
export const metadata = {
  title: { default: 'My App', template: '%s | My App' },
  description: 'Built with bini-router',
}

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.

document

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.

src/app/layout.tsx
export const document = {
  html: { lang: 'en' },
  body: { class: 'antialiased' },
  head: (
    <>
      <title>My App</title>
      <meta name="description" content="Built with bini-router" />
      <link rel="icon" href="/favicon.ico" />
    </>
  ),
}
KeyApplied in devApplied at build
headYesYes
html, bodyYesYes
metadataTitle 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.

Static Params and Prerender

ExportBehavior
staticParamsA function (sync or async) exported from a dynamic page that lists the URLs to pre-render.
prerender = falseMarks a route as opted out of pre-rendering.

API Routes

Place .ts or .js files in src/app/api/. Every handler receives a standard Request and a context object: { params, searchParams, env, waitUntil? }.

FileRoute
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

Three handler styles

Per-method exports
export function GET(req, { params }) {
  return Response.json({ id: params.id })
}
Default function (plain values as JSON)
export default function handler() {
  return { ok: true }
}
.fetch() object (Hono app)
import { Hono } from 'hono'
const app = new Hono()
app.all('/hello', (c) => c.json({ message: 'Hello' }))
export default app

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.

Configuration

vite.config.ts
biniroute({
  cors: false,
  trustProxy: false,
  bodySizeLimit: 1024 * 1024,
})
OptionTypeDefaultDescription
corsboolean | objectfalseAdds 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.
trustProxybooleanfalseBuilds the request origin from X-Forwarded-Host and X-Forwarded-Proto in dev and preview. The forwarded host must still pass the allow-list.
bodySizeLimitnumber | false1048576Maximum 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.

Was this helpful?
Previousbini-deploy
Nextbini-env

On this page

  • Overview
  • Requirements
  • Install
  • Setup
  • Project Structure
  • Routing
  • Route Groups
  • Parallel Routes
  • Intercepting Routes
  • Layouts and Templates
  • Route Data Exports
  • Boundaries
  • Metadata and Document
  • Static Params and Prerender
  • API Routes
  • Configuration
Edit this page on GitHub

bini-router

Official

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.

Overview

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.

Requirements

  • Vite >= 8
  • React >= 18
  • react-router-dom - a data-router release

Install

>_Terminal
$ npm install bini-router react-router-dom

For MDX and Markdown pages, add the MDX Rollup plugin as a dev dependency:

>_Terminal
$ npm install -D @mdx-js/rollup

Setup

1. Register the plugin in your Bini.js config:

vite.config.ts
import { defineConfig } from 'vite'
import react from '@vitejs/plugin-react'
import { biniroute } from 'bini-router'

export default defineConfig({
  plugins: [react(), biniroute()],
})

2. Mount the app in src/main.tsx:

src/main.tsx
import { createRoot } from 'react-dom/client'
import App, { rootOptions } from 'virtual:bini-app'

createRoot(document.getElementById('root')!, rootOptions).render(<App />)

3. Add a page at src/app/page.tsx:

src/app/page.tsx
export default function Home() {
  return <h1>Hello</h1>
}

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.

Project Structure

src
main.tsx
app
ƒlayout.tsx
ƒpage.tsx
about.mdx
(marketing)
ƒpricing/page.tsx
dashboard
ƒlayout.tsx
ƒpage.tsx
loading.tsx
ƒ[id]/page.tsx
inbox
ƒlayout.tsx
ƒpage.tsx
@sidebar
ƒdefault.tsx
ƒpage.tsx
blog
ƒindex.tsx
ƒ[slug].tsx
not-found.tsx
ƒdocs/[...path]/page.tsx
api
ƒusers.ts
ƒposts/[id].ts

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).

Routing

PatternExampleURL
Staticdashboard/page.tsx or dashboard.tsx/dashboard
Indexblog/index.tsx/blog
Dynamicblog/[slug].tsx/blog/:slug
Catch-alldocs/[...path]/page.tsx/docs/* (at least one segment)
Optional catch-alldocs/[[...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.

src/app/blog/[slug]/page.tsx
export default function Post() {
  const { slug } = useParams()
  return <h1>Post: {slug}</h1>
}

Matching order: static first, then dynamic :param, then required catch-alls *, then optional catch-alls **.

Route Groups

A folder wrapped in parentheses, such as (marketing), groups routes and can carry its own layout without adding a URL segment.

app
(marketing)
ƒlayout.tsx
ƒpricing/page.tsx
(app)
ƒlayout.tsx
ƒsettings/page.tsx

Folders using interception syntax (.), (..), (...) are not treated as groups.

Parallel Routes

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:

src/app/inbox/layout.tsx
export default function InboxLayout({ sidebar }) {
  return (
    <div className="grid">
      <aside>{sidebar}</aside>
      <main><Outlet /></main>
    </div>
  )
}
app
inbox
ƒlayout.tsx
ƒpage.tsx
@sidebar
ƒdefault.tsx
ƒpage.tsx

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.

Intercepting Routes

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.

PrefixIntercepts
(.)nameSibling of current segment (same level)
(..)nameOne level up
(...)nameRoot 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 and Templates

Layouts wrap every page in their directory and below. They receive params, any parallel-route slots, and children. Render either <Outlet /> or {children}.

src/app/dashboard/layout.tsx
export default function DashboardLayout({ params }) {
  return (
    <div className="dashboard">
      <aside>Sidebar</aside>
      <main><Outlet /></main>
    </div>
  )
}

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.

Route Data Exports

Pages and layouts can export loader, action, shouldRevalidate, ErrorBoundary, HydrateFallback / hydrateFallbackElement, and handle. They are wired into the generated data router.

src/app/users/page.tsx
export async function loader() {
  const res = await fetch('/api/users')
  return res.json()
}

export default function Users() {
  const users = useLoaderData()
  return <ul>{users.map((u) => <li key={u.id}>{u.name}</li>)}</ul>
}

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, Not Found, and Error Boundaries

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.

FileBehavior
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.

Metadata and Document

Static extraction applies to .tsx, .jsx, .ts, and .js files. .mdx and .md pages do not support metadata, document, or CSS extraction.

metadata

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.

src/app/layout.tsx
export const metadata = {
  title: { default: 'My App', template: '%s | My App' },
  description: 'Built with bini-router',
}

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.

document

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.

src/app/layout.tsx
export const document = {
  html: { lang: 'en' },
  body: { class: 'antialiased' },
  head: (
    <>
      <title>My App</title>
      <meta name="description" content="Built with bini-router" />
      <link rel="icon" href="/favicon.ico" />
    </>
  ),
}
KeyApplied in devApplied at build
headYesYes
html, bodyYesYes
metadataTitle 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.

Static Params and Prerender

ExportBehavior
staticParamsA function (sync or async) exported from a dynamic page that lists the URLs to pre-render.
prerender = falseMarks a route as opted out of pre-rendering.

API Routes

Place .ts or .js files in src/app/api/. Every handler receives a standard Request and a context object: { params, searchParams, env, waitUntil? }.

FileRoute
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

Three handler styles

Per-method exports
export function GET(req, { params }) {
  return Response.json({ id: params.id })
}
Default function (plain values as JSON)
export default function handler() {
  return { ok: true }
}
.fetch() object (Hono app)
import { Hono } from 'hono'
const app = new Hono()
app.all('/hello', (c) => c.json({ message: 'Hello' }))
export default app

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.

Configuration

vite.config.ts
biniroute({
  cors: false,
  trustProxy: false,
  bodySizeLimit: 1024 * 1024,
})
OptionTypeDefaultDescription
corsboolean | objectfalseAdds 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.
trustProxybooleanfalseBuilds the request origin from X-Forwarded-Host and X-Forwarded-Proto in dev and preview. The forwarded host must still pass the allow-list.
bodySizeLimitnumber | false1048576Maximum 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.

Was this helpful?
Previousbini-deploy
Nextbini-env

On this page

  • Overview
  • Requirements
  • Install
  • Setup
  • Project Structure
  • Routing
  • Route Groups
  • Parallel Routes
  • Intercepting Routes
  • Layouts and Templates
  • Route Data Exports
  • Boundaries
  • Metadata and Document
  • Static Params and Prerender
  • API Routes
  • Configuration
Edit this page on GitHub