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-server

Official

Production server for Bini.js apps. Serves the output of your build: pre-rendered pages, static assets, and the compiled API bundle.

Overview

bini-server is the production server for Bini.js apps. It serves the output of vite build - including pre-rendered HTML pages, static assets, and your compiled API bundle - using only Node.js built-in modules.

It adds everything a basic static host leaves out: ETag caching, API timeouts, graceful shutdown, sub-path deployments, and route-aware fallbacks for dynamic pages. It also automatically loads .env files at startup.

Requirements

  • Node.js >= 20.19.0
  • A completed vite build output folder (dist/)
  • dist/api/index.mjs (only if your app uses API routes)

Install

>_Terminal
$ npm install bini-server

Quick Start

1. Add scripts to your package.json:

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

2. Build and start the server:

>_Terminal
$ npm run build
$ npm run start

3. The terminal will output the server banner:

>_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

Usage

You can also start the server programmatically. The start() function reads your environment variables, finds a free port, scans the dist/ folder, and starts the HTTP server.

server.ts
import { start } from 'bini-server'

await start()

Keyboard Shortcuts

While the server is running in an interactive terminal, type a key and press enter:

KeyAction
hShow available shortcuts
oOpen the local URL in your default browser
qQuit the server gracefully

Shortcuts are automatically disabled when running in a non-interactive environment (like CI/CD or most hosting platforms).

Environment Variables

.env Loading

At startup, the server loads these files from your working directory (highest to lowest priority). Variables already set in the OS environment are never overridden.

  • .env.[NODE_ENV].local
  • .env.[NODE_ENV]
  • .env.local
  • .env

All detected files are listed in the startup banner. These values are available in process.env and are passed directly to your API routes.

Configuration Variables

Every setting below can use three naming conventions: BINI_PORT (highest priority), VITE_PORT (medium), or PORT (lowest).

