Netlify Caching

What Is This?

Overview

Netlify provides a powerful CDN caching layer that gives developers fine-grained control over how assets and responses are stored and served to users. By configuring cache headers correctly, you can dramatically improve site performance, reduce origin server load, and deliver faster experiences to visitors around the world. Understanding how Netlify's CDN interprets cache directives is essential for building production-ready web applications.

Netlify distinguishes between two types of cache instructions: standard Cache-Control headers that apply to both the CDN and the browser, and the Netlify-specific Netlify-CDN-Cache-Control header that targets only the CDN layer. This separation allows you to serve fresh content to browsers while still benefiting from long-lived CDN caching. The platform also supports advanced patterns such as stale-while-revalidate, on-demand cache purging via cache tags, and durable caching for serverless functions.

By default, static assets deployed to Netlify are cached at the CDN for one year and automatically invalidated on every new deployment. Dynamic responses from Netlify Functions or Edge Functions are not cached by default, giving you full control over when and how those responses are stored.

Who Should Use This

• Frontend developers deploying static sites or Jamstack applications who want to optimize asset delivery
• Full-stack developers building applications with Netlify Functions who need to cache API responses
• DevOps engineers configuring CDN behavior for high-traffic production environments
• Framework developers working with Next.js, Astro, or SvelteKit on Netlify who need framework-specific caching patterns
• Performance engineers investigating cache hit rates and CDN behavior for optimization
• Teams implementing incremental static regeneration or on-demand revalidation workflows

Why Use It?

Problems It Solves

• Slow page loads caused by uncached dynamic responses that hit the origin server on every request
• Stale content being served to users after a deployment because cache invalidation was not configured properly
• Browser and CDN cache conflicts where aggressive CDN caching prevents users from receiving updated assets
• High serverless function invocation costs resulting from repeated identical requests that could be cached
• Difficulty purging specific cached resources without triggering a full site redeployment

Core Highlights

• Separate CDN and browser cache control using Netlify-CDN-Cache-Control alongside standard Cache-Control
• Stale-while-revalidate support for serving cached content while refreshing in the background
• Cache tags enable targeted, on-demand purging of specific resources via the Netlify API
• Durable cache allows Netlify Functions to persist computed responses across invocations
• Automatic one-year CDN caching for all static assets with deployment-based invalidation
• Edge Function responses can be cached at the CDN edge for ultra-low latency delivery
• Framework integrations provide automatic caching configuration for popular tools like Next.js

How to Use It?

Basic Usage

Set cache headers in a Netlify Function response to control CDN behavior independently from the browser:

export default async (req, context) => {
  return new Response(JSON.stringify({ data: "example" }), {
    headers: {
      "Content-Type": "application/json",
      "Cache-Control": "public, max-age=0, must-revalidate",
      "Netlify-CDN-Cache-Control": "public, max-age=3600, stale-while-revalidate=86400"
    }
  });
};

This configuration tells the browser not to cache the response locally while allowing the CDN to cache it for one hour and serve stale content for up to 24 hours during revalidation.

Specific Scenarios

Scenario 1: Caching an API response with cache tags for targeted purging

return new Response(JSON.stringify(products), {
  headers: {
    "Netlify-CDN-Cache-Control": "public, max-age=86400",
    "Cache-Tag": "products, category-electronics"
  }
});

Scenario 2: Configuring headers in netlify.toml for static assets

[[headers]]
  for = "/api/*"
  [headers.values]
    Cache-Control = "public, max-age=60, stale-while-revalidate=600"

Real-World Examples

A product catalog page can cache its data response for 24 hours at the CDN while tagging it with products. When inventory updates, a webhook triggers a purge request to the Netlify API targeting only that tag, refreshing the cache without a full redeployment.

A news site uses stale-while-revalidate on article pages so readers always receive an instant response from the CDN while the latest content is fetched in the background.

When to Use It?

Use Cases

• Caching serverless function responses to reduce invocation frequency and latency
• Implementing incremental static regeneration patterns without a full rebuild
• Serving personalized content at the edge while caching shared page shells at the CDN
• Reducing API costs by caching third-party data responses at the CDN layer
• Configuring long-lived caching for versioned static assets such as JavaScript bundles
• Setting up background revalidation for content that changes infrequently
• Purging cached product or content pages after a CMS publish event

Important Notes

Requirements

• A Netlify account with a deployed site or function
• Netlify Functions or Edge Functions runtime for setting response headers programmatically
• Access to the Netlify API or dashboard for on-demand cache purging via cache tags