serve-handler

serve-handler is a plain (request, response, config) => Promise function that implements Vercel’s static-file-serving behavior — clean URLs, redirects, rewrites, directory listings, and MIME handling — decoupled from any specific HTTP server or CLI. It is the routing engine underneath Vercel’s popular serve command-line tool, but is published independently so any Node.js HTTP server (raw http, Express, micro) can reuse the exact same static-serving logic Vercel deployments use.

Because it accepts the same now.json/vercel.json-style configuration object used by Vercel deployments (routes, redirects, headers, cleanUrls, trailingSlash), it lets developers preview or self-host static sites with production-equivalent routing behavior instead of a generic static file server.

What You Get

• A single exported handler function usable with Node’s raw http, Express, or micro
• Support for Vercel-style config (cleanUrls, redirects, rewrites, headers, trailingSlash)
• Automatic MIME type detection and correct content-type headers
• Directory listing pages when no index file is present
• Etag/last-modified based caching headers for static assets

Common Use Cases

• Powering the serve CLI’s local static-file preview server
• Embedding production-equivalent Vercel routing/redirect behavior into a custom Node.js server for local testing
• Serving a static site build (e.g. dist/ or build/) with clean URLs during a CI smoke test
• Building custom static-hosting tools that need Vercel-compatible config parsing without depending on the full CLI

Under The Hood

Architecture: The entire implementation lives in a single src/index.js (~775 lines) that parses the passed configuration object, resolves the requested path against the filesystem (with glob-based route matching in a companion glob-slash.js), and dispatches to either a static file stream, a directory listing page (rendered via directory.js using dot templates), or an error page (error.js); everything is expressed as pure functions taking (request, response, config), with no framework or server assumptions baked in. Tech Stack: Plain Node.js/JavaScript with dot for the directory-listing view template, tested via jest integration tests and linted with Vercel’s internal @zeit/eslint-config-node. Code Quality: test/integration.test.js spins up a real server via test-listen and exercises routing, redirects, and headers end-to-end rather than unit-testing internals in isolation; the project has been stable for years with infrequent but deliberate maintenance releases. API Design: The API is deliberately minimal — one function, one config object — so it drops into any existing Node.js HTTP stack (raw http.createServer, Express middleware, micro) without requiring adoption of a specific framework.