DocsPluginsShowcaseReleases
npmStar us on GitHub

Getting Started

IntroductionInstallationProject StructureLayouts and PagesLinking and Navigating

Routing

Folder-Based RoutingFile-Based RoutingDynamic RoutesParallel RoutesIntercepting RoutesCatch-All RoutesMDX & Markdown Pages

Special Files

Loading UIError BoundariesTemplateDefaultNot Found

Data Fetching

LoadersActionsAccessing Route Data

Metadata

Metadata & SEOOpen Graph & TwitterIcons & Favicons

API Routes

API Routes OverviewPlain Function HandlersHono IntegrationDynamic API Routes

Environment Variables

OverviewPrefixes & Client ExposureUsing in API Routes

Styling

CSS OverviewTailwind CSSCSS Modules

Platforms

WebWindowsmacOSLinuxAndroidiOS

Deployment

Deployment OverviewProduction ServerStatic ExportHosting Providers

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.

Static Export

Pre-render your Bini.js app to static HTML, ready for any static host.

Pre-rendering is built into the production build. Every route that can be rendered is rendered to HTML during vite build and written into dist/, so the first paint delivers real content while React hydrates in the background.

There is no separate export command and no export mode to enable. The same build that bundles your client also produces the pre-rendered pages.

How It Works

During the build, each of the following steps runs in order:

src
app
page.tsx
blog
page.tsx
[slug]
page.tsx
/
/blog
/blog/:slug
  • Reads your routes from the router, so static routes and dynamic patterns are both known.
  • Expands staticParams so dynamic routes that export it become concrete URLs.
  • Renders each URL through the built-in SSR entry and writes the resulting HTML into dist/.
  • Crawls every rendered page for internal links and renders those URLs too.
  • Writes shell pages for routes that cannot be rendered server-side.
  • Injects metadata and route-scoped CSS, and writes a 404.html.

staticParams

Export staticParams from a dynamic page to declare which URLs should be pre-rendered. It works independently of link crawling, so you can guarantee coverage of every known parameter.

src/app/blog/[slug]/page.tsx
// src/app/blog/[slug]/page.tsx
export async function staticParams() {
  return [{ slug: 'hello-world' }, { slug: 'second-post' }]
}

Each object is substituted into the route pattern. Named segments such as :slug accept a string or number. A trailing * or ** accepts the '*' key, as either an array of segments or a string that is split on /.

A dynamic route without staticParams that no rendered page links to will only get a shell page. To pre-render it as full HTML, list its URLs in staticParams or link to it from a rendered page.

prerender = false

Opt a page out of server rendering by exporting prerender = false:

src/app/admin/page.tsx
// src/app/admin/page.tsx
export const prerender = false

A shell page is still written at that URL, but the SSR renderer is never called for it. Use this for pages that only make sense on the client, such as authenticated dashboards or views that depend on browser APIs.

Build Command

Build your app for production. The client, the server bundle, and all pre-rendered HTML are produced in a single pass.

>_Terminal
$ npm run build

To serve the build on a Node.js host, use the start command. It runs the production server, which serves the pre-rendered pages and the compiled API together:

>_Terminal
$ npm run start
CommandPurpose
npm run buildBuilds the client, builds the server bundle, and pre-renders every route to dist/.
npm run startServes the built app on a Node.js server, including API routes.

Output Structure

Each route is written as its own folder with an index.html. Highlighted files were produced by crawling or expanded from staticParams. The [slug] and [...slug] folders are shell fallbacks for dynamic routes that were never pre-rendered.

