A zero-dependency, secure-by-default production server for your Bini.js app, powered by bini-server.
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.
It has no dependencies beyond Node.js itself, and works the same on Windows, macOS, and Linux.
Ships the output of vite build - pages, assets, and API.
Handles /api/* from the compiled bundle.
Pre-rendered page, then shell page, then 404, then index.html.
Sends ETag headers so unchanged files return 304 Not Modified.
Body size limits, timeouts, and path traversal protection are on.
Handles SIGTERM and SIGINT cleanly.
Every Bini.js web project already includes bini-server. To add it to an existing project:
While the server is running, type a key and press enter:
| Key | Action |
|---|---|
| h | Show available shortcuts |
| o | Open your app in the default browser |
| q | Quit the server |
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.
Every setting works with any of these, in priority order:
| Convention | Example | Priority |
|---|---|---|
| BINI_* | BINI_PORT=3000 | Highest |
| VITE_* | VITE_PORT=3000 | Medium |
| No prefix | PORT=3000 | Lowest |
| Variable | Default | Description |
|---|---|---|
| PORT | 3000 | HTTP 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_SECS | 30 | Max seconds to read an API request body. |
| HANDLER_TIMEOUT_SECS | 30 | Max seconds for an API handler to respond. |
| BODY_SIZE_LIMIT | 10485760 | Max API request body size in bytes (10 MB). |
dist/ - build output (required)dist/api/index.mjs - compiled API bundle (only if the app has API routes).env - environment variablesEvery /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.
{"error":"No API routes compiled"}.A Hono app (recommended):
Or a plain function:
Handlers receive route params as the second argument:
Files in dist/ are served directly. For a URL without a file extension, the server picks in this order:
dist/404.htmldist/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.
| Feature | Default | Change with |
|---|---|---|
| API body size limit | 10 MB | BODY_SIZE_LIMIT |
| API body read timeout | 30 s | BODY_TIMEOUT_SECS |
| API handler timeout | 30 s | HANDLER_TIMEOUT_SECS |
| Path traversal | Blocked | Always on |
| Hidden error messages | On with NODE_ENV=production | NODE_ENV |
| Platform | Start Command |
|---|---|
| Railway | npm start |
| Render | npm start |
| Fly.io | npm start |
| Heroku | npm start |
These platforms inject PORT automatically.
Where to deploy a Bini.js app.
Pre-render the whole app for a static host.
Platform-specific deployment notes.
Read secrets with getEnv and requireEnv.
A zero-dependency, secure-by-default production server for your Bini.js app, powered by bini-server.
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.
It has no dependencies beyond Node.js itself, and works the same on Windows, macOS, and Linux.
Ships the output of vite build - pages, assets, and API.
Handles /api/* from the compiled bundle.
Pre-rendered page, then shell page, then 404, then index.html.
Sends ETag headers so unchanged files return 304 Not Modified.
Body size limits, timeouts, and path traversal protection are on.
Handles SIGTERM and SIGINT cleanly.
Every Bini.js web project already includes bini-server. To add it to an existing project:
While the server is running, type a key and press enter:
| Key | Action |
|---|---|
| h | Show available shortcuts |
| o | Open your app in the default browser |
| q | Quit the server |
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.
Every setting works with any of these, in priority order:
| Convention | Example | Priority |
|---|---|---|
| BINI_* | BINI_PORT=3000 | Highest |
| VITE_* | VITE_PORT=3000 | Medium |
| No prefix | PORT=3000 | Lowest |
| Variable | Default | Description |
|---|---|---|
| PORT | 3000 | HTTP 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_SECS | 30 | Max seconds to read an API request body. |
| HANDLER_TIMEOUT_SECS | 30 | Max seconds for an API handler to respond. |
| BODY_SIZE_LIMIT | 10485760 | Max API request body size in bytes (10 MB). |
dist/ - build output (required)dist/api/index.mjs - compiled API bundle (only if the app has API routes).env - environment variablesEvery /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.
{"error":"No API routes compiled"}.A Hono app (recommended):
Or a plain function:
Handlers receive route params as the second argument:
Files in dist/ are served directly. For a URL without a file extension, the server picks in this order:
dist/404.htmldist/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.
| Feature | Default | Change with |
|---|---|---|
| API body size limit | 10 MB | BODY_SIZE_LIMIT |
| API body read timeout | 30 s | BODY_TIMEOUT_SECS |
| API handler timeout | 30 s | HANDLER_TIMEOUT_SECS |
| Path traversal | Blocked | Always on |
| Hidden error messages | On with NODE_ENV=production | NODE_ENV |
| Platform | Start Command |
|---|---|
| Railway | npm start |
| Render | npm start |
| Fly.io | npm start |
| Heroku | npm start |
These platforms inject PORT automatically.
Where to deploy a Bini.js app.
Pre-render the whole app for a static host.
Platform-specific deployment notes.
Read secrets with getEnv and requireEnv.