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.

Production Server

A zero-dependency, secure-by-default production server for your Bini.js app, powered by bini-server.

Overview

bini-server is the production server for Bini.js apps on Node.js. It serves your built app - the pages, the assets, and the API routes - so you can run it on a server.

Requestbini-server
dist/static files and pagesdist/api/index.mjsall /api/* requests

It has no dependencies beyond Node.js itself, and works the same on Windows, macOS, and Linux.

Features

Serves your build

Ships the output of vite build - pages, assets, and API.

API routes

Handles /api/* from the compiled bundle.

Page fallbacks

Pre-rendered page, then shell page, then 404, then index.html.

Caching

Sends ETag headers so unchanged files return 304 Not Modified.

Safe by default

Body size limits, timeouts, and path traversal protection are on.

Graceful shutdown

Handles SIGTERM and SIGINT cleanly.

Installation

Every Bini.js web project already includes bini-server. To add it to an existing project:

>_Terminal
$ npm install bini-server

Usage

1. Add scripts to package.json

{}package.json
{
  "scripts": {
    "build": "vite build",
    "start": "bini-server"
  }
}

2. Build and start

>_Terminal
$ npm run build
$ npm start

3. Terminal output

>_Terminal
  ß Bini.js (production)
  ➜  Environments: .env.local, .env
  ➜  Local:   http://localhost:3000/
  ➜  Network: http://192.168.1.5:3000/
  ➜  press h + enter to show help

Keyboard Shortcuts

While the server is running, type a key and press enter:

KeyAction
hShow available shortcuts
oOpen your app in the default browser
qQuit the server
Shortcuts are disabled when the server runs without a terminal (for example on a hosted platform or in CI).

Environment Variables

.env files

At startup, bini-server loads these files from the working directory when they exist. Highest priority first:

  • .env.[mode].local
  • .env.[mode]
  • .env.local
  • .env

[mode] is NODE_ENV, or production when that is not set. A variable that is already set in the environment is never overridden by a file.

Naming conventions

Every setting works with any of these, in priority order:

ConventionExamplePriority
BINI_*BINI_PORT=3000Highest
VITE_*VITE_PORT=3000Medium
No prefixPORT=3000Lowest

Server settings

VariableDefaultDescription
PORT3000HTTP port to listen on. Uses the next free port if busy.
BASE(empty)Sub-path the app is served under, for example /app.
BODY_TIMEOUT_SECS30Max seconds to read an API request body.
HANDLER_TIMEOUT_SECS30Max seconds for an API handler to respond.
BODY_SIZE_LIMIT10485760Max API request body size in bytes (10 MB).

Examples

.env
# .env
PORT=8080
BODY_SIZE_LIMIT=5242880  # 5MB
>_Terminal
# Inline
$ PORT=3001 bini-server

# BINI_ takes precedence over plain PORT
$ BINI_PORT=3002 bini-server

Project Structure

my-app
dist
index.html
404.html
assets
api
index.mjs
src
app
api
ƒusers.ts
layout.tsx
.env
package.json
vite.config.ts
  • dist/ - build output (required)
  • dist/api/index.mjs - compiled API bundle (only if the app has API routes)
  • .env - environment variables

API Routes

Every /api/* request goes to the single compiled bundle at dist/api/index.mjs. vite build produces it from the files in src/app/api/. bini-server does not read your source at runtime.

If the bundle is missing, every API request returns 404 with {"error":"No API routes compiled"}.

Handler formats

A Hono app (recommended):

src/app/api/users.ts
import { Hono } from 'hono'

const app = new Hono()

app.get('/users', (c) => c.json({ users: [] }))

export default app

Or a plain function:

src/app/api/hello.ts
// src/app/api/hello.ts
export default (req: Request) => {
  return Response.json({ message: 'Hello' })
}

Dynamic routes

src
app
api
users
ƒ[id].ts
posts
ƒ[...slug].ts
/api/users/:id
/api/posts/*

Handlers receive route params as the second argument:

src/app/api/users/[id].ts
// src/app/api/users/[id].ts
export default (req: Request, { params }: { params: { id: string } }) => {
  return Response.json({ id: params.id })
}

Static File Serving

Files in dist/ are served directly. For a URL without a file extension, the server picks in this order:

  • a pre-rendered page at that path
  • a shell page that matches the path
  • dist/404.html
  • dist/index.html (client-side fallback)

Files under dist/api/ are never served as static files.

Caching is automatic: unchanged files return 304 Not Modified via ETag, and files inside an assets/ folder get a 1-year immutable cache header.

Security

FeatureDefaultChange with
API body size limit10 MBBODY_SIZE_LIMIT
API body read timeout30 sBODY_TIMEOUT_SECS
API handler timeout30 sHANDLER_TIMEOUT_SECS
Path traversalBlockedAlways on
Hidden error messagesOn with NODE_ENV=productionNODE_ENV

Test your server

>_Terminal
# Page
$ curl http://localhost:3000/

# API route
$ curl http://localhost:3000/api/hello

# ETag / 304
$ curl -I http://localhost:3000/assets/app.js

Deployment

VPS / dedicated server

>_Terminal
$ npm run build
$ npm start
$ npm install -g pm2
$ pm2 start "npm start" --name my-app
$ pm2 save
$ pm2 startup

Platform as a Service

PlatformStart Command
Railwaynpm start
Rendernpm start
Fly.ionpm start
Herokunpm start

These platforms inject PORT automatically.

Docker

Dockerfile
FROM node:20-alpine
WORKDIR /app
COPY package*.json ./
RUN npm ci
COPY . .
RUN npm run build && npm prune --omit=dev
ENV NODE_ENV=production
EXPOSE 3000
CMD ["npm", "start"]

Fly.io

fly.toml
[processes]
  app = "npm start"

Deployment Overview

Where to deploy a Bini.js app.

Static Export

Pre-render the whole app for a static host.

Hosting Providers

Platform-specific deployment notes.

Environment Variables

Read secrets with getEnv and requireEnv.

Was this helpful?
PreviousDeploying
NextStatic Export

On this page

  • Overview
  • Features
  • Installation
  • Usage
  • Keyboard Shortcuts
  • Environment Variables
  • Project Structure
  • API Routes
  • Static File Serving
  • Security
  • Deployment
Edit this page on GitHub

Production Server

A zero-dependency, secure-by-default production server for your Bini.js app, powered by bini-server.

Overview

bini-server is the production server for Bini.js apps on Node.js. It serves your built app - the pages, the assets, and the API routes - so you can run it on a server.

Requestbini-server
dist/static files and pagesdist/api/index.mjsall /api/* requests

It has no dependencies beyond Node.js itself, and works the same on Windows, macOS, and Linux.

Features

Serves your build

Ships the output of vite build - pages, assets, and API.

API routes

Handles /api/* from the compiled bundle.

Page fallbacks

Pre-rendered page, then shell page, then 404, then index.html.

Caching

Sends ETag headers so unchanged files return 304 Not Modified.

Safe by default

Body size limits, timeouts, and path traversal protection are on.

Graceful shutdown

Handles SIGTERM and SIGINT cleanly.

Installation

Every Bini.js web project already includes bini-server. To add it to an existing project:

>_Terminal
$ npm install bini-server

Usage

1. Add scripts to package.json

{}package.json
{
  "scripts": {
    "build": "vite build",
    "start": "bini-server"
  }
}

2. Build and start

>_Terminal
$ npm run build
$ npm start

3. Terminal output

>_Terminal
  ß Bini.js (production)
  ➜  Environments: .env.local, .env
  ➜  Local:   http://localhost:3000/
  ➜  Network: http://192.168.1.5:3000/
  ➜  press h + enter to show help

Keyboard Shortcuts

While the server is running, type a key and press enter:

KeyAction
hShow available shortcuts
oOpen your app in the default browser
qQuit the server
Shortcuts are disabled when the server runs without a terminal (for example on a hosted platform or in CI).

Environment Variables

.env files

At startup, bini-server loads these files from the working directory when they exist. Highest priority first:

  • .env.[mode].local
  • .env.[mode]
  • .env.local
  • .env

[mode] is NODE_ENV, or production when that is not set. A variable that is already set in the environment is never overridden by a file.

Naming conventions

Every setting works with any of these, in priority order:

ConventionExamplePriority
BINI_*BINI_PORT=3000Highest
VITE_*VITE_PORT=3000Medium
No prefixPORT=3000Lowest

Server settings

VariableDefaultDescription
PORT3000HTTP port to listen on. Uses the next free port if busy.
BASE(empty)Sub-path the app is served under, for example /app.
BODY_TIMEOUT_SECS30Max seconds to read an API request body.
HANDLER_TIMEOUT_SECS30Max seconds for an API handler to respond.
BODY_SIZE_LIMIT10485760Max API request body size in bytes (10 MB).

Examples

.env
# .env
PORT=8080
BODY_SIZE_LIMIT=5242880  # 5MB
>_Terminal
# Inline
$ PORT=3001 bini-server

# BINI_ takes precedence over plain PORT
$ BINI_PORT=3002 bini-server

Project Structure

my-app
dist
index.html
404.html
assets
api
index.mjs
src
app
api
ƒusers.ts
layout.tsx
.env
package.json
vite.config.ts
  • dist/ - build output (required)
  • dist/api/index.mjs - compiled API bundle (only if the app has API routes)
  • .env - environment variables

API Routes

Every /api/* request goes to the single compiled bundle at dist/api/index.mjs. vite build produces it from the files in src/app/api/. bini-server does not read your source at runtime.

If the bundle is missing, every API request returns 404 with {"error":"No API routes compiled"}.

Handler formats

A Hono app (recommended):

src/app/api/users.ts
import { Hono } from 'hono'

const app = new Hono()

app.get('/users', (c) => c.json({ users: [] }))

export default app

Or a plain function:

src/app/api/hello.ts
// src/app/api/hello.ts
export default (req: Request) => {
  return Response.json({ message: 'Hello' })
}

Dynamic routes

src
app
api
users
ƒ[id].ts
posts
ƒ[...slug].ts
/api/users/:id
/api/posts/*

Handlers receive route params as the second argument:

src/app/api/users/[id].ts
// src/app/api/users/[id].ts
export default (req: Request, { params }: { params: { id: string } }) => {
  return Response.json({ id: params.id })
}

Static File Serving

Files in dist/ are served directly. For a URL without a file extension, the server picks in this order:

  • a pre-rendered page at that path
  • a shell page that matches the path
  • dist/404.html
  • dist/index.html (client-side fallback)

Files under dist/api/ are never served as static files.

Caching is automatic: unchanged files return 304 Not Modified via ETag, and files inside an assets/ folder get a 1-year immutable cache header.

Security

FeatureDefaultChange with
API body size limit10 MBBODY_SIZE_LIMIT
API body read timeout30 sBODY_TIMEOUT_SECS
API handler timeout30 sHANDLER_TIMEOUT_SECS
Path traversalBlockedAlways on
Hidden error messagesOn with NODE_ENV=productionNODE_ENV

Test your server

>_Terminal
# Page
$ curl http://localhost:3000/

# API route
$ curl http://localhost:3000/api/hello

# ETag / 304
$ curl -I http://localhost:3000/assets/app.js

Deployment

VPS / dedicated server

>_Terminal
$ npm run build
$ npm start
$ npm install -g pm2
$ pm2 start "npm start" --name my-app
$ pm2 save
$ pm2 startup

Platform as a Service

PlatformStart Command
Railwaynpm start
Rendernpm start
Fly.ionpm start
Herokunpm start

These platforms inject PORT automatically.

Docker

Dockerfile
FROM node:20-alpine
WORKDIR /app
COPY package*.json ./
RUN npm ci
COPY . .
RUN npm run build && npm prune --omit=dev
ENV NODE_ENV=production
EXPOSE 3000
CMD ["npm", "start"]

Fly.io

fly.toml
[processes]
  app = "npm start"

Deployment Overview

Where to deploy a Bini.js app.

Static Export

Pre-render the whole app for a static host.

Hosting Providers

Platform-specific deployment notes.

Environment Variables

Read secrets with getEnv and requireEnv.

Was this helpful?
PreviousDeploying
NextStatic Export

On this page

  • Overview
  • Features
  • Installation
  • Usage
  • Keyboard Shortcuts
  • Environment Variables
  • Project Structure
  • API Routes
  • Static File Serving
  • Security
  • Deployment
Edit this page on GitHub