Skip to content
Cache Tags
Esc
↑↓navigate↵open⌘Jpreview

Cache every response, purge only what changed.

Every Delivery API response tells your frontend which keys it covers. When an editor publishes, Umbraco purges exactly those keys, once every server has the change.

Get startedView on GitHub
dotnet add package TheBuilder.CacheTags --prerelease

Umbraco CMS 17.4 or later · .NET 10

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

X-Umbraco-Cache-Keys: response-2de23a3a68340e675d917313029cab2e, umbraco
{
  "version": 1,
  "expire": [
    "content-e0000000-0000-0000-0000-000000000003",
    "response-2de23a3a68340e675d917313029cab2e",
    "response-bedaf32c19e04d2a8b1e5c7a0f3d9e61"
  ],
  "stale": ["children-e0000000-0000-0000-0000-000000000002"]
}

Your frontend caches for days, and is never wrong for long. Umbraco keeps track of which responses showed which content, and tells the frontend the moment any of them changes.

Built for headless Umbraco

For Next.js and other frontends that cache Delivery API responses, on one Umbraco server or many.

Purges exactly what changed

Publishing an article purges its page, the listings it appears in, and the pages that pick it. Every other cached response stays.

Never refetches the old version

A purge goes out once every Umbraco server serves the change, and listings once every server's index has it, so a frontend that refetches at once gets the new content.

Works with your cache

Tag entries with Next.js cacheTag, let Cloudflare purge by tag, or receive a signed webhook in anything else.

How a publish reaches your cache

The package records each change, waits until every server serves it, and sends the keys to every purge target.

How a purge is timed
TagEvery cacheable response carries its keys in a header. Your frontend tags its cache entry with them.
WaitA change is purged once every server has applied it, and its listings once every server's index has it.
PurgeA signed webhook to your frontend, Cloudflare's purge API, or a target of your own.

Two lines in your fetch

Tag each cached response with its keys, and add a webhook route that expires them. The Next.js guide has both, ready to copy.

Read the Next.js guide
const response = await fetch(url);
cacheTag(...response.headers.get("x-umbraco-cache-keys").split(", "));

Purge your first page

Install the package, point it at your frontend, and publish.

Read the quickstart

More from TheBuilder

Focused packages for modern Umbraco projects.