serve

What it is

serve is a zero-config static-file HTTP server from Vercel, designed for the "I just built a SPA and want to verify it locally" workflow. Point it at a directory; it serves files with content-type detection, gzip compression, directory listings, and (crucially) SPA-mode rewrites so /profile resolves to index.html for client-side routing.

It's not a production server — there's no clustering, no caching tier, no graceful reload. But for vercel dev-style local previews, demo deployments, and CI smoke tests of build output, it's the path of least friction.

Install

# As a global dev tool (preferred — version not pinned per project)
npm install -g serve

# As a project dev dep (when you want `npx serve` reproducibly)
npm install -D serve

# One-off
npx serve dist

Output: serve binary on PATH. Library import serve (programmatic) and serve-handler (Express/Connect-compatible middleware) also exported.

Versioning & Node support

• Current major line is 14.x (released 2023) — major rewrite for modular handlers, dropped Node 14 support.
• Recent releases require Node 18+ or 20+.
• The bundled serve-handler package (the actual serving logic) is published separately and used by Vercel internals as well.

Package metadata

• Maintainer: Vercel.
• Project home: github.com/vercel/serve
• npm: npmjs.com/package/serve
• License: MIT
• First released: 2014 (as list, renamed to serve in 2017).
• Downloads: ~5-7 million per week — partly direct, partly transitive via various CLI scaffolds.

Peer dependencies & extras

serve bundles its own dependencies (chalk, clipboardy, compression, content-disposition, mime, etc.). No peer deps and no companion packages typically needed.

Alternatives

Common gotchas

1. SPA mode is opt-in. serve defaults to a 404 for missing paths. SPAs need serve -s (single-page mode) which rewrites all unmatched requests to index.html.
2. The dist/ arg is optional. serve with no arg serves the current directory — useful but dangerous (will expose .env, node_modules, etc., if you forget).
3. Directory listings default to ON. A path with no index.html shows a navigable directory tree. Disable with -l (no listing) or a serve.json config.
4. Default port is 3000. Override with -p PORT or env PORT=5000. Collisions with other dev servers are common.
5. HTTPS is NOT built-in. Use --ssl-cert / --ssl-key with your own self-signed cert, or mkcert for trusted local certs.
6. No --watch / file-change reload. For live-reload, use Vite's preview or pair with live-server.
7. No proxy support. If you need to proxy /api/* to a backend during preview, switch to vite preview --host (or a tool like local-web-server).
8. Clipboardy may break in headless CI. On first run, serve tries to copy the URL to clipboard; in containers without xclip/wl-clipboard it logs a warning. Set CLIPBOARD=false or use --no-clipboard (v14+).

Real-world recipes

Serve a static directory

npx serve dist

Output:

 ┌──────────────────────────────────────────────────┐
 │   Serving!                                       │
 │   - Local:    http://localhost:3000              │
 │   - Network:  http://192.168.1.5:3000            │
 │   Copied local address to clipboard!             │
 └──────────────────────────────────────────────────┘

SPA fallback

For any SPA where the router handles client-side paths (React Router, Vue Router, etc.):

npx serve -s dist

Output:

   ┌──────────────────────────────────────┐
   │  Serving!                            │
   │  Local: http://localhost:3000        │
   │  SPA mode: 404 → index.html          │
   └──────────────────────────────────────┘

-s (single-page mode) rewrites any 404 to /index.html, so /users/42 reaches the SPA shell which then routes.

Custom port and host binding

# Pick a non-default port and bind to all interfaces
npx serve -l 5000 dist

# Bind to a specific interface
npx serve -l tcp://127.0.0.1:5000 dist

# Unix socket
npx serve -l unix:/tmp/serve.sock dist

Output:

   ┌──────────────────────────────────────┐
   │  Serving!                            │
   │  Local: http://localhost:5000        │
   └──────────────────────────────────────┘

Basic auth via serve.json

serve reads serve.json from the served directory. Auth is implemented in a headers or redirects block (no native basic-auth flag), but the most common usage is serve-handler programmatically:

// server.mjs
import { createServer } from "node:http";
import handler from "serve-handler";

createServer((req, res) => {
  const auth = req.headers.authorization;
  if (auth !== `Basic ${Buffer.from("admin:hunter2").toString("base64")}`) {
    res.writeHead(401, { "WWW-Authenticate": 'Basic realm="preview"' });
    return res.end();
  }
  return handler(req, res, { public: "dist" });
}).listen(3000);

For built-in basic auth without code, use local-web-server or a Caddy reverse proxy.

CORS headers via serve.json

// serve.json (in the served directory)
{
  "headers": [
    {
      "source": "**/*",
      "headers": [
        { "key": "Access-Control-Allow-Origin", "value": "*" },
        { "key": "Cache-Control", "value": "no-store" }
      ]
    }
  ]
}

npx serve dist

Output:

   ┌──────────────────────────────────────┐
   │  Serving!                            │
   │  Local: http://localhost:3000        │
   └──────────────────────────────────────┘

The headers apply to all responses. source is a glob; use specific patterns for per-route control.

Custom rewrites and redirects

// serve.json
{
  "rewrites": [
    { "source": "/api/:slug", "destination": "/api.json" }
  ],
  "redirects": [
    { "source": "/old/:slug", "destination": "/new/:slug", "type": 301 }
  ]
}

HTTPS for local preview

# Generate a cert with mkcert (https://github.com/FiloSottile/mkcert)
mkcert -install
mkcert localhost

npx serve --ssl-cert localhost.pem --ssl-key localhost-key.pem dist

