Skip to content
Tutorials Center
My learning

Topics

Lesson 31 of 37 ยท Performance and Limits

Caching and the CDN

How the edge network caches your site: Cache-Control, s-maxage and stale-while-revalidate, immutable hashed assets, ISR and on-demand revalidation, cache invalidation and purging.

Both platforms put your site on a content delivery network (CDN): servers around the world that keep copies of your files close to visitors. A request that the nearest server can answer from its copy (a cache hit) is fast and costs almost nothing. A miss travels to the origin (your function or build output), is slower, and may cost compute. Good caching is the biggest performance and cost lever you have.

The networks cannot run here. Behavior is described from documentation; platform defaults change, so confirm in current docs. The runnable code is a JavaScript stand-in of a cache with Cache-Control rules and a fake clock.

What gets cached by default

  • Static files (HTML, CSS, JS, images from your build) are served from the CDN. Netlify and Vercel manage their freshness so that a new deployment shows up immediately without you purging anything: browsers revalidate, and the edge cache is tied to the deployment.
  • Function and server-rendered responses are not cached unless you send cache headers that allow it.

Cache-Control in plain language

Cache-Control is the header that tells browsers and CDNs how long a response stays fresh.

Directive Meaning
max-age=N browsers and shared caches may reuse it for N seconds
s-maxage=N shared caches (the CDN) may reuse it for N seconds; overrides max-age there
public / private private means only the user's browser may keep it, not the CDN
no-store never keep a copy (use for personal or sensitive data)
no-cache may store it, but must revalidate before each reuse
immutable the content will never change at this URL
stale-while-revalidate=N for N seconds after expiry, serve the old copy instantly while fetching a fresh one in the background

Two classic recipes:

TEXT
# Fingerprinted assets (app.8f3a1c.js): cache for a year
Cache-Control: public, max-age=31536000, immutable

# A server-rendered page: CDN keeps it 60 s, then serves stale up to 5 min while refreshing
Cache-Control: public, s-maxage=60, stale-while-revalidate=300

Fingerprinting (a hash in the file name) is what makes the long cache safe: when the content changes the name changes, so nobody sees an old file. HTML must not be cached for a year, since it names those files. Frameworks add hashes automatically.

Cache decisions

Hashed assets One year, immutable.
HTML Short or revalidate.
SWR Serve stale, refresh behind.
Personal data private or no-store.

Never cache per-user pages publicly.

1 / 2

Simulating an edge cache

The stand-in below implements a miniature shared cache that honors s-maxage and stale-while-revalidate. Time is a variable, so results are repeatable.

JS Edge cache stand-in

Press Run (or Ctrl + Enter) to see the console output here.

No output.

Notice that visitors never waited for the origin during the STALE step: that is the point of the directive.

ISR and on-demand revalidation

Static pages are fast but go stale. Frameworks bridge the gap:

  • Incremental Static Regeneration (Next.js on Vercel, with equivalents in Nuxt, SvelteKit and others, and Netlify through its framework adapters): a page is built once, served from the CDN, and re-generated in the background after a revalidate interval, much like stale-while-revalidate.
  • On-demand revalidation: call an API route or function (revalidatePath, revalidateTag in Next.js) from your CMS webhook when content changes, so updates appear in seconds without waiting for a timer.
  • Cache tags let you purge many pages at once: tag all pages that show product 42 and invalidate that tag.

Both platforms also expose purge APIs for manually clearing cached function responses.

A cache-key mistake

A cache stores one response per cache key: usually the URL and chosen headers. Two problems follow:

  1. Personalized HTML cached publicly. If a page greets "Hello Ada" and is cached with public, the next visitor may see Ada's name. Personalization must be done client-side after load, or the response must be private/no-store.
  2. Too many keys. If random query parameters (?utm_source=...) are part of the key, each variation is a separate miss. Strip tracking parameters, or configure the cache to ignore them.

The stand-in helps visualize the second one:

JS Cache key stand-in

Press Run (or Ctrl + Enter) to see the console output here.

No output.

Debugging cache behavior

Open the Network panel or run curl -I and read the response headers. Vercel adds x-vercel-cache (values like HIT, MISS, STALE, PRERENDER), and Netlify adds cache-status and x-nf-request-id. age: shows seconds since the CDN stored the response. If a "static" page misses every time, look for Set-Cookie headers, Cache-Control: no-store from your framework, or dynamic functions you did not intend.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. Which header lets the CDN keep a page for 60 seconds but a browser use its own rule?

    s-maxage applies to shared caches such as CDNs, while max-age governs browsers.
  2. 2. Why is it safe to cache a fingerprinted file like app.8f3a1c.js for a year?

    The URL itself identifies the exact content, which makes the cached copy permanent.
  3. 3. What does stale-while-revalidate do?

    Visitors get a fast response and the cache refreshes for the next one.
  4. 4. A page shows the logged-in user's name. How should it be cached?

    A public cache could serve one person's page to another.

Summary

  • The CDN serves cached copies near users; hits are fast and cheap.
  • Static assets are managed automatically; dynamic responses need cache headers.
  • Use long immutable caching for hashed assets, short or SWR caching for pages.
  • ISR and on-demand revalidation keep static pages fresh.
  • Never publicly cache personalized content; inspect headers when debugging.

Next: Images and Web Vitals