@plenary/nuxt
@plenary/nuxt connects Plenary to the Nitro cache behind a Nuxt site. It gives you a server handler that receives Plenary webhooks and purges the cached responses of the pages an entry change affects, so swr and cache route rules and defineCachedEventHandler routes regenerate on the next request instead of waiting out their maxAge. It depends on @plenary/client, @nuxt/kit, and h3, and the module declares Nuxt 4 as its compatibility range. It does not depend on Vue.
npm install @plenary/client @plenary/nuxtThis page documents version 1.0.x.
Exports
Section titled “Exports”| Export | Import from | Kind |
|---|---|---|
| default | @plenary/nuxt |
The Nuxt module, for modules in nuxt.config.ts |
createRevalidateHandler |
@plenary/nuxt/server |
Server handler factory |
purgeCachedPaths |
@plenary/nuxt/server |
The cache purge, for custom handlers |
cacheKeyPathname |
@plenary/nuxt/server |
The key prefix Nitro files a path under |
planRevalidation |
@plenary/client |
The pure decision function, for custom handlers |
entryUrl |
@plenary/client |
Default URL builder |
RevalidateOptions, RevalidatePaths, RevalidationPlan, CacheStorage |
@plenary/nuxt/server |
Types |
The module
Section titled “The module”export default defineNuxtConfig({ modules: ["@plenary/nuxt"], runtimeConfig: { plenaryWebhookSecret: "", // set with NUXT_PLENARY_WEBHOOK_SECRET }, routeRules: { "/blog/**": { swr: 3600 }, },});The module has no options and mounts no routes. It registers the package’s server runtime with Nitro’s bundler, which is what lets the handler reach Nitro’s cache storage: nitropack/runtime, where useStorage comes from, exists only inside the Nitro bundle, so the runtime must be bundled rather than loaded from node_modules at request time. Without the module, every request to the handler answers 500, and the server log says Package import specifier "#nitro-internal-virtual/storage" is not defined in package …/nitropack/package.json.
createRevalidateHandler
Section titled “createRevalidateHandler”import { createRevalidateHandler } from "@plenary/nuxt/server";
function createRevalidateHandler(options: RevalidateOptions): EventHandler;Returns an h3 event handler for a server/ route. For each request it verifies the secret, parses the payload, works out which paths the event affects, and removes their cached responses.
import { createRevalidateHandler } from "@plenary/nuxt/server";
export default createRevalidateHandler({ secret: useRuntimeConfig().plenaryWebhookSecret, paths: { post: ({ entry }) => (entry.slug ? ["/blog", `/blog/${entry.slug}`] : ["/blog"]), },});The .post.ts suffix makes Nitro answer other methods with a 404 before the handler runs; the handler also refuses them itself, so a plain revalidate.ts works too.
Then add a webhook in the console that points at https://your-site.example.com/api/revalidate, subscribes to the entry events, and sends a header x-plenary-secret marked Secret with the same value as NUXT_PLENARY_WEBHOOK_SECRET.
RevalidateOptions
Section titled “RevalidateOptions”| Option | Type | Default | Description |
|---|---|---|---|
secret |
string |
Required | The shared secret configured on the webhook. |
secretHeader |
string |
"x-plenary-secret" |
Header the secret arrives in. |
secretQuery |
string |
"secret" |
Query parameter checked when the header is absent. |
paths |
Record<string, RevalidatePaths> |
None | Paths to purge per model key. A model listed here replaces the default URL entirely. |
entryUrl |
(payload: EntryWebhookPayload) => string | null | undefined |
entryUrl |
Builds the path for models not listed in paths. Return null to purge no path. |
events |
EntryWebhookEvent[] |
All five entry events | Events that trigger a purge. Others are answered but ignored. |
type RevalidatePaths = | string | string[] | ((payload: EntryWebhookPayload) => string | string[] | null | undefined);A path function receives the full entry webhook payload, so you can use entry.slug, entry.path, entry.locale, model.key, and changed. Duplicate paths are removed. Paths must be route paths on your site, such as /blog/hello-plenary; a query string on a path is ignored, because a purge removes every cached variant of the page anyway.
To keep the default URL and add more, call entryUrl yourself:
import { entryUrl } from "@plenary/client";import { createRevalidateHandler } from "@plenary/nuxt/server";
export default createRevalidateHandler({ secret: useRuntimeConfig().plenaryWebhookSecret, paths: { page: (payload) => [entryUrl(payload) ?? "/", "/sitemap.xml"], },});What the handler does with each request
Section titled “What the handler does with each request”| Request | Status | Response body | Cache effect |
|---|---|---|---|
Not POST |
405 |
{ "message": "Method not allowed" } |
None |
No secret configured (empty or unset) |
500 |
{ "message": "Webhook secret is not configured" } |
None |
| Secret missing or wrong | 401 |
{ "message": "Invalid webhook secret" } |
None |
| Body not JSON, or not a Plenary payload | 400 |
{ "message": "…" } |
None |
form.submitted, or an event not in events |
200 |
{ "revalidated": false, "ignored": "<event>" } |
None |
Event webhook.test |
200 |
{ "test": true, "paths": […] } |
None (dry run) |
| An entry event | 200 |
{ "revalidated": true, "paths": […], "purged": <n> } |
Every cached response of each path removed |
purged is the number of cache entries removed. It is 0 when nothing was cached for the paths, which is normal for a page nobody has visited since it was last purged. A 0 for a page you know is cached means the cache lives somewhere the handler cannot see; see What gets purged.
The 4xx answers make Plenary fail the delivery at once rather than retry it. Plenary retries 5xx responses and timeouts with backoff for about seven hours, and gives each attempt 10 seconds. Purging is idempotent, so a retried or duplicated delivery is harmless.
What gets purged
Section titled “What gets purged”Nitro has no cache tags. A cached response is stored in useStorage("cache") under a key derived from its request URL:
cache:nitro:routes:_:newshelloworld.a1B2c3D4e5.json ← /news/hello-world via a route rulecache:nitro:handlers:_:newshelloworld.f6G7h8I9j0.json ← /news/hello-world via defineCachedEventHandlerThe part before the dot is the URL path with every non-word character removed and cut to 16 characters (/ becomes index); the part after it is a hash of the full URL including the query string, so each query-string variant of a page is its own entry. The handler lists the nitro:routes and nitro:handlers groups and removes every entry whose path part matches one of the planned paths. It does not recompute the hash, which means:
- Every variant of the page goes.
/news/hello-world?utm=xand a response cached under avariesheader are purged together with the plain page. - Long paths over-purge.
/blog/2026/11/03/some-titleand/blog/2026/11/03/some-othershare the 16-character prefixblog20261103some, so purging one purges both. That is harmless: the next request regenerates the page.
Things the handler cannot reach:
| Cache | Why | What to do |
|---|---|---|
| Per-instance memory | Nitro’s default cache storage in production is in-memory, so on a platform that runs several instances the purge only hits the one that received the webhook. |
Mount a shared driver for cache in nitro.storage, such as Redis, Cloudflare KV, or Vercel KV, so every instance sees it. |
| Platform ISR | The isr route rule on Vercel and Netlify caches at the platform’s CDN, outside Nitro’s storage. |
Use swr with a shared cache driver, or purge through the platform’s API. |
defineCachedFunction |
Its keys are whatever getKey returns, so the nitro:functions group is left alone. |
Give those functions a maxAge you can live with, or purge them from a custom handler built on planRevalidation. |
Cached handlers with a custom getKey |
Same reason. | Same. |
purgeCachedPaths
Section titled “purgeCachedPaths”import { purgeCachedPaths, cacheKeyPathname } from "@plenary/nuxt/server";
function purgeCachedPaths(storage: CacheStorage, paths: string[]): Promise<number>;function cacheKeyPathname(path: string): string;
interface CacheStorage { getKeys(base?: string): Promise<string[]>; removeItem(key: string): Promise<void>;}The purge the handler performs, for use in your own routes: pass useStorage("cache") and the paths, and get back the number of entries removed. cacheKeyPathname gives the path part Nitro files a path under (/news/hello-world → newshelloworld, / → index), if you need to match keys yourself.
planRevalidation
Section titled “planRevalidation”import { planRevalidation } from "@plenary/client";
function planRevalidation(payload: WebhookPayload, options: RevalidateOptions): RevalidationPlan;
interface RevalidationPlan { relevant: boolean; // false for form payloads and events not in options.events test: boolean; // true for "webhook.test": report, do not purge paths: string[];}The decision the handler uses, with no framework calls. It lives in @plenary/client, which @plenary/next builds on too; @plenary/nuxt/server re-exports only its types. Use it to write a custom handler, for example one that also clears a defineCachedFunction by its own keys:
import { parseWebhookRequest, planRevalidation, PlenaryWebhookError } from "@plenary/client";import { purgeCachedPaths, type RevalidateOptions } from "@plenary/nuxt/server";
const options: RevalidateOptions = { secret: useRuntimeConfig().plenaryWebhookSecret };
export default defineEventHandler(async (event) => { let payload; try { payload = await parseWebhookRequest(toWebRequest(event), options); } catch (err) { if (err instanceof PlenaryWebhookError) { setResponseStatus(event, err.status); return { message: err.message }; } throw err; }
const plan = planRevalidation(payload, options); if (!plan.relevant) return { revalidated: false, ignored: payload.event }; if (plan.test) return { test: true, paths: plan.paths };
const cache = useStorage("cache"); const purged = await purgeCachedPaths(cache, plan.paths); // A cached function named "nav" with getKey: () => "menu" await cache.removeItem("nitro:functions:nav:menu.json"); return { revalidated: true, paths: plan.paths, purged };});entryUrl
Section titled “entryUrl”import { entryUrl } from "@plenary/client";
function entryUrl(payload: EntryWebhookPayload): string | null;The default path for an entry: its folder path joined with its slug. A root-folder entry slugged home is the home page, /.
entry.path |
entry.slug |
Result |
|---|---|---|
/ |
hello-plenary |
/hello-plenary |
/ |
home |
/ |
/blog |
spring-sale |
/blog/spring-sale |
| any | none (singleton) | null |
This matches your site’s URLs only if your routes mirror the folder tree with no prefix. A blog served at /blog/{slug} from a model with no folders needs a paths entry or a custom entryUrl. Locale is not part of the default path; add it in entryUrl if your routes include it.
Environment variables
Section titled “Environment variables”| Variable | Used for |
|---|---|
NUXT_PLENARY_WEBHOOK_SECRET |
Fills runtimeConfig.plenaryWebhookSecret, the value of the secret header configured on the webhook. Generate a long random string, for example with openssl rand -hex 32. |
NUXT_PLENARY_BASE_URL, NUXT_PLENARY_API_KEY, … |
The client configuration, if you keep it in runtimeConfig too. See SDK overview. |
The names are a convention; the package reads nothing from the environment or from runtimeConfig itself. Keep the private key and the secret out of runtimeConfig.public.
Related
Section titled “Related”- Webhooks: configuring webhooks in the console.
- Webhook events: events, payloads, and delivery behavior.
- @plenary/client: the webhook helpers and the path planner this package builds on.
- @plenary/next: the same integration for Next.js, where the cache has tags.