netlify-caching
Cache dynamic and static responses on Netlify's CDN from Functions, Edge Functions, and proxies. Use when you add caching or cache-control headers to a function response, tune cache TTL or stale-while-revalidate, set up the durable cache, vary a cache key by query/header/cookie/country/language, purge or invalidate the cache by site or cache tag, use the programmatic Cache API (caches.open/match/put) or @netlify/cache helpers (fetchWithCache/cacheHeaders/getCacheStatus), speed up an expensive AP
Security Assessment
About netlify-caching
This skill is a practical reference for caching dynamic and static responses on Netlify's CDN from Functions, Edge Functions, and proxies. It solves the problem that dynamic responses are not cached by default and that the various cache-control headers behave subtly differently: it tells the agent to reach for Netlify-CDN-Cache-Control, explains how it relates to CDN-Cache-Control and standard Cache-Control, and lists the directives (public/private/no-store, s-maxage, max-age, stale-while-revalidate, durable) and their defaults.
It is heavy on real-world footguns: only GET is cached, netlify dev does not emulate the CDN cache so caching must be verified on a deployed URL via the Cache-Status header, the full query string becomes the cache key unless you scope it with Netlify-Vary, static assets stay fresh up to a year, basic-auth on any page disables caching site-wide, and durable is serverless-only. It documents cache-key variation with Netlify-Vary (by query, header, language, country, cookie), cache tagging and opt-out via Netlify-Cache-Tag and Netlify-Cache-ID, and on-demand purging with purgeCache from a deployed function, by tag, from Lambda-compatible functions, or via the direct HTTP purge API.
Target users are web and full-stack developers tuning CDN performance, adding ISR/on-demand revalidation, or debugging why a response is or is not cached. The skill is security-conscious: it explicitly says personal access tokens for out-of-function purges should be read from an environment variable and never hardcoded, and warns against opting sensitive content out of automatic cache invalidation — so it is benign.
FAQ
Why isn't my dynamic function response being cached?
Dynamic responses are not cached by default and only GET requests are ever cached. You must opt in by setting Netlify-CDN-Cache-Control on the response, and expose cacheable data on a GET route.
Why do I see a cache miss when testing locally?
netlify dev does not emulate the CDN cache, so a local miss every time is expected. Verify caching on a deployed Deploy Preview or production URL by inspecting the Cache-Status header.
How do I stop every query string from creating a separate cache entry?
Without Netlify-Vary, the full query string is the cache key, so params like utm_* create distinct entries. Use Netlify-Vary: query=... to enumerate only the params that actually change the response.
How do I purge or invalidate the cache?
Use purgeCache from a deployed function (site ID is passed automatically), optionally by tag or targeting a deploy alias/domain. From CI or local scripts, pass a personal access token read from an environment variable plus the site ID, or call the direct HTTP purge API.
Are there gotchas that disable caching entirely?
Yes. basic-auth on any page disables caching for the entire site, durable has no effect on Edge Function responses, and legacy On-demand Builders do not support these headers. The skill advises against ODBs in new code.
Install netlify-caching
Quick Setup:
- Copy the skill folder to
.claude/skills/ - Claude will automatically detect and use the skill
Repository
netlify/context-and-tools