Production server for Bini.js apps. Serves the output of your build: pre-rendered pages, static assets, and the compiled API bundle.
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.
>= 20.19.0vite build output folder (dist/)dist/api/index.mjs (only if your app uses API routes)1. Add scripts to your package.json:
2. Build and start the server:
3. The terminal will output the server banner:
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.
While the server is running in an interactive terminal, type a key and press enter:
| Key | Action |
|---|---|
| h | Show available shortcuts |
| o | Open the local URL in your default browser |
| q | Quit the server gracefully |
Shortcuts are automatically disabled when running in a non-interactive environment (like CI/CD or most hosting platforms).
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.envAll detected files are listed in the startup banner. These values are available in process.env and are passed directly to your API routes.
Every setting below can use three naming conventions: BINI_PORT (highest priority), VITE_PORT (medium), or PORT (lowest).
| Variable | Default | Description |
|---|---|---|
| PORT | 3000 | HTTP port to listen on. Auto-increments if busy. |
| DIST_DIR | dist | Build output folder. |
| BASE | (empty) | Sub-path the app is served under (e.g. /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 (10 MB). |
0 does not disable it. A body limit of 0 rejects any request body, and a timeout of 0 expires immediately.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.
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:
cors option in biniroute() inside your vite.config.ts.For paths without a file extension, the server tries to serve files in this order:
| Order | Looks for | Status |
|---|---|---|
| 1 | dist/<path>/index.html (pre-rendered page) | 200 |
| 2 | A dynamic shell page matching the path | 200 |
| 3 | dist/404.html | 404 |
| 4 | dist/index.html (SPA fallback) | 200 |
| 5 | Nothing found | 404 |
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:
| Folder | Matches |
|---|---|
| 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) |
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.| Feature | Default | Configured With |
|---|---|---|
| Body size limit (API) | 10 MB | BODY_SIZE_LIMIT |
| Body read timeout (API) | 30 s | BODY_TIMEOUT_SECS |
| Handler timeout (API) | 30 s | HANDLER_TIMEOUT_SECS |
| Path traversal | Blocked (refuses .. segments and null bytes) | Not configurable |
| Compiled API isolation | dist/api/ is never served as static files | Not configurable |
| Error messages | Hidden when NODE_ENV=production | NODE_ENV |
These are produced by bini-server itself:
| Code | Description |
|---|---|
| 200 | Success |
| 304 | Not Modified (ETag match) |
| 400 | Bad request URL |
| 404 | Not found (missing file, unknown path, or no compiled API) |
| 408 | API request body not received in time |
| 413 | API request body too large |
| 500 | Internal server error (including API handler timeout) |
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.
Production server for Bini.js apps. Serves the output of your build: pre-rendered pages, static assets, and the compiled API bundle.
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.
>= 20.19.0vite build output folder (dist/)dist/api/index.mjs (only if your app uses API routes)1. Add scripts to your package.json:
2. Build and start the server:
3. The terminal will output the server banner:
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.
While the server is running in an interactive terminal, type a key and press enter:
| Key | Action |
|---|---|
| h | Show available shortcuts |
| o | Open the local URL in your default browser |
| q | Quit the server gracefully |
Shortcuts are automatically disabled when running in a non-interactive environment (like CI/CD or most hosting platforms).
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.envAll detected files are listed in the startup banner. These values are available in process.env and are passed directly to your API routes.
Every setting below can use three naming conventions: BINI_PORT (highest priority), VITE_PORT (medium), or PORT (lowest).
| Variable | Default | Description |
|---|---|---|
| PORT | 3000 | HTTP port to listen on. Auto-increments if busy. |
| DIST_DIR | dist | Build output folder. |
| BASE | (empty) | Sub-path the app is served under (e.g. /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 (10 MB). |
0 does not disable it. A body limit of 0 rejects any request body, and a timeout of 0 expires immediately.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.
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:
cors option in biniroute() inside your vite.config.ts.For paths without a file extension, the server tries to serve files in this order:
| Order | Looks for | Status |
|---|---|---|
| 1 | dist/<path>/index.html (pre-rendered page) | 200 |
| 2 | A dynamic shell page matching the path | 200 |
| 3 | dist/404.html | 404 |
| 4 | dist/index.html (SPA fallback) | 200 |
| 5 | Nothing found | 404 |
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:
| Folder | Matches |
|---|---|
| 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) |
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.| Feature | Default | Configured With |
|---|---|---|
| Body size limit (API) | 10 MB | BODY_SIZE_LIMIT |
| Body read timeout (API) | 30 s | BODY_TIMEOUT_SECS |
| Handler timeout (API) | 30 s | HANDLER_TIMEOUT_SECS |
| Path traversal | Blocked (refuses .. segments and null bytes) | Not configurable |
| Compiled API isolation | dist/api/ is never served as static files | Not configurable |
| Error messages | Hidden when NODE_ENV=production | NODE_ENV |
These are produced by bini-server itself:
| Code | Description |
|---|---|
| 200 | Success |
| 304 | Not Modified (ETag match) |
| 400 | Bad request URL |
| 404 | Not found (missing file, unknown path, or no compiled API) |
| 408 | API request body not received in time |
| 413 | API request body too large |
| 500 | Internal server error (including API handler timeout) |
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.