DatoCMS Cache Tags

The DatoCMS Content Delivery API offers a feature called cache tags. It lets you cache your website pages for as long as you like — serving traffic from a CDN instead of querying us on every request, which cuts your hosting bill and your DatoCMS API usage alike — without the usual headache of working out what to invalidate, and when.

Astro is a particularly good place to use it, because since Astro 7 tagged caching is a first-class primitive of the framework rather than something you bolt on. Astro.cache.set({ tags }) records tags for the response being rendered, cache.invalidate({ tags }) purges them, and your adapter's cache provider translates both into whatever your host actually speaks — Cache-Tag on Cloudflare, Netlify-Cache-Tag on Netlify.

So the integration is short: ask the Content Delivery API for the tags behind each query, hand them to Astro.cache, and hand the webhook's tags to cache.invalidate(). Roughly forty lines, most of which you write once in a shared executeQuery wrapper and then never think about again.

What you'll need

• Astro 7 or later, with output: 'server'. Cache tags only make sense for server-rendered pages: a statically prerendered page has no response for the CDN to tag.

• An adapter that ships a cache provider — Cloudflare, Netlify and Vercel all do. The examples below use Cloudflare; the last section covers what changes on the other two.

• A DatoCMS project on a plan that exposes cache tags, and a read-only CDA token.

Step 1: Enable the cache provider

Point Astro's cache.provider at your adapter's provider:

1
import cloudflare from '@astrojs/cloudflare';
2
import { cacheCloudflare } from '@astrojs/cloudflare/cache';
3
import { defineConfig } from 'astro/config';
4

5
export default defineConfig({
6
  output: 'server',
7
  adapter: cloudflare(),
8
  cache: {
9
    provider: cacheCloudflare(),
10
  },
11
});

On Cloudflare there's a second switch, and it's the one people miss: the Workers cache has to be turned on in wrangler.jsonc too (with Wrangler 4.69.0 or later). Without it, everything below runs without error and simply never caches anything.

{
  "name": "my-site",
  "main": "@astrojs/cloudflare/entrypoints/server",
  "compatibility_date": "2026-08-08",
  "cache": {
    "enabled": true,
  },
}

Step 2: Ask DatoCMS for cache tags, and register them

Cache tags are returned in the x-cache-tags response header, but only if you ask for them. With @datocms/cda-client that's the returnCacheTags option — and since you need the header and not just the parsed body, you want rawExecuteQuery, which returns both.

Everything then funnels into a single executeQuery wrapper that every page and component uses:

1
import { rawExecuteQuery } from '@datocms/cda-client';
2
import { DATOCMS_CDA_TOKEN } from 'astro:env/server';
3

4
const ONE_YEAR = 60 * 60 * 24 * 365;
5

6
export async function executeQuery(context, query, variables) {
7
  const [result, response] = await rawExecuteQuery(query, {
8
    token: DATOCMS_CDA_TOKEN,
9
    returnCacheTags: true,
10
    variables,
11
  });
12

13
  const rawTags = response.headers.get('x-cache-tags');
14
  const cacheTags = rawTags ? rawTags.split(' ') : [];
15

16
  if (cacheTags.length > 0) {
17
    context.cache.set({ maxAge: ONE_YEAR, tags: cacheTags });
18
  }
19

20
  return result;
21
}

Three details worth pausing on:

• The header is space-separated. DatoCMS uses spaces (the Fastly Surrogate-Key convention); Cloudflare's Cache-Tag uses commas. You split on spaces, hand Astro an array, and the provider re-joins with commas for you.

• Tags accumulate across the whole request. Astro.cache keeps a Set internally, so calling cache.set() once per query is exactly right: a page that runs a layout query, a header query and a page query ends up with the union of all three tag sets, deduplicated. You never have to collect tags yourself.

• maxAge is a year on purpose. The cached response isn't meant to expire on a timer — it's meant to live until the content behind it changes, at which point step 4 purges it explicitly. A TTL here would only mean serving stale content for up to that TTL, and re-fetching content that hasn't changed. If you'd rather have a safety net, a swr window is a better tool than a short maxAge.

