@nervmouse/oneserve

A simple yet powerful static server with proxy capabilities and SPA history mode support.

Installation

npm install @nervmouse/oneserve
# or globally
npm install -g @nervmouse/oneserve

Usage

You can run it directly using the CLI:

# Using npx (recommended)
npx @nervmouse/oneserve

# If installed globally
serve

Local Project Usage

If installed as a dependency in your project:

In package.json scripts:

{
  "scripts": {
    "dev": "serve"
  }
}

Using npx in project root:

npx serve

Configuration

oneserve can be configured via a serve.cfg.json file in the working directory or via environment variables.

Configuration Options

Option	Env Variable	Default	Description
port	PORT	8000	Port to listen on.
api_url	API_URL	http://api.gov.tw	Target URL for the API proxy.
api_uri	API_URI	/api	The base path to prepend to proxied requests on the target server.
local_api_uri	LOCAL_API_URI	/api	The local path prefix to intercept for proxying.
mode	MODE	hash	hash or history. Use history for SPA with client-side routing.
root_dir	ROOT_DIR	./spa	Directory containing static files to serve.
index_path	INDEX_PATH	null	Path to the index file (for history mode). Defaults to root_dir/index.html.
auto_update	N/A	true	Enables /_oneserve/update endpoint to trigger git pull.
console_title	CONSOLE_TITLE	Package Name	Title of the process.
max_age	MAX_AGE	1d	Cache-Control max-age for static assets.

Configuration File (serve.cfg.json) Example

Create a serve.cfg.json in your project root:

{
  "port": 3000,
  "root_dir": "./dist",
  "mode": "history",
  "api_url": "http://backend-api.com",
  "local_api_uri": "/api/v1",
  "max_age": "1d"
}

Features

Static File Serving

Serves static files from the specified root_dir.

API Proxy

Proxies requests matching local_api_uri to api_url.

• Automatically handles X-Forwarded-For and x-real-ip headers.
• A request to [server]:[port]/<local_api_uri>/<some_path> is proxied to <api_url>/<api_uri>/<some_path>.

SPA History Mode

If mode is set to history, any request that doesn't match a static file or the proxy path will serve the index.html (defined by index_path or default root_dir/index.html), allowing client-side routing to work.

Auto Update

Security Warning: This feature exposes an unprotected endpoint /_oneserve/update that executes git pull. Enabling this in a production or publicly accessible environment is a major security risk and is strongly discouraged. It should only be used in controlled, trusted environments.

When enabled, the server exposes /_oneserve/update. Accessing this endpoint will execute git pull in the server's root directory.