Overview

bini-server is the default production server for the Node.js hosting target. It streams your built dist/ folder, serves /api/* routes directly from src/app/api/, and adds everything vite preview intentionally leaves out - ETag caching, timeouts, graceful shutdown, and configurable body limits.

It has zero runtime dependencies - only Node.js built-in modules - and works identically on Windows, macOS, and Linux.

Features

Core

Security & Performance

Developer Experience

Installation

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

$ npm install bini-server

Usage

1. Add scripts to package.json

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

2. Build and start

$ npm run build
$ npm start

3. Terminal output

  ß Bini.js (production)
  ➜  Environments: .env, .env.local
  ➜  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:

Environment Variables

Auto-detected .env files

At startup, bini-server automatically detects and loads, in priority order:

• .env.local
• .env.[NODE_ENV].local (e.g. .env.production.local)
• .env.[NODE_ENV] (e.g. .env.production)
• .env

All detected files are listed in the startup banner.

Naming conventions

Every setting supports three naming conventions, in priority order:

Server configuration

Examples

# .env
PORT=8080
CORS_ENABLED=false
API_DIR=src/api
BODY_SIZE_LIMIT=5242880  # 5MB

$ PORT=3001 BINI_CORS_ENABLED=false bini-server

# Or with the VITE prefix
$ VITE_PORT=3000 VITE_CORS_ENABLED=false bini-server

Project Structure

• dist/ - built static files (required)
• src/app/api/ - API handlers (optional)
• .env - environment variables

API Routes

Supported formats

A Hono app (recommended):

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
export default (req: Request) => {
  return Response.json({ message: 'Hello' })
}

Dynamic routes

Route parameters

For plain function handlers, route params are passed as JSON via the x-bini-params request header:

// src/app/api/users/[id].ts
export default (req: Request) => {
  const params = JSON.parse(req.headers.get('x-bini-params') || '{}')
  // params.id -> '123'
  return Response.json({ id: params.id })
}

CORS

CORS is enabled by default with these headers:

Access-Control-Allow-Origin: *
Access-Control-Allow-Methods: GET,POST,PUT,PATCH,DELETE,OPTIONS,HEAD
Access-Control-Allow-Headers: Content-Type,Authorization,X-Request-ID

Disable it with CORS_ENABLED=false, BINI_CORS_ENABLED=false, or VITE_CORS_ENABLED=false:

# .env
CORS_ENABLED=false

Static File Serving

Supported MIME types

• HTML, CSS, JavaScript, JSON
• Images - PNG, JPEG, GIF, SVG, WebP, AVIF, ICO
• Fonts - WOFF, WOFF2, TTF, EOT
• Documents - TXT, XML
• Web manifests

Cache headers

ETag support

ETags are generated automatically from file size + mtimeMs:

• Sends an ETag header on the first request
• Handles If-None-Match for 304 Not Modified responses
• Uses an MD5 hash (16 chars) for efficient caching

vs vite preview

Security

Testing your server

# Check static files
$ curl http://localhost:3000/

# Check API routes
$ curl http://localhost:3000/api/hello

# Check ETag
$ curl -I http://localhost:3000/styles.css

# Test 304 Not Modified
$ curl -I http://localhost:3000/styles.css \
  -H "If-None-Match: [etag_from_previous_request]"

# Test CORS
$ curl -X OPTIONS http://localhost:3000/api/hello \
  -H "Origin: http://example.com"

Configuration examples

Development (all security disabled)

# .env
CORS_ENABLED=true
BODY_TIMEOUT_SECS=0
HANDLER_TIMEOUT_SECS=0
BODY_SIZE_LIMIT=0
NODE_ENV=development

Production (secure defaults)

# .env
CORS_ENABLED=true
BODY_TIMEOUT_SECS=30
HANDLER_TIMEOUT_SECS=30
BODY_SIZE_LIMIT=10485760
NODE_ENV=production

Internal API (no CORS)

# .env
CORS_ENABLED=false
BODY_SIZE_LIMIT=5242880  # 5MB

File upload service

# .env
CORS_ENABLED=true
BODY_SIZE_LIMIT=1073741824  # 1GB
BODY_TIMEOUT_SECS=300  # 5 minutes

Deployment

Where it works

• VPS / pm2 - deploy the full project directory
• Railway / Render / Fly.io - automatic, since these clone your repository
• Docker - copy both dist/ and src/ into the image

VPS / dedicated server

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

Platform as a Service

Docker

FROM node:20-alpine
WORKDIR /app
COPY package*.json ./
RUN npm install --production
COPY . .
RUN npm run build
EXPOSE 3000
CMD ["npm", "start"]

Fly.io

[processes]
  app = "npm start"

API Reference

Environment variable priority

1. BINI_* (highest)
2. VITE_* (medium)
3. No prefix (lowest)

HTTP status codes

Supported HTTP methods

GET, POST, PUT, PATCH, DELETE, OPTIONS (CORS preflight), and HEAD (with ETag support).