#!/usr/bin/env node // A local stand-in for a Vercel deployment of a site with no framework: static // files, Node functions under api/, and the rewrites in vercel.json. It does // what a real deployment did when we measured one on 2026-11-19 // (Fluid compute, Node 24, framework "Other"): // // - The filesystem comes first (static files, then functions), and the // rewrites after it. // - A rewritten request keeps the URL the browser asked for. The parameters // the rewrite matched are appended to its query (`/rw/a/b` through // `/rw/:path*` reaches the function as `/rw/a/b?path=a%2Fb`). // - `api/[name].js` matches one path segment, and so does // `api/[...name].js`: outside Next.js it is not a catch-all. The segment // reaches the function as `?name=` (or `?...name=`). // - x-forwarded-for, x-real-ip and x-forwarded-proto come from the // connection. Whatever a client sent in them is replaced. // - Exported GET/POST/… functions, and `export default { fetch }`, get a Web // Request. A default-exported function gets Vercel's (req, res) helpers: // req.query, req.cookies, a parsed req.body, res.status/json/send/redirect. // req.url is the browser's path, as above. // - With a public/ folder, only that folder is served. Without one, the // project's root is, except api/, node_modules, dotfiles, package files // and vercel.json: server modules in lib/ are readable, as on Vercel. // - A path nothing serves gets Vercel's NOT_FOUND page; a function that // throws, FUNCTION_INVOCATION_FAILED; one that outlasts its maxDuration // (vercel.json `functions`, default 300 s), FUNCTION_INVOCATION_TIMEOUT. // // Not emulated: instances being suspended, replaced or run side by side // (one process serves every request, and the modules a function imports are // shared between functions), the Edge runtime, and vercel.json's redirects, // headers, has/missing conditions and external rewrites. // // node vercel-local.mjs [--root ] [--port 3000] [--host 127.0.0.1] // // tests/vercel-functions/vercel-local.mjs is the original; the trial fixture in // trials/platforms/vercel-functions keeps an identical copy, which // tests/vercel-local.test.mjs holds to it. import { randomBytes } from "node:crypto"; import { existsSync, readdirSync, readFileSync, statSync } from "node:fs"; import { createServer } from "node:http"; import path from "node:path"; import { Readable } from "node:stream"; import { pathToFileURL } from "node:url"; const METHODS = ["GET", "HEAD", "POST", "PUT", "PATCH", "DELETE", "OPTIONS"]; const FUNCTION_EXTENSIONS = [".js", ".mjs", ".cjs"]; const DEFAULT_MAX_DURATION_S = 300; const MAX_BODY_BYTES = 4.5 * 1024 * 1024; const TYPES = { ".html": "text/html; charset=utf-8", ".css": "text/css; charset=utf-8", ".js": "application/javascript; charset=utf-8", ".mjs": "application/javascript; charset=utf-8", ".map": "application/json; charset=utf-8", ".json": "application/json; charset=utf-8", ".svg": "image/svg+xml", ".png": "image/png", ".jpg": "image/jpeg", ".webp": "image/webp", ".ico": "image/x-icon", ".txt": "text/plain; charset=utf-8", }; const HOP_BY_HOP = new Set(["connection", "keep-alive", "transfer-encoding", "upgrade"]); const HIDDEN_AT_ROOT = new Set([ "api", "node_modules", "package.json", "package-lock.json", "vercel.json", ]); function vercelId() { return `dev1::${randomBytes(4).toString("hex")}-${Date.now()}`; } function textResponse(status, code, title) { return new Response(`${title}\n\n${code}\n\n${vercelId()}\n`, { status, headers: { "content-type": "text/plain; charset=utf-8", "x-vercel-error": code }, }); } const notFound = () => textResponse(404, "NOT_FOUND", "The page could not be found"); /** * `/openreceive/:path*` and friends (path-to-regexp's syntax) as a RegExp. * An unnamed `(.*)` is `$1`, `$2`, … in the destination. */ export function compileSource(source) { let pattern = ""; let unnamed = 0; for (const segment of source.split("/").filter(Boolean)) { const param = segment.match(/^:([A-Za-z_]\w*)(\(.*\))?([*+?])?$/); if (param) { const [, name, custom, modifier] = param; const repeats = modifier === "*" || modifier === "+"; const body = custom ? custom.slice(1, -1) : repeats ? ".+" : "[^/]+"; const group = `(?<${name}>${body})`; pattern += modifier === "*" || modifier === "?" ? `(?:/${group})?` : `/${group}`; } else if (segment === "(.*)") { unnamed += 1; pattern += `/(?<_${unnamed}>.*)`; } else { pattern += `/${segment.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}`; } } return new RegExp(`^${pattern || "/"}/?$`); } /** * The rewrite's destination for a matched path, and the named parameters it * did not use: Vercel appends those to the query. */ export function applyRewrite(rewrite, pathname) { const match = rewrite.regex.exec(pathname); if (match === null) return undefined; let destination = rewrite.destination; const appended = []; for (const [name, value] of Object.entries(match.groups ?? {})) { if (value === undefined) continue; if (name.startsWith("_")) { destination = destination.replaceAll(`$${name.slice(1)}`, value); continue; } const placeholder = new RegExp(`:${name}(?!\\w)[*+?]?`, "g"); if (placeholder.test(destination)) destination = destination.replace(placeholder, value); else appended.push([name, value]); } return { destination, appended }; } /** Every function file under api/, as a route pattern ranked static-first. */ export function functionRoutes(root) { const apiDir = path.join(root, "api"); const routes = []; const walk = (directory, segments) => { if (!existsSync(directory)) return; for (const entry of readdirSync(directory, { withFileTypes: true })) { if (entry.name.startsWith(".") || entry.name.startsWith("_")) continue; const full = path.join(directory, entry.name); if (entry.isDirectory()) { walk(full, [...segments, entry.name]); continue; } const extension = path.extname(entry.name); if (!FUNCTION_EXTENSIONS.includes(extension)) continue; const name = entry.name.slice(0, -extension.length); const parts = ["api", ...segments, ...(name === "index" ? [] : [name])]; const params = []; const pattern = parts .map((part) => { const dynamic = part.match(/^\[(\.\.\.)?([^\]]+)\]$/); if (!dynamic) return part.replace(/[.*+?^${}()|[\]\\]/g, "\\$&"); params.push(`${dynamic[1] ?? ""}${dynamic[2]}`); return "([^/]+)"; }) .join("/"); routes.push({ file: full, relative: path.relative(root, full).split(path.sep).join("/"), regex: new RegExp(`^/${pattern}/?$`), params, rank: params.length, }); } }; walk(apiDir, []); return routes.sort((left, right) => left.rank - right.rank); } function matchFunction(routes, pathname) { for (const route of routes) { const match = route.regex.exec(pathname); if (match === null) continue; return { route, appended: route.params.map((name, index) => [name, decodeURIComponent(match[index + 1])]), }; } return undefined; } /** A glob from vercel.json `functions` ("api/**\/*.js") against a file. */ function globMatches(glob, file) { const regex = glob .split("/") .map((part) => part === "**" ? "(?:.*)" : part .replace(/[.+^${}()|[\]\\]/g, "\\$&") .replace(/\*/g, "[^/]*") .replace(/\?/g, "[^/]"), ) .join("/") .replace(/\(\?:\.\*\)\//g, "(?:.*/)?"); return new RegExp(`^${regex}$`).test(file); } function staticFile(root, staticRoot, pathname) { let decoded; try { decoded = decodeURIComponent(pathname); } catch { return undefined; } const relative = path.normalize(decoded).replace(/^(\.\.(\/|\\|$))+/, ""); const parts = relative.split(/[/\\]/).filter(Boolean); if (parts.some((part) => part.startsWith("."))) return undefined; if (staticRoot === root && parts.length > 0 && HIDDEN_AT_ROOT.has(parts[0])) return undefined; let file = path.join(staticRoot, ...parts); if (!file.startsWith(staticRoot)) return undefined; if (existsSync(file) && statSync(file).isDirectory()) file = path.join(file, "index.html"); return existsSync(file) && statSync(file).isFile() ? file : undefined; } function serveStatic(file, method) { const body = method === "HEAD" ? null : readFileSync(file); return new Response(body, { status: 200, headers: { "content-type": TYPES[path.extname(file).toLowerCase()] ?? "application/octet-stream", "cache-control": "public, max-age=0, must-revalidate", }, }); } function parseCookies(header) { const cookies = {}; for (const part of (header ?? "").split(";")) { const at = part.indexOf("="); if (at <= 0) continue; const name = part.slice(0, at).trim(); const value = part.slice(at + 1).trim(); try { cookies[name] = decodeURIComponent(value); } catch { cookies[name] = value; } } return cookies; } function queryObject(searchParams) { const query = {}; for (const [key, value] of searchParams) { if (key in query) query[key] = [].concat(query[key], value); else query[key] = value; } return query; } /** Vercel's (req, res) helpers on Node's own objects. */ function legacyInvoke(handler, nodeReq, nodeRes, url, bodyBuffer) { const contentType = (nodeReq.headers["content-type"] ?? "").split(";")[0].trim().toLowerCase(); let parsed; let parsedOnce = false; Object.defineProperty(nodeReq, "body", { configurable: true, get() { if (parsedOnce) return parsed; parsedOnce = true; if (bodyBuffer === undefined || bodyBuffer.length === 0) return undefined; const text = bodyBuffer.toString("utf8"); if (contentType === "application/json") { try { parsed = JSON.parse(text); } catch { const error = new Error("Invalid JSON"); error.statusCode = 400; throw error; } } else if (contentType === "application/x-www-form-urlencoded") { parsed = queryObject(new URLSearchParams(text)); } else if (contentType.startsWith("text/")) { parsed = text; } else { parsed = bodyBuffer; } return parsed; }, }); nodeReq.url = `${url.pathname}${url.search}`; nodeReq.query = queryObject(url.searchParams); nodeReq.cookies = parseCookies(nodeReq.headers.cookie); nodeRes.status = (code) => { nodeRes.statusCode = code; return nodeRes; }; nodeRes.send = (body) => { if (body === undefined || body === null) return nodeRes.end(); if (Buffer.isBuffer(body)) { if (!nodeRes.getHeader("content-type")) nodeRes.setHeader("content-type", "application/octet-stream"); return nodeRes.end(body); } if (typeof body === "object") return nodeRes.json(body); if (!nodeRes.getHeader("content-type")) nodeRes.setHeader("content-type", "text/html; charset=utf-8"); return nodeRes.end(String(body)); }; nodeRes.json = (body) => { nodeRes.setHeader("content-type", "application/json; charset=utf-8"); return nodeRes.end(JSON.stringify(body)); }; nodeRes.redirect = (statusOrUrl, maybeUrl) => { const [status, location] = typeof statusOrUrl === "number" ? [statusOrUrl, maybeUrl] : [307, statusOrUrl]; nodeRes.statusCode = status; nodeRes.setHeader("location", location); return nodeRes.end(); }; return new Promise((resolve, reject) => { nodeRes.on("finish", resolve); nodeRes.on("close", resolve); Promise.resolve() .then(() => handler(nodeReq, nodeRes)) .catch(reject); }); } async function readBody(nodeReq) { const chunks = []; let size = 0; for await (const chunk of nodeReq) { size += chunk.length; if (size > MAX_BODY_BYTES) throw Object.assign(new Error("body too large"), { statusCode: 413 }); chunks.push(chunk); } return Buffer.concat(chunks); } async function writeResponse(nodeRes, response, method) { const headers = {}; for (const [name, value] of response.headers) { if (name === "set-cookie") continue; headers[name] = value; } const cookies = response.headers.getSetCookie(); if (cookies.length > 0) headers["set-cookie"] = cookies; nodeRes.writeHead(response.status, headers); if (method === "HEAD" || response.body === null) { nodeRes.end(); return; } for await (const chunk of Readable.fromWeb(response.body)) nodeRes.write(chunk); nodeRes.end(); } export function createVercelLocal({ root, log = (line) => console.log(line), logError = (error) => console.error(error), }) { const absoluteRoot = path.resolve(root); const configFile = path.join(absoluteRoot, "vercel.json"); const config = existsSync(configFile) ? JSON.parse(readFileSync(configFile, "utf8")) : {}; for (const key of ["redirects", "headers", "routes"]) { if (config[key] !== undefined) log(`vercel-local: vercel.json "${key}" is not emulated`); } const rewrites = (config.rewrites ?? []).map((rewrite) => { if (rewrite.has !== undefined || rewrite.missing !== undefined) { throw new Error( `vercel-local: rewrite ${rewrite.source} uses has/missing, which is not emulated`, ); } return { ...rewrite, regex: compileSource(rewrite.source) }; }); const publicDir = path.join(absoluteRoot, "public"); const staticRoot = existsSync(publicDir) ? publicDir : absoluteRoot; const routes = functionRoutes(absoluteRoot); const modules = new Map(); const maxDurationFor = (relative) => { for (const [glob, settings] of Object.entries(config.functions ?? {})) { if (globMatches(glob, relative) && typeof settings.maxDuration === "number") return settings.maxDuration; } return DEFAULT_MAX_DURATION_S; }; const loadModule = (route) => { let loaded = modules.get(route.file); if (loaded === undefined) { loaded = import(pathToFileURL(route.file).href); modules.set(route.file, loaded); loaded .then((module) => { if (module.config?.runtime === "edge") { log( `vercel-local: ${route.relative} asks for the Edge runtime, which is not emulated; it runs on Node here`, ); } }) .catch(() => modules.delete(route.file)); } return loaded; }; /** Find what serves `pathname`: a static file or a function, then the rewrites. */ const resolve = (pathname) => { const direct = staticFile(absoluteRoot, staticRoot, pathname); if (direct) return { kind: "static", file: direct }; const fn = matchFunction(routes, pathname); if (fn) return { kind: "function", ...fn }; for (const rewrite of rewrites) { const applied = applyRewrite(rewrite, pathname); if (applied === undefined) continue; if (/^https?:\/\//.test(applied.destination)) return { kind: "external" }; const target = new URL(applied.destination, "http://destination.invalid"); const extra = [...target.searchParams]; const file = staticFile(absoluteRoot, staticRoot, target.pathname); if (file) return { kind: "static", file }; const rewritten = matchFunction(routes, target.pathname); if (rewritten) { return { kind: "function", route: rewritten.route, appended: [...extra, ...rewritten.appended, ...applied.appended], }; } return { kind: "missing" }; } return { kind: "missing" }; }; const handle = async (nodeReq, nodeRes) => { const started = Date.now(); const method = (nodeReq.method ?? "GET").toUpperCase(); const remote = (nodeReq.socket.remoteAddress ?? "127.0.0.1").replace(/^::ffff:/, ""); const host = nodeReq.headers.host ?? "localhost"; const url = new URL(nodeReq.url ?? "/", `http://${host}`); // Vercel sets these from the connection, never from the client. nodeReq.headers["x-forwarded-for"] = remote; nodeReq.headers["x-real-ip"] = remote; nodeReq.headers["x-vercel-forwarded-for"] = remote; nodeReq.headers["x-forwarded-proto"] = "http"; nodeReq.headers["x-forwarded-host"] = host; nodeReq.headers["x-vercel-id"] = vercelId(); let status = 500; try { const target = resolve(url.pathname); if (target.kind === "static") { const response = method === "GET" || method === "HEAD" ? serveStatic(target.file, method) : textResponse(405, "METHOD_NOT_ALLOWED", "Method not allowed"); status = response.status; await writeResponse(nodeRes, response, method); return; } if (target.kind !== "function") { const response = target.kind === "external" ? textResponse( 502, "EXTERNAL_REWRITE_NOT_EMULATED", "External rewrites are not emulated", ) : notFound(); status = response.status; await writeResponse(nodeRes, response, method); return; } for (const [name, value] of target.appended) url.searchParams.append(name, value); const body = method === "GET" || method === "HEAD" ? undefined : await readBody(nodeReq); const module = await loadModule(target.route); const maxDurationMs = maxDurationFor(target.route.relative) * 1000; const named = METHODS.filter((name) => typeof module[name] === "function"); let work; if (named.length > 0 || typeof module.default?.fetch === "function") { const fn = module[method] ?? (named.length === 0 ? module.default.fetch.bind(module.default) : undefined); if (fn === undefined) { const response = textResponse(405, "METHOD_NOT_ALLOWED", "Method not allowed"); status = 405; await writeResponse(nodeRes, response, method); return; } const headers = new Headers(); for (const [name, value] of Object.entries(nodeReq.headers)) { if (value === undefined || HOP_BY_HOP.has(name)) continue; for (const one of [].concat(value)) headers.append(name, one); } const request = new Request(url, { method, headers, body: body?.length ? body : undefined, }); // A handler that throws before it returns a promise fails the same way. work = Promise.resolve() .then(() => fn(request)) .then(async (response) => { if (!(response instanceof Response)) throw new TypeError(`${target.route.relative} did not return a Response`); // A reply after the timeout answered has nowhere to go. if (nodeRes.headersSent) return; status = response.status; await writeResponse(nodeRes, response, method); }); work.catch(() => {}); } else if (typeof module.default === "function") { work = legacyInvoke(module.default, nodeReq, nodeRes, url, body).then(() => { status = nodeRes.statusCode; }); } else { throw new TypeError(`${target.route.relative} exports no handler`); } let timer; const timeout = new Promise((resolveTimeout) => { timer = setTimeout(() => resolveTimeout("timeout"), maxDurationMs); }); let outcome; try { outcome = await Promise.race([work, timeout]); } finally { clearTimeout(timer); } if (outcome === "timeout") { status = 504; if (!nodeRes.headersSent) { await writeResponse( nodeRes, textResponse( 504, "FUNCTION_INVOCATION_TIMEOUT", "An error occurred with your deployment", ), method, ); } else nodeRes.destroy(); } } catch (error) { status = error?.statusCode ?? 500; logError(error); if (!nodeRes.headersSent) { const response = status === 400 || status === 413 ? textResponse( status, status === 400 ? "INVALID_REQUEST" : "FUNCTION_PAYLOAD_TOO_LARGE", "Bad request", ) : textResponse(500, "FUNCTION_INVOCATION_FAILED", "A server error has occurred"); status = response.status; await writeResponse(nodeRes, response, method).catch(() => nodeRes.destroy()); } else nodeRes.destroy(); } finally { log(`${method} ${url.pathname} ${status} ${Date.now() - started}ms`); } }; return createServer((nodeReq, nodeRes) => { handle(nodeReq, nodeRes).catch((error) => { logError(error); nodeRes.destroy(); }); }); } const isMain = process.argv[1] !== undefined && import.meta.url === pathToFileURL(path.resolve(process.argv[1])).href; if (isMain) { const flag = (name, fallback) => { const at = process.argv.indexOf(name); return at === -1 ? fallback : process.argv[at + 1]; }; const root = flag("--root", process.cwd()); const port = Number(flag("--port", process.env.PORT ?? "3000")); const host = flag("--host", "127.0.0.1"); const server = createVercelLocal({ root }); server.listen(port, host, () => console.log(`vercel-local: serving ${path.resolve(root)} on http://${host}:${port}`), ); for (const signal of ["SIGINT", "SIGTERM"]) { process.on(signal, () => { server.close(() => process.exit(0)); server.closeAllConnections(); }); } }