VariableDefaultDescription
PORT3000HTTP port to listen on. Auto-increments if busy.
DIST_DIRdistBuild output folder.
BASE(empty)Sub-path the app is served under (e.g. /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 (10 MB).
Setting a limit or timeout to 0 does not disable it. A body limit of 0 rejects any request body, and a timeout of 0 expires immediately.

Project Structure

my-app
dist
index.html
assets
api
index.mjs
src
app
api
ƒusers.ts
layout.tsx
.env
package.json
vite.config.ts

The server only needs dist/, your package.json, and your installed dependencies. It does not read the src/ folder at runtime; API routes are loaded entirely from dist/api/index.mjs.

API Routes

During your build, bini-router compiles your API handlers into a single bundle at dist/api/index.mjs. The server loads this once at startup and passes requests to its fetch export.

The bundle supports Hono apps, plain functions, and per-method exports:

src/app/api/hello.ts
// 1. Hono app
import { Hono } from 'hono'
const app = new Hono()
app.get('/hello', (c) => c.json({ message: 'Hello' }))
export default app

// 2. Plain function
export default (req: Request) => Response.json({ message: 'Hello' })

// 3. Per-method export
export function GET(req: Request) {
  return Response.json({ message: 'Hello' })
}
CORS is not handled by bini-server. It is handled by the compiled API bundle. To enable CORS, use the cors option in biniroute() inside your vite.config.ts.

Static File Serving

Fallback Chain

For paths without a file extension, the server tries to serve files in this order:

OrderLooks forStatus
1dist/<path>/index.html (pre-rendered page)200
2A dynamic shell page matching the path200
3dist/404.html404
4dist/index.html (SPA fallback)200
5Nothing found404

Shell Pages

At startup, the server scans dist/ for folders wrapped in square brackets (like blog/[slug]). These act as dynamic shells for your client-side router:

FolderMatches
blog/[slug]/blog/anything (exactly one segment)
docs/[...path]/docs/a, /docs/a/b (at least one segment)
docs/[[...path]]/docs, /docs/a, /docs/a/b (zero or more segments)

Caching & ETags

Files inside an assets/ folder are cached for 1 year (max-age=31536000, immutable). All other files are served with no-cache. ETags are generated automatically, and 304 Not Modified responses are supported via If-None-Match.

bini-server does not compress responses. If you need gzip or brotli, place a reverse proxy (like Nginx or Cloudflare) in front of it.

Security

FeatureDefaultConfigured With
Body size limit (API)10 MBBODY_SIZE_LIMIT
Body read timeout (API)30 sBODY_TIMEOUT_SECS
Handler timeout (API)30 sHANDLER_TIMEOUT_SECS
Path traversalBlocked (refuses .. segments and null bytes)Not configurable
Compiled API isolationdist/api/ is never served as static filesNot configurable
Error messagesHidden when NODE_ENV=productionNODE_ENV

API Reference

HTTP Status Codes

These are produced by bini-server itself:

CodeDescription
200Success
304Not Modified (ETag match)
400Bad request URL
404Not found (missing file, unknown path, or no compiled API)
408API request body not received in time
413API request body too large
500Internal server error (including API handler timeout)

Supported Methods

All methods are passed to the API bundle, which decides which it accepts. Static responses do not check the method. HEAD requests receive headers only.

Was this helpful?
Previousbini-native
Nextbini-overlay

On this page

  • Overview
  • Requirements
  • Install
  • Quick Start
  • Usage
  • Keyboard Shortcuts
  • Environment Variables
  • Project Structure
  • API Routes
  • Static File Serving
  • Security
  • API Reference
Edit this page on GitHub

bini-server

Official

Production server for Bini.js apps. Serves the output of your build: pre-rendered pages, static assets, and the compiled API bundle.

Overview

bini-server is the production server for Bini.js apps. It serves the output of vite build - including pre-rendered HTML pages, static assets, and your compiled API bundle - using only Node.js built-in modules.

It adds everything a basic static host leaves out: ETag caching, API timeouts, graceful shutdown, sub-path deployments, and route-aware fallbacks for dynamic pages. It also automatically loads .env files at startup.

Requirements

  • Node.js >= 20.19.0
  • A completed vite build output folder (dist/)
  • dist/api/index.mjs (only if your app uses API routes)

Install

>_Terminal
$ npm install bini-server

Quick Start

1. Add scripts to your package.json:

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

2. Build and start the server:

>_Terminal
$ npm run build
$ npm run start

3. The terminal will output the server banner:

>_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

Usage

You can also start the server programmatically. The start() function reads your environment variables, finds a free port, scans the dist/ folder, and starts the HTTP server.

server.ts
import { start } from 'bini-server'

await start()

Keyboard Shortcuts

While the server is running in an interactive terminal, type a key and press enter:

KeyAction
hShow available shortcuts
oOpen the local URL in your default browser
qQuit the server gracefully

Shortcuts are automatically disabled when running in a non-interactive environment (like CI/CD or most hosting platforms).

Environment Variables

.env Loading

At startup, the server loads these files from your working directory (highest to lowest priority). Variables already set in the OS environment are never overridden.

  • .env.[NODE_ENV].local
  • .env.[NODE_ENV]
  • .env.local
  • .env

All detected files are listed in the startup banner. These values are available in process.env and are passed directly to your API routes.

Configuration Variables

Every setting below can use three naming conventions: BINI_PORT (highest priority), VITE_PORT (medium), or PORT (lowest).

VariableDefaultDescription
PORT3000HTTP port to listen on. Auto-increments if busy.
DIST_DIRdistBuild output folder.
BASE(empty)Sub-path the app is served under (e.g. /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 (10 MB).
Setting a limit or timeout to 0 does not disable it. A body limit of 0 rejects any request body, and a timeout of 0 expires immediately.

Project Structure

my-app
dist
index.html
assets
api
index.mjs
src
app
api
ƒusers.ts
layout.tsx
.env
package.json
vite.config.ts

The server only needs dist/, your package.json, and your installed dependencies. It does not read the src/ folder at runtime; API routes are loaded entirely from dist/api/index.mjs.

API Routes

During your build, bini-router compiles your API handlers into a single bundle at dist/api/index.mjs. The server loads this once at startup and passes requests to its fetch export.

The bundle supports Hono apps, plain functions, and per-method exports:

src/app/api/hello.ts
// 1. Hono app
import { Hono } from 'hono'
const app = new Hono()
app.get('/hello', (c) => c.json({ message: 'Hello' }))
export default app

// 2. Plain function
export default (req: Request) => Response.json({ message: 'Hello' })

// 3. Per-method export
export function GET(req: Request) {
  return Response.json({ message: 'Hello' })
}
CORS is not handled by bini-server. It is handled by the compiled API bundle. To enable CORS, use the cors option in biniroute() inside your vite.config.ts.

Static File Serving

Fallback Chain

For paths without a file extension, the server tries to serve files in this order:

OrderLooks forStatus
1dist/<path>/index.html (pre-rendered page)200
2A dynamic shell page matching the path200
3dist/404.html404
4dist/index.html (SPA fallback)200
5Nothing found404

Shell Pages

At startup, the server scans dist/ for folders wrapped in square brackets (like blog/[slug]). These act as dynamic shells for your client-side router:

FolderMatches
blog/[slug]/blog/anything (exactly one segment)
docs/[...path]/docs/a, /docs/a/b (at least one segment)
docs/[[...path]]/docs, /docs/a, /docs/a/b (zero or more segments)

Caching & ETags

Files inside an assets/ folder are cached for 1 year (max-age=31536000, immutable). All other files are served with no-cache. ETags are generated automatically, and 304 Not Modified responses are supported via If-None-Match.

bini-server does not compress responses. If you need gzip or brotli, place a reverse proxy (like Nginx or Cloudflare) in front of it.

Security

FeatureDefaultConfigured With
Body size limit (API)10 MBBODY_SIZE_LIMIT
Body read timeout (API)30 sBODY_TIMEOUT_SECS
Handler timeout (API)30 sHANDLER_TIMEOUT_SECS
Path traversalBlocked (refuses .. segments and null bytes)Not configurable
Compiled API isolationdist/api/ is never served as static filesNot configurable
Error messagesHidden when NODE_ENV=productionNODE_ENV

API Reference

HTTP Status Codes

These are produced by bini-server itself:

CodeDescription
200Success
304Not Modified (ETag match)
400Bad request URL
404Not found (missing file, unknown path, or no compiled API)
408API request body not received in time
413API request body too large
500Internal server error (including API handler timeout)

Supported Methods

All methods are passed to the API bundle, which decides which it accepts. Static responses do not check the method. HEAD requests receive headers only.

Was this helpful?
Previousbini-native
Nextbini-overlay

On this page

  • Overview
  • Requirements
  • Install
  • Quick Start
  • Usage
  • Keyboard Shortcuts
  • Environment Variables
  • Project Structure
  • API Routes
  • Static File Serving
  • Security
  • API Reference
Edit this page on GitHub