serve -C (--cors): enable CORS on the Vercel serve static server

npx serve -C ./build (long form --cors) makes Vercel's serve static file server add CORS headers to every response: Access-Control-Allow-Origin: *, Access-Control-Allow-Headers: *, Access-Control-Allow-Credentials: true and Access-Control-Allow-Private-Network: true. That lets a front end on another port or host fetch the files during development. Without -C, no CORS headers are sent and cross-origin reads are blocked by the browser.

The headers serve sends

A local serve instance with --cors, a cross-origin GET and a preflight (-L turns off request logging, -n the clipboard copy):

npm init -y >/dev/null && npm install --silent --no-audit --no-fund serve@14.2.6 >/dev/null 2>&1
mkdir site && echo '{"ok":true}' > site/data.json
timeout 12 node node_modules/serve/build/main.js site -l tcp://127.0.0.1:5418 -L -n >/dev/null 2>&1 &
timeout 12 node node_modules/serve/build/main.js site -l tcp://127.0.0.1:5420 -L -n --cors >/dev/null 2>&1 &
sleep 4
echo "--- without --cors:"
curl -s -D - -o /dev/null -H "Origin: http://localhost:3000" http://127.0.0.1:5418/data.json | tr -d '\r' | grep -iE "^HTTP|^access-control"
echo "--- with --cors:"
curl -s -D - -o /dev/null -H "Origin: http://localhost:3000" http://127.0.0.1:5420/data.json | tr -d '\r' | grep -iE "^HTTP|^access-control"
echo "--- preflight with --cors:"
curl -s -D - -o /dev/null -X OPTIONS -H "Origin: http://localhost:3000" -H "Access-Control-Request-Method: GET" \
  -H "Access-Control-Request-Headers: X-Api-Version" http://127.0.0.1:5420/data.json | tr -d '\r' | grep -iE "^HTTP|^access-control"
wait

--- without --cors:
HTTP/1.1 200 OK
--- with --cors:
HTTP/1.1 200 OK
Access-Control-Allow-Origin: *
Access-Control-Allow-Headers: *
Access-Control-Allow-Credentials: true
Access-Control-Allow-Private-Network: true
--- preflight with --cors:
HTTP/1.1 200 OK
Access-Control-Allow-Origin: *
Access-Control-Allow-Headers: *
Access-Control-Allow-Credentials: true
Access-Control-Allow-Private-Network: true

The preflight gets a 200 OK with the same four headers: serve treats OPTIONS like a normal request for static files.

What the headers mean

The credentials pitfall

Access-Control-Allow-Credentials: true suggests that cookies work, but the Fetch standard forbids combining credentials with Access-Control-Allow-Origin: *. A fetch(url, { credentials: 'include' }) from another origin is therefore blocked, and the console reports the wildcard problem described on wildcard origin with credentials. Requests without credentials, which is what most static assets use, work normally.

If you need cookies or a fixed origin, set the headers yourself in serve.json:

{
  "headers": [
    {
      "source": "**/*.json",
      "headers": [
        { "key": "Access-Control-Allow-Origin", "value": "http://localhost:3000" },
        { "key": "Access-Control-Allow-Credentials", "value": "true" },
        { "key": "Vary", "value": "Origin" }
      ]
    }
  ]
}

Compared with other dev servers

For http-server see http-server --cors; for the general mechanism, the preflight request page.

FAQ