netlify-caching

Files (1)

• SKILL.md

SKILL.md (first lines)

# 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:

```ts
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` applies to the Netlify CDN only. **Reach for this.**
- `CDN-Cache-Control` applies to all CDNs that support it.
- `Cache-Control` applies to 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)

- **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.
- **Cache API silently drops responses over 10 MB.** `cache.put()` doesn't store them and later lookups miss. Compress the content or split it across multiple entries.
- Never opt sensitive content out of automatic invalidation. It can stay publicly cached after deploys/firewall changes.

## Directives

- `public` caches the response. `private` caches it in the browser only, not in Netlify's shared cache. `no-store` prevents caching.
- `s-maxage=N` sets seconds in Netlify's shared cache (overrides `max-age` there).
- `max-age=N` sets seconds in any cache.
- `stale-while-revalidate=N` serves stale for N seconds after expiry while revalidating in the background.
- `durable` (serverless only) stores the response 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` varies on a subset; bare `query` varies on all params. Keys are case-sensitive; param order is irrelevant.
- `header=Device-Type|App-Version` supports custom and most standard headers.
- `language=en|es+pt` uses `+` for groups. It is checked against `Accept-Language` with quality weighting.
- `country=us|es+pt` uses GeoIP with ISO 3166-1 two-letter codes; `+` groups.
- `cookie=ab_test|is_logged_in` targets 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` and 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`, so 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`. Values are comma-separated, auto-registered as cache tags for purging, and have a 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`. The site ID is passed automatically:

```ts
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:

```ts
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 });
};
```

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

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

From netlify/context-and-tools, MIT.

More from netlify/context-and-tools