Skip to content

@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.

Terminal window
npm install @plenary/client @plenary/nuxt

This page documents version 1.0.x.

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
nuxt.config.ts
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.

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.

server/api/revalidate.post.ts
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.

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"],
},
});
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.

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 rule
cache:nitro:handlers:_:newshelloworld.f6G7h8I9j0.json ← /news/hello-world via defineCachedEventHandler

The 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=x and a response cached under a varies header are purged together with the plain page.
  • Long paths over-purge. /blog/2026/11/03/some-title and /blog/2026/11/03/some-other share the 16-character prefix blog20261103some, 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.
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.

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:

server/api/revalidate.post.ts
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 };
});
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.

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.

  • 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.