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.

Defaults when no header is set — static: Netlify-CDN-Cache-Control: public, s-maxage=31536000, must-revalidate; dynamic: Cache-Control: public, max-age=0, must-revalidate.

Cache key variation — Netlify-Vary

Comma-delimited instructions on the response; pipe-delimited value lists:

Netlify-Vary: query=item_id|page, country=es+de|us, cookie=ab_test|is_logged_in

• query=a|b subset, or bare query for all params. Keys case-sensitive; param order irrelevant.
• header=Device-Type|App-Version — custom + most standard headers.
• language=en|es+pt — + groups; checked against Accept-Language with quality weighting.
• country=us|es+pt — GeoIP, ISO 3166-1 two-letter codes; + groups.
• cookie=ab_test|is_logged_in — target specific keys, not the whole Cookie header.

Cannot vary by header on: Accept*, Cache-Control, Connection, Content-Length, Cookie, Host, If-*, Range, Referer, Upgrade, User-Agent. For language/cookie/format use Vary: Accept-Language/Vary: Cookie or the specific Netlify-Vary instruction.

Consistency rule: a URL must return the same Netlify-Vary on every response — the first cached response's instructions win and later ones are ignored. Netlify-Vary + standard Vary are both respected (use Vary for format/encoding, and to pass instructions to an upstream CDN like Cloudflare).

Cache tags & opt-out

Tag responses for taggable purging:

Netlify-Cache-Tag: tag1,tag2,tag3

• Netlify-Cache-Tag (Netlify CDN) wins over Cache-Tag (passed downstream). Some providers strip Cache-Tag — set both when proxying through them.
• Constraints: case-insensitive, UTF-8 only, ≤1024 chars/tag, ≤500 tags/response.

Opt a response out of automatic atomic-deploy invalidation with Netlify-Cache-ID (comma-separated; auto-registered as cache tags for purging; separate 500-ID limit):

Netlify-Cache-ID: cms-proxy,product,image

After opting out, purge on-demand after relevant changes (e.g. redirect/proxy or function changes behind a Netlify-Cache-ID).

On-demand invalidation (purge)

Purge from a deployed function with purgeCache (site ID is passed automatically):

import { purgeCache } from "@netlify/functions";

export default async () => {
  await purgeCache(); // no args = purge everything for the site
  return new Response("Purged!", { status: 202 });
};

Purge by tag, optionally targeting a deploy/subdomain:

import { purgeCache } from "@netlify/functions";

export default async (req: Request) => {
  const cacheTag = new URL(req.url).searchParams.get("tag");
  if (!cacheTag) return;
  await purgeCache({
    tags: [cacheTag],
    deployAlias: "deploy-preview-11",
    domain: "early-access.company.com",
  });
  return new Response("Purged!", { status: 202 });
};

Ambient credentials only work inside a deployed function. From CI, local scripts, or the build, pass token (a personal access token read from an env var — never hardcoded) and siteID.

Lambda-compatible functions use the legacy module.exports.handler = async (event, context) => {…} signature and must pass context.clientContext.custom.purge_api_token:

import { purgeCache } from "@netlify/functions";

module.exports.handler = async (event, context) => {
  const token = context.clientContext.custom.purge_api_token;
  await purgeCache({ tags: ["tag1", "tag2"], token });
  return { body: "Purged!", statusCode: 202 };
};

Direct API (from outside a function) — POST https://api.netlify.com/api/v1/purge with Authorization: Bearer <personal_access_token> and Content-Type: application/json:

curl -X POST \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <personal_access_token>" \
  --data '{"site_slug": "mysitename", "cache_tags": ["news"], "deploy_alias": "deploy-preview-11", "domain": "early-access.company.com"}' \
  'https://api.netlify.com/api/v1/purge'

• Purge by site: site_id or site_slug. By tag: cache_tags + site. Omitting cache_tags purges the whole site; an empty cache_tags list purges NOTHING.
• Identifier mapping: in the UI (Project configuration > General > Project details), Project ID = site_id, Project name = site_slug. See https://docs.netlify.com/api-and-cli-guides/api-guides/get-started-with-api#get-site.
• Rate limit: each tag or site can be purged only twice per 5s — exceeding returns 429.

Cache API (caches global)

Programmatic read/write of HTTP responses from Functions/Edge Functions. Use for caching individual components of a route or arbitrary fetches, alongside header-based route caching.

Scope rule: caches.open() anywhere, but match/put/delete only inside the request handler — doing them at module/global scope throws.

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

const cache = await caches.open("my-cache"); // ok in global scope

export default async (req: Request, context: Context) => {
  const request = new Request("https://example.com/expensive-api");
  const cached = await cache.match(request);
  if (cached) return cached;

  const fresh = await fetch(request);
  if (fresh.ok) {
    cache.put(request, fresh.clone()).catch((error) => {
      console.error("Failed to add to the cache:", error);
    });
  }
  return fresh;
};

export const config: Config = { path: "/cache-api-example" };

CacheStorage subset:

• caches.match(request) → Response from any cache, or undefined.