Response headers: HTTP caching & compression

Between your server and the user sit two kinds of HTTP cache (RFC 9111):

• a private cache: the browser's, for one user;
• a shared cache: a CDN or reverse proxy, serving the same stored response to everyone.

Cache-Control talks to both, and the two most-used directives each pick an audience:

• max-age=N: fresh for N seconds, in any cache.
• s-maxage=N: fresh for N seconds in shared caches only. It overrides max-age there, and browsers ignore it.

So one header can say "the CDN may keep this for a day, the browser must check every time":

// app/api/catalog/route.ts — the same JSON for every visitor
export async function GET() {
  const catalog = await getCatalog();
  return Response.json(catalog, {
    headers: { "Cache-Control": "public, max-age=0, s-maxage=86400" },
  });
}

The CDN answers from its copy for a day, so your function runs roughly once a day per CDN location instead of once per visitor (on Vercel, each new deployment starts with an empty cache). The browser keeps nothing fresh, so users never sit on an old copy the CDN has already replaced.

Four recipes cover most responses:

private keeps shared caches out: a CDN must not store it, but the user's own browser may. public is the reverse permission, and you rarely need it: a max-age or s-maxage already makes a normal response cacheable. Its real job is overriding the rule that a shared cache won't store the answer to a request that carried an Authorization header (s-maxage and must-revalidate lift that rule too).

A stored response is fresh while its age is below its lifetime, and stale after. RFC 9111 picks the lifetime in a fixed order: in a shared cache s-maxage first, then max-age, then Expires minus Date, then a heuristic. Fresh responses are served without asking the server. Stale ones are usually revalidated, not thrown away.

Revalidation with an ETag. The server labels each version of a resource; the cache sends the label back:

$ curl -s -o /dev/null -D - -H 'If-None-Match: "v1"' http://127.0.0.1:4517/data
HTTP/1.1 304 Not Modified
Cache-Control: public, max-age=0, must-revalidate
ETag: "v1"
Vary: Accept-Encoding
Date: Sat, 17 Oct 2026 10:13:21 GMT

That transcript is from a 25-line node:http server (connection headers trimmed): when If-None-Match matches the current ETag, it answers 304 with no body. RFC 9110 requires a 304 to repeat the headers a 200 would have sent among Cache-Control, ETag, Vary and Date, so the cache can update its copy, and forbids it from carrying content. A changed resource gets a normal 200 with a new ETag. Next.js generates ETags for pages by default (generateEtags in next.config).

stale-while-revalidate=N (RFC 5861) lets a cache keep serving the stale copy for up to N more seconds while it revalidates in the background:

Cache-Control: public, max-age=60, stale-while-revalidate=300

For the first 60 seconds: fresh, served directly. From 60 to 360: served stale instantly, with a refresh in the background so the next visitor gets new content. After 360: the cache must wait for the server. must-revalidate is the opposite promise: once stale, never serve without checking.

Vary widens the cache key. By default a cache keys on method and URL. If the response depends on a request header, name it:

Vary: Accept-Encoding

Now the cache stores a gzip copy and a brotli copy separately and never hands brotli to a client that didn't ask for it. Choose Vary headers with few distinct values. Vary: Cookie makes nearly every visitor a separate entry, and Vercel's CDN refuses to cache such responses altogether. Per-user content belongs behind Cache-Control: private instead.

You can set a response header in three places:

// 1. A Route Handler — this one response
return new Response(body, { headers: { "Cache-Control": "public, s-maxage=3600" } });

// 2. next.config.ts headers() — every response whose path matches `source`
async headers() {
  return [{ source: "/:all*(pdf|csv)", headers: [{ key: "Cache-Control", value: "public, max-age=3600" }] }];
}

// 3. proxy.ts — responses that pass through it
const res = NextResponse.next();
res.headers.set("X-Frame-Options", "DENY");
return res;

And Next sets some itself. Pages get Cache-Control from how they render: a static page s-maxage=31536000, a revalidating page s-maxage=<revalidate>, stale-while-revalidate=…, a dynamic page private, no-cache, no-store, max-age=0, must-revalidate. Hashed files under /_next/static get public, max-age=31536000, immutable, which the docs say you cannot override. A page component itself has no API for response headers (headers() from next/headers is read-only); when you need control over one response, that's a Route Handler.

The collision. Say that /:all*(pdf|csv) rule was written for files in public/. Later a Route Handler serves /reports/q3.csv from storage and sends its own Cache-Control. Which one does the client get?

• next start: the config value. The router applies the config headers to the response first; when the handler's Response is written, Next 16's sendResponse only copies a header that isn't already set. The handler's Cache-Control is dropped with no warning; its other headers survive. (Reproduced against Next 16.2's own send-response.js.)
• Vercel: the handler's value. Vercel's Cache-Control docs state that Cache-Control returned by a function takes priority over the same header from next.config.js or vercel.json.

Same code, two answers. A route that sends no-store on its error response can have that replaced by the config's max-age=3600 on a self-hosted server, so an outage gets cached for an hour. Locally the page still renders fine, and no type check or lint rule notices.

The fixes:

• Before giving a Route Handler its own caching header, search next.config headers() for any source that matches its URL, including wildcard and file-extension rules.
• Fix overlaps in the config (narrow the source), never by "setting it harder" in the route.
• Assert response headers in a test against a running production build, and check the deployed platform once: it may merge differently.