netlify-caching

Netlify caching

Cache-control header to reach for

Dynamic responses (Functions, Edge Functions, proxies) are NOT cached by default — you must opt in. Set Netlify-CDN-Cache-Control on the response:

import type { Context } from "@netlify/functions";

export default async (req: Request, context: Context) => {
  return new Response("Hello world", {
    headers: {
      'Netlify-CDN-Cache-Control': 'public, durable, max-age=60, stale-while-revalidate=120'
    }
  });
};

Header choice (most specific wins; CDN-Cache-Control/Cache-Control always pass downstream):

• Netlify-CDN-Cache-Control — Netlify CDN only. Reach for this.
• CDN-Cache-Control — all CDNs that support it.
• Cache-Control — any CDN or the browser.

Legacy path to avoid: On-demand Builders do not support these headers or Netlify-Vary — they use a TTL pattern and key on URL path only. Don't reach for ODBs in new code.

Footguns (read first)

• Only GET is cached. POST/PUT/etc. are never cached regardless of headers — expose cacheable data on a GET route (inputs in the URL or query string).
• netlify dev does not emulate the CDN cache. A local cache miss every time is expected. Verify caching on a deployed URL (Deploy Preview or production) via its Cache-Status header.
• Without Netlify-Vary: query=..., the full query string is the cache key — every distinct query string (utm_*, fbclid, …) is a separate cache entry. Enumerate only the params that change the response.
• Static assets are fresh for up to a year — a shorter max-age is ignored. They change only on a new deploy or manual purge.
• basic-auth on ANY page disables caching for the ENTIRE site.
• durable is serverless-only — it has no effect on Edge Function responses.
• Never opt sensitive content out of automatic invalidation — it can stay publicly cached after deploys/firewall changes.

Directives

• public cache it / private browser-only, not Netlify's shared cache / no-store don't cache.
• s-maxage=N seconds in Netlify's shared cache (overrides max-age there).
• max-age=N seconds in any cache.
• stale-while-revalidate=N serve stale for N seconds after expiry while revalidating in background.
• durable (serverless only) store in Netlify's durable cache so other edge nodes reuse it instead of re-invoking the function.