Output:

The local CA is now installed in the system trust store!
Created a new certificate valid for localhost
   ┌──────────────────────────────────────┐
   │  Serving!                            │
   │  Local: https://localhost:3000       │
   └──────────────────────────────────────┘

Output now binds to https://localhost:3000 with a trusted cert.

Smoke-testing a build output

// package.json
{
  "scripts": {
    "build": "vite build",
    "preview": "serve -s dist",
    "smoke": "concurrently -k -s first \"npm:preview\" \"wait-on http://localhost:3000 && playwright test\""
  }
}

The CI runs npm run build && npm run smoke to confirm the built output works end-to-end.

Production deployment

Don't. serve is not a production server.

For static production hosting:

• Vercel / Netlify / Cloudflare Pages — zero-config CDN-backed static hosting, often free.
• Caddy — single-binary production server with auto-HTTPS.
• nginx — the classic high-performance static server.
• Bun — bun --bun serve is production-capable.
• AWS S3 + CloudFront, Cloudflare R2, etc. — for very-high-volume.

serve lacks: HTTP/2, HTTP/3, automatic TLS, request logging that respects log-rotation, graceful reload, process supervision, ACME integration. The architecture is "single Node process; restart on crash" — fine for previews, not for Cache-Control-aware production.

Performance tuning

serve is a thin layer over Node's http module. Performance knobs are minimal:

• --cors adds a CORS header to every response — not a perf issue, but watch large file responses.
• Compression is on by default for text mime-types. Disable with --no-compression if you're hosting already-gzipped artefacts (e.g. brotli pre-compressed).
• No HTTP/2. For static-only with HTTP/2, switch to Caddy or run nginx in front.

For high throughput (>1k req/s), use Caddy or nginx — Node's single-threaded http becomes the bottleneck.

Version migration guide

From legacy alternatives

If you're migrating from python -m http.server, the main extras are: SPA fallback, compression, configurable headers, MIME-type breadth. Direct CLI replacement; same workflow.

Security considerations

1. Default directory listings expose secrets. Serving the wrong directory (. from a project root) leaks .env, node_modules, .git. Always serve a specific subdirectory (dist, public).
2. No authentication by default. Anyone with network access to the port can fetch every file. Bind to 127.0.0.1 for local-only with -l tcp://127.0.0.1:PORT.
3. Path traversal protection is in serve-handler. As of recent versions, ../ requests are rejected. Keep up to date — older versions had path-traversal CVEs.
4. --ssl-cert / --ssl-key use whatever you provide. Self-signed certs work; for public exposure use Let's Encrypt via Caddy, not serve.
5. No rate limiting, no DDoS protection. Putting serve directly on the public internet invites trouble.

Configuration patterns

serve.json

Place in the served directory. Full schema includes:

{
  "public": "dist",
  "cleanUrls": true,
  "trailingSlash": false,
  "rewrites": [
    { "source": "/app/**", "destination": "/index.html" }
  ],
  "redirects": [
    { "source": "/old/**", "destination": "/new/:_/*", "type": 301 }
  ],
  "headers": [
    {
      "source": "**/*.{js,css}",
      "headers": [{ "key": "Cache-Control", "value": "public, max-age=31536000, immutable" }]
    }
  ],
  "directoryListing": false,
  "renderSingle": true,
  "etag": true,
  "symlinks": false
}

Programmatic via serve-handler

import { createServer } from "node:http";
import handler from "serve-handler";

createServer((req, res) =>
  handler(req, res, { public: "dist", rewrites: [{ source: "**", destination: "/index.html" }] })
).listen(3000);

This is what serve itself does under the hood.

Troubleshooting common errors

• EADDRINUSE — port collision. serve -l 5001 dist or kill the other process (lsof -i :3000).
• "Copied local address to clipboard" warning in CI — clipboardy can't find a clipboard tool. Set CLIPBOARD=false env or use --no-clipboard.
• 404s on every SPA route — missing -s flag.
• MIME-type mismatch — serve uses the mime package's tables. For non-standard types (.wasm, .json variants), add a headers block in serve.json setting Content-Type explicitly.
• CORS errors — add headers entry in serve.json or use --cors flag (v14+: --cors enables permissive CORS for all routes).

Ecosystem integrations

• Vercel deployments — serve is what Vercel runs internally for static builds. Local parity is one reason to prefer it over http-server.
• CI smoke tests — pair with start-server-and-test or wait-on for "build → serve → run e2e → tear down" loops.
• Docker — minimal Dockerfile: FROM node:20-alpine; RUN npm install -g serve; COPY dist /app; CMD serve -s -l 3000 /app. Decent for ephemeral previews; not for production.

When NOT to use this

• Production traffic. Use Caddy, nginx, Vercel, Netlify, Cloudflare Pages, or any real CDN.
• You need a reverse proxy / API mocking. Use Vite preview, local-web-server, or set up a real proxy with Caddy.
• Live-reload during development. Use the framework's dev server (Vite, Next, Astro, etc.) — they hot-reload; serve doesn't.
• HTTPS without configuration. Caddy auto-provisions Let's Encrypt; serve requires manual cert files.
• You already have Bun installed. bun --bun serve is faster and built in.
• You want HTTP/2 or HTTP/3. Not supported.
• You only need to share one file briefly. python -m http.server or bun --bun serve are smaller-footprint alternatives.

serve is the right tool for the 30-second "verify my SPA build worked" loop. Outside that, reach for a more specialised tool.

See also

• Packages: npm-http-server — alternative static server
• Concept: HTTP — request/response lifecycle