serve-reload

Zero-dependency static file server with live reload for development.

Most static dev servers with live reload are either abandoned — accumulating security vulnerabilities flagged by npm audit — or bloated with features and dependencies far beyond what a simple dev server needs. serve-reload takes a different approach: it just serves and reloads, with zero dependencies, eliminating the problem of transitive security issues at the root.

Features

• Zero dependencies — only Node.js built-ins
• Live reload — via Server-Sent Events (no WebSocket library needed)
• CSS hot inject — CSS changes apply instantly without a full page reload
• SPA mode — fallback routing for single-page apps
• Proxy — forward API requests to another server
• CORS enabled — by default
• Glob ignore patterns — *.map, src/temp, **/test, etc.
• Fast startup — nothing to install beyond Node.js
• CLI + API — use from the terminal or programmatically

Install

npm install -g serve-reload

Or use directly with npx:

npx serve-reload ./public

CLI Usage

serve-reload [root] [options]

| Option | Description | Default | |---|---|---| | -p, --port <n> | Port number (auto-fallback if busy) | 3000 | | --host <addr> | Bind address | 0.0.0.0 | | -o, --open | Open browser on start | off | | --no-reload | Disable live reload | enabled | | --no-cors | Disable CORS headers | enabled | | --spa <file> | SPA fallback file | — | | --quiet | Suppress request logs | off | | --ignore <patterns> | Comma-separated ignore patterns | — | | --proxy <route:url> | Proxy route to URL (repeatable) | — |

Examples

# Serve current directory on port 3000
serve-reload

# Serve ./dist on port 8080, open browser
serve-reload ./dist -p 8080 --open

# SPA mode (all unknown routes → index.html)
serve-reload ./build --spa index.html

# Ignore source maps and temp files
serve-reload --ignore "*.map,*.min.*,temp"

# Proxy API requests
serve-reload --proxy /api:https://api.example.com

# Multiple proxies
serve-reload --proxy /api:https://api.example.com --proxy /auth:http://localhost:4000

# Disable live reload (just a static server)
serve-reload ./public --no-reload

Ignore Patterns

The --ignore option controls which file changes do not trigger a reload. Ignored files are still served normally over HTTP — they just won't cause the browser to refresh.

Supported patterns:

| Pattern | Example | Matches | |---|---|---| | node_modules | Plain name | Any path segment named node_modules | | *.map | Extension glob | dist/bundle.js.map | | *.min.* | Multi-extension | bundle.min.js | | src/temp | Path prefix | src/temp and src/temp/file.js | | **/test | Recursive glob | test, src/test, deep/nested/test | | ?.js | Single character | a.js but not ab.js |

Default ignored: node_modules, .git, .DS_Store

Programmatic API

import { ServeReload } from "serve-reload";

const server = new ServeReload({
  root: "./public",
  port: 8080,
  open: true,
  spa: "index.html",
  ignore: ["*.map", "temp"],
  proxy: {
    "/api": "https://api.example.com",
  },
});

server.start();

// Later...
await server.stop();

How It Works

1. Static serving — Node's built-in http module serves files with correct MIME types
2. HTML injection — A tiny <script> is injected into HTML responses that opens an SSE connection
3. File watching — fs.watch (recursive) monitors the served directory for changes
4. Reload signal — When a non-CSS file changes, all connected browsers reload. When a CSS file changes, stylesheets are hot-swapped without a full reload
5. Reconnect — If the server restarts, the browser automatically reconnects and reloads

Requirements

Node.js ≥ 18

License

MIT