@canner-ca/nuxt-cache

One-line cache headers for Canner, for Nuxt. It sets Cache-Control and Surrogate-Key exactly the way Canner's cache proxy expects, so your pages cache on Canner and purge by tag from your CMS.

Install

npm install @canner-ca/nuxt-cache

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

Use it

Pages (<script setup>) — pass the request event. On the client it's undefined, so the call is a safe no-op:

<script setup>
import { cache } from '@canner-ca/nuxt-cache';

const route = useRoute();
const { data: post } = await useAsyncData(() => fetchPost(route.params.slug));

cache(useRequestEvent(), { ttl: 3600, tags: [post.value.id, 'blog-listing'] });
</script>

Server routes (server/api/**, server/routes/**):

import { cache } from '@canner-ca/nuxt-cache';

export default defineEventHandler((event) => {
  cache(event, { ttl: 3600, tags: ['blog-listing'] });
  return getPosts();
});

Server middleware (server/middleware/**) — set caching for matching paths:

import { cache } from '@canner-ca/nuxt-cache';

export default defineEventHandler((event) => {
  if (event.path.startsWith('/blog/')) {
    cache(event, { ttl: 3600, tags: ['blog-listing'] });
  }
});

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

Why it's safe with Nuxt

Nuxt mostly "just works": client navigation fetches payloads from separate URLs, so a page URL only ever returns its HTML document. The one same-URL exception is the SPA shell Nuxt returns when a request sends x-nuxt-no-ssr — Canner's proxy passes those requests straight through, so only the real server-rendered document is ever cached. You don't configure any of that.

API

cache(target, options)

target is an H3Event, a Node ServerResponse, a Response/Headers, or null/undefined (a no-op). Returns the same target.

applyCacheHeaders(headers, options)

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; duplicates and whitespace tags are dropped. | | browserTtl | number | Optional. Seconds the visitor's browser may cache (sets max-age). Omit to keep tag purges instant. |

What Canner caches

The same rules this helper produces:

• method GET/HEAD, status 200, no x-nuxt-no-ssr request header
• 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. It does not remove Set-Cookie: Canner already declines to cache a response that sets a cookie, so you get a development-only warning instead — your cookie is left untouched. A bad ttl sets no headers and warns; a null target is a no-op (the client render pass); only passing something that isn't a supported target 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.

Also available: @canner-ca/astro-cache and @canner-ca/next-cache.

License

MIT