@canner-ca/astro-cache

One-line cache headers for Canner. It sets Cache-Control and Surrogate-Key exactly the way Canner's cache proxy expects, so your server-rendered pages cache on Canner and purge by tag from your CMS — without you memorizing header names or formats.

Works with any framework (it only touches the Web Headers API), but it's built for Astro + a headless CMS like DatoCMS.

Install

npm install @canner-ca/astro-cache

Requires Node.js 20 or later. Zero runtime dependencies.

Use it

---
// src/pages/blog/[slug].astro
import { cache } from '@canner-ca/astro-cache';

const post = await getPost(Astro.params.slug);

// Cache this response on Canner for an hour, tagged so a publish can clear it.
cache(Astro.response, { ttl: 3600, tags: [post.id, 'blog-listing'] });
---

That sets:

Cache-Control: public, s-maxage=3600
Surrogate-Key: <post.id> blog-listing

When the post changes, your DatoCMS webhook purges tag <post.id> (Canner reads the changed record automatically) and Canner clears every page carrying it. Add blog-listing to your listing page and to the purge to clear the index too.

Full integration guide (the webhook setup, the dashboard token): https://canner.ca/docs/caching

API

cache(target, options)

target is a Response, Astro.response, or a Headers. Returns the Headers.

applyCacheHeaders(headers, options)

Same thing, lower-level, when you already hold a Headers instance.

options

| Option | Type | Notes | |---|---|---| | ttl | number (required) | Seconds Canner may serve the cached response. Sets s-maxage. Positive integer. | | tags | string \| number \| Array<string \| number> | Tags for purging. Sets Surrogate-Key. Numbers are coerced to strings; duplicates and whitespace-containing tags are dropped. | | browserTtl | number | Optional. Seconds the visitor's browser may cache (sets max-age). Omit to let the browser revalidate while Canner serves from cache — keeps purges instant. |

What it caches (and what it won't)

A response is cached by Canner only when all of these hold — the same rules this helper produces:

• method GET/HEAD, status 200
• Cache-Control: public with a positive s-maxage (or max-age)
• no Set-Cookie
• Vary absent or only Accept-Encoding
• body under 8 MB

It only ever adds headers

This package never strips or mutates anything your app set. In particular it does not remove Set-Cookie: Canner already declines to cache a response that sets a cookie, so the only safe thing to do is tell you. If you call cache() on a response that sets a cookie, you'll get a development-only warning explaining it won't be cached — your cookie is left untouched.

Invalid input degrades gracefully too: a bad ttl sets no cache headers (the page still renders, just uncached) and warns in dev. Only passing something that isn't a Response/Headers throws.

Non-goals

• It doesn't configure your CMS webhook — that's two copy-paste values in the Canner dashboard (Settings → Caching).
• It doesn't implement stale-while-revalidate; after a purge the next request re-renders once and re-caches.

License

MIT