Quickstart

dotnet add package TheBuilder.CacheTags --prerelease

Start the site. The package creates its tables on the first start. From then on, every cacheable Delivery API response carries its keys in a header:

GET /umbraco/delivery/api/v2/content/item/articles/harbour-mornings/

X-Umbraco-Cache-Keys: umbraco, content-e0000000-0000-0000-0000-000000000003

Preview requests, signed-in requests and responses other than 200 get no keys.

Tag each cached response with the keys in its header. In Next.js with Cache Components:

import { cacheLife, cacheTag } from "next/cache";

export async function deliveryApi<T>(path: string): Promise<T | null> {
  "use cache";
  const url = `${process.env.UMBRACO_URL}/umbraco/delivery/api/v2/${path}`;
  const response = await fetch(url);
  if (!response.ok) {
    // An error carries no keys, so no purge would reach it. Keep it only briefly.
    cacheLife("seconds");
    return null;
  }
  cacheTag(...(response.headers.get("x-umbraco-cache-keys")?.split(", ") ?? []));
  cacheLife("days");
  return response.json();
}

The Next.js guide handles errors, cultures and an API key too.

Your frontend needs a route that receives purges and expires the keys in them. Copy the route handler from the Next.js guide. It checks the signature, then calls revalidateTag for each key.

In Umbraco, go to Settings > Advanced > Cache tags > Targets and select Add target. Enter the webhook’s URL and a signing secret, then select Send test purge to check it before you save.

A secret typed into the backoffice is stored in the database in plain text. Outside local development, set it as an environment variable such as CacheTags__Secrets__WebhookSecret, and have the target name WebhookSecret instead. See Purge targets.

You can configure the target in appsettings.json instead:

{
  "CacheTags": {
    "Targets": {
      "nextjs": {
        "Url": "https://www.example.com/api/cache-tags",
        "Secret": "<at least 32 random characters>"
      }
    }
  }
}

Keep the secret out of source control. Set it as the environment variable CacheTags__Targets__nextjs__Secret, or in your host’s secret store, and leave it out of the file.

Give the frontend the same secret, as CACHE_TAGS_WEBHOOK_SECRET, and use a different one for each environment. To generate one:

openssl rand -base64 32

Publish a page your frontend shows. Within a second or two, Settings > Advanced > Cache tags > Changes shows the change, the keys it planned and the purge it sent. The page, and every listing that shows it, renders the new content on its next request.

The page’s Info tab lists the cached responses that include it, and can purge it by hand. See Backoffice.