News & Announcements

Cache-tags & Purge API on Netlify

News & Announcements

Cache-tags & Purge API on Netlify

Two weeks ago, we released fine grained cache control, which provides better control over caching and revalidation behavior for dynamic content across Netlify Edge. Today we’re happy to announce yet another set of features that will give Netlify users even more control over their cached content.

While the caching instructions provided by the Cache-Control, CDN-Cache-Control, and Netlify-Cdn-Cache-Control headers are a powerful way to manage cached content lifetimes, waiting for cached content TTLs to expire is sometimes not enough as an invalidation mechanism. And re-deploying the site, although effective in purging all the site’s cached content, sometimes comes at the cost of a new site build and can affect performance for content that hasn’t changed between deploys.

Cache-tags provide a way to label your cached content across Netlify Edge so it can be purged more granularly, almost immediately, and globally. For example, you might have an e-commerce site where you want to remove the promotions for sold-out products without having to purge any of the pages from your core platform. Cache-tags allow you to do this and more without affecting the performance of the rest of the site, giving a new level of control while making the purge process simpler, faster, and more efficient.

How does cache tagging and purging work?

Netlify now supports the Cache-Tag and Netlify-Cache-Tag response headers, allowing you to associate an object—or collection of cached objects—to a tag that can be purged simultaneously across all of Netlify’s Edge, without the need for a new deploy.

Here’s an example of a Function that will be cached on Netlify Edge for up to one year. The content is tagged using Cache-Tag with the request query parameter productType, promotions, and proxy-api-response. Each of these tags provides a different level of granularity that allows purging one or many content pages simultaneously.

export default async (req: Request) => {
  const url = new URL(req.url);
  const productType = url.searchParams.get("productType");
  const resp = await fetch(`https://your-api.com/promotions/${productType}`);
  const json = await resp.json();
  const body = `<!doctype html><html>
    <head>
        <title>E-commerce promotions</title>
    </head>
    <body>
        <h2>Promotions</h2>
        <ul>${json.map((item) => `<li>${item.title}</li>`).join("\n")}</ul>
    </body><html>`;

  return new Response(body, {
    headers: {
      "Content-Type": "text/html",
      "Cache-Control": "public, max-age=0, must-revalidate", // Tell browsers to always revalidate
      "Netlify-CDN-Cache-Control": "public, max-age=31536000, must-revalidate", // Tell Edge to cache asset for up to a year,
      "Cache-Tag": `${productType},promotions,proxy-api-response` // Tag all promotions responses with these tags
    }
  });
};

Content tagged with these headers can be purged using a Netlify Function to call Netlify’s Purge API. The following function uses the capabilities of Netlify’s Improved Compute and invokes the Purge API to purge all the site’s content tagged with promotions —while leaving the remaining site’s content cached on the CDN.

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

export default async () => {
  const cacheTags = ["promotions"];
  await purgeCache({ cacheTags });

  return new Response("Purged successfully!", { status: 202 });
};

export const config: Config = {
  path: "/purge"
};

Alternatively to Cache-Tag, Netlify-Cache-Tag can be used instead, which Netlify will remove from the client response headers and it will only affect content cached in Netlify’s CDN, in case another service is being used in front of Netlify’s CDN that also supports this feature.

Demo

We’ve created a demo repository where you can explore these patterns yourself and see them in action on Netlify Edge at this link.

Visit our documentation for more information on how to get started.

What’s next for edge caching on Netlify?

This ability to granularly invalidate cached dynamic content over Netlify Edge is just another step in our goal to provide a best-in-class caching experience, and we’re excited to share even more caching primitives improvements over the next few weeks.