Using it from a page looks like any other data fetch, except you pass Astro through:

1
---
2
import { executeQuery } from '~/lib/datocms/executeQuery';
3
import { BLOG_POST_QUERY } from './_graphql';
4

5
const data = await executeQuery(Astro, BLOG_POST_QUERY, {
6
  slug: Astro.params.slug,
7
});
8
---
9

10
<h1>{data.blogPost.title}</h1>

Step 3: Make sure component-level tags aren't missed

This is the one non-obvious part of the integration, and it's worth understanding rather than just copying.

Astro streams HTML by default. The response object resolves as soon as the page starts rendering, and Astro applies the cache headers at that moment — but queries living inside a Layout, a <Header /> or a <Footer /> haven't run yet. Their tags get registered after the Cache-Tag header has already been serialized, so they're silently dropped. The symptom is nasty precisely because it's partial: the page caches, tag-based purging works for the page's own query, and updating a record that only appears in the footer never purges anything.

The fix is to buffer the HTML in middleware, which forces the full render — and therefore every query — to complete before the headers are applied:

1
import { defineMiddleware } from 'astro:middleware';
2

3
export const onRequest = defineMiddleware(async (context, next) => {
4
  let response = await next();
5

6
  const contentType = response.headers.get('content-type') || '';
7

8
  if (contentType.includes('text/html')) {
9
    // Astro applies the cache headers as soon as this middleware returns, but
10
    // with streaming the response resolves before the body is rendered — so any
11
    // executeQuery() inside Layout/Header/Footer would register its cache tags
12
    // too late. Buffering the body here forces the whole page to render (and
13
    // every query to run) before the tags are serialized.
14
    response = new Response(await response.arrayBuffer(), response);
15
  }
16

17
  return response;
18
});

You're giving up streaming for HTML responses. On a page that's about to be cached at the edge for a year, that's a very cheap trade: the buffering cost is paid once per cache miss, and every subsequent visitor is served by the CDN anyway.

Step 4: Purge on content change

DatoCMS emits an invalidation webhook listing exactly which tags are now stale. Your endpoint's whole job is to hand those tags to cache.invalidate():

1
import { CACHE_INVALIDATION_WEBHOOK_SECRET } from 'astro:env/server';
2

3
// The webhook delivers a payload shaped like this:
4
//
5
//   {
6
//     entity_type: 'cda_cache_tags',
7
//     event_type: 'invalidate',
8
//     entity: {
9
//       id: 'cda_cache_tags',
10
//       type: 'cda_cache_tags',
11
//       attributes: { tags: ['8f2a1c', '3b91e7', ...] },
12
//     },
13
//   }
14

15
export const POST = async ({ request, cache }) => {
16
  if (
17
    request.headers.get('Authorization') !==
18
    `Bearer ${CACHE_INVALIDATION_WEBHOOK_SECRET}`
19
  ) {
20
    return Response.json({ error: 'Unauthorized' }, { status: 401 });
21
  }
22

23
  const body = await request.json();
24
  const tags = body.entity.attributes.tags;
25

26
  if (!tags.length) {
27
    return Response.json({ error: 'Missing tags' }, { status: 400 });
28
  }
29

30
  await cache.invalidate({ tags });
31

32
  return Response.json({ success: true, invalidated: tags.length });
33
};

Then, in your DatoCMS project, go to Settings > Webhooks, create a webhook pointing at https://your-site.com/api/invalidate-cache, add an Authorization: Bearer <your-secret> header, and subscribe it to the Cache tags invalidation event.

That's the entire loop. A record is published, DatoCMS computes which tags are affected, your endpoint purges them, and the next visitor to any page that touched that record gets a fresh render.

Verifying it works

Cloudflare reports the cache outcome in Cf-Cache-Status:

curl -sI https://your-site.com/blog/hello-world | grep -i cf-cache-status
# cf-cache-status: MISS   ← first request
# cf-cache-status: HIT    ← second request, served without reaching your Worker