dist
index.html
about
index.html
blog
index.html
my-first-post
index.html
hello-world
index.html
[slug]
index.html
docs
getting-started
index.html
[...slug]
index.html
404.html
api
index.mjs
index-[hash].js
index-[hash].css
/
/about
/blog
/blog/my-first-post
/blog/hello-world
/blog/:slug
/docs/getting-started
/docs/*
A dynamic route that is linked from a rendered page, or listed in staticParams, is written as full HTML. Everything else falls back to a shell page.

Crawling & Shell Fallback

After rendering static routes and any staticParams URLs, the build reads each rendered page for internal links and renders those URLs as well:

dist/blog/index.html
<a href="/blog/my-first-post">
<a href="/blog/hello-world">
Discovered and pre-rendered
/blog/my-first-postdist/blog/my-first-post/index.html
/blog/hello-worlddist/blog/hello-world/index.html

This repeats until no new URLs are discovered. Some routes cannot be rendered server-side - those with prerender = false, client-only routes with data exports such as loader, and dynamic patterns that no page links to and that are not listed in staticParams. Each of those receives a shell page with an empty #root and this marker in <head>:

<script>window.__BINI_SHELL__=true;</script>
Linked dynamic routes are fully pre-rendered, so they load instantly and are indexed by search engines. Unlinked ones still work through the shell fallback - no 404, and they hydrate on the client.

Client Entry & Hydration

The marker script only sets a flag. The client entry decides how to mount the app based on it:

  • If window.__BINI_SHELL__ === true, or #root is empty, call createRoot(root).render(<App />).
  • Otherwise call hydrateRoot(root, <App />).

A pre-rendered page already contains its markup, so hydrating it attaches the client app without a second render. A shell page has an empty #root, so attempting to hydrate it would fail - hence the flag.

404 Handling

404.html is always written to dist/. What goes inside depends on your app:

src
app
not-found.tsx
dist
404.html
index.html
SituationWhat gets written to 404.html
src/app/not-found.tsxYour custom not-found page, pre-rendered to HTML.
No custom not-found fileThe built-in 404 page.
Rendering /404 failsA shell page - not counted as a build failure.

Static Hosts

The Web build can be served directly from any static host. Both static and dynamic routes work:

HostStatic routesDynamic routes
GitHub Pages✓ pre-rendered✓ crawled + pre-rendered, shell fallback
AWS S3 + CloudFront✓ pre-rendered✓ crawled + pre-rendered, shell fallback
Firebase Hosting✓ pre-rendered✓ crawled + pre-rendered, shell fallback
Surge.sh✓ pre-rendered✓ crawled + pre-rendered, shell fallback

Complete Example

Deploy to GitHub Pages. If your site is served under a subpath, set base in vite.config.ts first:

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

export default defineConfig({
  base: '/my-app/',  // GitHub Pages subpath
  plugins: [
    react(),
    // ...your other plugins
  ],
})

Build the app, then push the contents of dist/ to your GitHub Pages branch (or upload them through the GitHub Pages UI).

>_Terminal
$ npm run build

Deployment Overview

Where to deploy a Bini.js app.

Production Server

Run the production server for Node.js hosting.

Hosting Providers

Platform-specific deployment notes.

Layouts and Pages

How routes map to pages in the app directory.

Was this helpful?
PreviousProduction Server
NextHosting Providers

On this page

  • Overview
  • How It Works
  • staticParams
  • prerender = false
  • Build Command
  • Output Structure
  • Crawling & Shell Fallback
  • Client Entry & Hydration
  • 404 Handling
  • Static Hosts
  • Complete Example
Edit this page on GitHub

Static Export

Pre-render your Bini.js app to static HTML, ready for any static host.

Pre-rendering is built into the production build. Every route that can be rendered is rendered to HTML during vite build and written into dist/, so the first paint delivers real content while React hydrates in the background.

There is no separate export command and no export mode to enable. The same build that bundles your client also produces the pre-rendered pages.

How It Works

During the build, each of the following steps runs in order:

src
app
page.tsx
blog
page.tsx
[slug]
page.tsx
/
/blog
/blog/:slug
  • Reads your routes from the router, so static routes and dynamic patterns are both known.
  • Expands staticParams so dynamic routes that export it become concrete URLs.
  • Renders each URL through the built-in SSR entry and writes the resulting HTML into dist/.
  • Crawls every rendered page for internal links and renders those URLs too.
  • Writes shell pages for routes that cannot be rendered server-side.
  • Injects metadata and route-scoped CSS, and writes a 404.html.

staticParams

Export staticParams from a dynamic page to declare which URLs should be pre-rendered. It works independently of link crawling, so you can guarantee coverage of every known parameter.

src/app/blog/[slug]/page.tsx
// src/app/blog/[slug]/page.tsx
export async function staticParams() {
  return [{ slug: 'hello-world' }, { slug: 'second-post' }]
}

Each object is substituted into the route pattern. Named segments such as :slug accept a string or number. A trailing * or ** accepts the '*' key, as either an array of segments or a string that is split on /.

A dynamic route without staticParams that no rendered page links to will only get a shell page. To pre-render it as full HTML, list its URLs in staticParams or link to it from a rendered page.

prerender = false

Opt a page out of server rendering by exporting prerender = false:

src/app/admin/page.tsx
// src/app/admin/page.tsx
export const prerender = false

A shell page is still written at that URL, but the SSR renderer is never called for it. Use this for pages that only make sense on the client, such as authenticated dashboards or views that depend on browser APIs.

Build Command

Build your app for production. The client, the server bundle, and all pre-rendered HTML are produced in a single pass.

>_Terminal
$ npm run build

To serve the build on a Node.js host, use the start command. It runs the production server, which serves the pre-rendered pages and the compiled API together:

>_Terminal
$ npm run start
CommandPurpose
npm run buildBuilds the client, builds the server bundle, and pre-renders every route to dist/.
npm run startServes the built app on a Node.js server, including API routes.

Output Structure

Each route is written as its own folder with an index.html. Highlighted files were produced by crawling or expanded from staticParams. The [slug] and [...slug] folders are shell fallbacks for dynamic routes that were never pre-rendered.

dist
index.html
about
index.html
blog
index.html
my-first-post
index.html
hello-world
index.html
[slug]
index.html
docs
getting-started
index.html
[...slug]
index.html
404.html
api
index.mjs
index-[hash].js
index-[hash].css
/
/about
/blog
/blog/my-first-post
/blog/hello-world
/blog/:slug
/docs/getting-started
/docs/*
A dynamic route that is linked from a rendered page, or listed in staticParams, is written as full HTML. Everything else falls back to a shell page.

Crawling & Shell Fallback

After rendering static routes and any staticParams URLs, the build reads each rendered page for internal links and renders those URLs as well:

dist/blog/index.html
<a href="/blog/my-first-post">
<a href="/blog/hello-world">
Discovered and pre-rendered
/blog/my-first-postdist/blog/my-first-post/index.html
/blog/hello-worlddist/blog/hello-world/index.html

This repeats until no new URLs are discovered. Some routes cannot be rendered server-side - those with prerender = false, client-only routes with data exports such as loader, and dynamic patterns that no page links to and that are not listed in staticParams. Each of those receives a shell page with an empty #root and this marker in <head>:

<script>window.__BINI_SHELL__=true;</script>
Linked dynamic routes are fully pre-rendered, so they load instantly and are indexed by search engines. Unlinked ones still work through the shell fallback - no 404, and they hydrate on the client.

Client Entry & Hydration

The marker script only sets a flag. The client entry decides how to mount the app based on it:

  • If window.__BINI_SHELL__ === true, or #root is empty, call createRoot(root).render(<App />).
  • Otherwise call hydrateRoot(root, <App />).

A pre-rendered page already contains its markup, so hydrating it attaches the client app without a second render. A shell page has an empty #root, so attempting to hydrate it would fail - hence the flag.

404 Handling

404.html is always written to dist/. What goes inside depends on your app:

src
app
not-found.tsx
dist
404.html
index.html
SituationWhat gets written to 404.html
src/app/not-found.tsxYour custom not-found page, pre-rendered to HTML.
No custom not-found fileThe built-in 404 page.
Rendering /404 failsA shell page - not counted as a build failure.

Static Hosts

The Web build can be served directly from any static host. Both static and dynamic routes work:

HostStatic routesDynamic routes
GitHub Pages✓ pre-rendered✓ crawled + pre-rendered, shell fallback
AWS S3 + CloudFront✓ pre-rendered✓ crawled + pre-rendered, shell fallback
Firebase Hosting✓ pre-rendered✓ crawled + pre-rendered, shell fallback
Surge.sh✓ pre-rendered✓ crawled + pre-rendered, shell fallback

Complete Example

Deploy to GitHub Pages. If your site is served under a subpath, set base in vite.config.ts first:

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

export default defineConfig({
  base: '/my-app/',  // GitHub Pages subpath
  plugins: [
    react(),
    // ...your other plugins
  ],
})

Build the app, then push the contents of dist/ to your GitHub Pages branch (or upload them through the GitHub Pages UI).

>_Terminal
$ npm run build

Deployment Overview

Where to deploy a Bini.js app.

Production Server

Run the production server for Node.js hosting.

Hosting Providers

Platform-specific deployment notes.

Layouts and Pages

How routes map to pages in the app directory.

Was this helpful?
PreviousProduction Server
NextHosting Providers

On this page

  • Overview
  • How It Works
  • staticParams
  • prerender = false
  • Build Command
  • Output Structure
  • Crawling & Shell Fallback
  • Client Entry & Hydration
  • 404 Handling
  • Static Hosts
  • Complete Example
Edit this page on GitHub