Now edit that record in DatoCMS and publish it. The next request should be a MISS again, with the new content — that transition is the whole integration working.

When it isn't:

• No Cf-Cache-Status at all — Workers Cache isn't active: cache.enabled is missing from wrangler.jsonc, or Wrangler is older than 4.69.0.

• A HIT that survives publishing — look at the webhook, not the caching. DatoCMS logs every delivery along with the response your endpoint returned, which separates "never fired" from "returned a 401".

Don't go looking for the tags themselves: Cloudflare strips Cache-Tag before the response leaves the edge. To see what your app registered, echo Astro.cache.tags from the middleware, after the buffering step:

// src/middleware.js — temporary, for debugging only
response.headers.set('X-Debug-Cache-Tags', context.cache.tags.join(','));

Things to keep in mind

Draft mode must not be cached. If you've set up draft mode, draft responses are per-editor and must never reach a shared cache. The simplest guard is to skip tag registration entirely when drafts are on:

if (!includeDrafts && cacheTags.length > 0) {
  context.cache.set({ maxAge: ONE_YEAR, tags: cacheTags });
}

Astro also gives you Astro.cache.set(false), which disables caching for the current response outright — useful as a belt-and-braces measure in a middleware that already knows whether draft mode is active. Either way, pair it with an explicit Cache-Control: private, no-store on draft responses.

Deploys don't invalidate anything. Cache tags track content changes, not code changes. Ship a template tweak and the CDN will happily keep serving the old HTML for a year. Add a full purge to your deploy pipeline — on Cloudflare, an authenticated route is the easiest way:

import { cache } from 'cloudflare:workers';

await cache.purge({ purgeEverything: true });

Mind the tag budget. A Content Delivery API response can carry up to 500 cache tags, and every query on a page contributes to the same set. Cloudflare has room to spare; other hosts don't (see below). A page that genuinely needs hundreds of tags is usually a page worth rethinking anyway — paginate the listing, or narrow the query.

Deploying on Netlify or Vercel

The code doesn't change. Swap the adapter and its provider in astro.config.mjs and everything else — executeQuery, the middleware buffering, the webhook endpoint — stays exactly as written:

1
// Netlify
2
import netlify from '@astrojs/netlify';
3
import { cacheNetlify } from '@astrojs/netlify/cache';
4
export default defineConfig({
5
  output: 'server',
6
  adapter: netlify(),
7
  cache: { provider: cacheNetlify() },
8
});
9

10
// Vercel
11
import vercel from '@astrojs/vercel';
12
import { cacheVercel } from '@astrojs/vercel/cache';
13
export default defineConfig({
14
  output: 'server',
15
  adapter: vercel(),
16
  cache: { provider: cacheVercel() },
17
});

What differs is underneath, and one difference is worth knowing before you commit:

• Cloudflare — tags go out as Cache-Tag, purging goes through the Workers cache.purge() API. The header holds 16 KB, roughly 1,000 tags.

• Netlify — tags go out as Netlify-Cache-Tag, purging through purgeCache() from @netlify/functions. The cap is 500 tags per response, exactly matching ours.

• Vercel — tags go out as Vercel-Cache-Tag, purging through invalidateByTag() from @vercel/functions. The cap is 128 tags per response.

Cloudflare and Netlify comfortably fit everything DatoCMS can return. Vercel caps a cached response at 128 tags, well below our 500, so a page whose queries collectively touch more than 128 records will overflow the budget. Most detail pages are nowhere near that ceiling; large listing pages can cross it without anyone noticing. Vercel doesn't document what happens to the excess, so if you're on Vercel with tag-heavy pages, verify the behaviour before relying on it.

Vercel's purge path is also chattier: the provider issues one invalidateByTag() call per tag, so a webhook delivery carrying a few hundred tags becomes a few hundred concurrent API calls inside one function invocation. If you're on Vercel and publishing in bulk, chunk the tags in your webhook handler rather than passing the whole array through at once.