@towa-digital/storyblok-nuxt-cv 0.1.2

package/README.md

@@ -0,0 +1,176 @@
+# @towa-digital/storyblok-nuxt-cv
+
+Keeps **published Storyblok content fresh on long-running Nuxt servers** — no
+redeploy after publish. Packages the `aichelin-multisite` 1.5.5 storage-bridge
+fix as a drop-in Nuxt module.
+
+Maintained by [TOWA](https://www.towa.digital). Design rationale and the full
+bug analysis live in TOWA's internal `storyblok-cv-audit` playbook repo
+(`docs/package-design.md`, `docs/problem.md`).
+
+## The problem (short version)
+
+`storyblok-js-client` pins the space cache version (`cv`) in a process-global
+map for the process lifetime, and Storyblok's CDN serves a **frozen snapshot**
+for every URL warmed under that `cv` (7-day s-maxage). On client **v6** nothing
+ever heals the pin — published content stays stale **until redeploy**; on **v5
+and v7** the pin self-heals on the first cache-missing response, which presents
+as unpredictable per-worker **flapping** after every publish. In production
+builds the render client is a **separate bundled copy** of the client that
+Nitro code can't reach, so a plain server-side `flushCache()` webhook does not
+fix the render path.
+
+## What this module does
+
+- **Nitro middleware** attaches the stored live `cv` to every page render's
+  `event.context`; an **app plugin** (compiled into the same bundle as the
+  render client) pins it via `useStoryblokApi().setCacheVersion(cv)` before
+  content is fetched, and forwards it to the browser through the payload.
+- The stored `cv` is kept fresh by three composable strategies:
+  - **startup init** (on by default) — populates the store at boot,
+  - **publish webhook** (built-in route, or one line in your existing handler),
+  - **TTL stale-while-revalidate** — for serverless/edge and multi-instance.
+- Works with `storyblok-js-client` **v5 → v7** and `@storyblok/nuxt` **5 → 9**:
+  the server side never imports the client (raw `cdn/spaces/me` fetch), the app
+  side only uses `useStoryblokApi`/`setCacheVersion`, which are stable across
+  all those majors. Keeps Storyblok's `cv`-keyed CDN caching intact (unlike
+  `cache: { cv: 'manual' }`).
+
+## Install
+
+Requires `@storyblok/nuxt` (any major from 5 to 9) in the host app.
+
+```bash
+yarn add @towa-digital/storyblok-nuxt-cv
+```
+
+```ts
+// nuxt.config.ts
+export default defineNuxtConfig({
+  modules: [
+    ['@storyblok/nuxt', { accessToken: process.env.STORYBLOK_TOKEN }],
+    '@towa-digital/storyblok-nuxt-cv',
+  ],
+})
+```
+
+That's it for a **single-process Node server** (DigitalOcean preset etc.):
+token is auto-detected from the `@storyblok/nuxt` config, startup init and the
+built-in webhook route are on by default.
+
+Then create a **story publish webhook** in Storyblok
+(Settings → Webhooks, story events) pointing at
+`https://<site>/api/storyblokCvWebhook`, set a secret, and provide it as
+`NUXT_STORYBLOK_CV_WEBHOOK_SECRET`.
+
+## Configuration
+
+```ts
+export default defineNuxtConfig({
+  storyblokCv: {
+    token: undefined,          // default: auto-detected from @storyblok/nuxt config; env NUXT_STORYBLOK_CV_TOKEN
+    region: 'eu',              // eu | us | ap | ca | cn — or apiHost: 'https://...'
+    storage: 'storyblok-cv',   // nitro storage mount name
+    endpoint: '/api/storyblokCv',        // GET current cv; false to disable
+    webhook: true,             // built-in route /api/storyblokCvWebhook; string = custom route; false = use refreshStoryblokCv() yourself
+    ttl: false,                // e.g. 60_000 — background refresh when the stored cv is older (serverless/multi-instance)
+    onStartup: true,           // populate the store once at boot
+  },
+})
+```
+
+## Deployment-target matrix (pick your refresh strategy)
+
+| Target | Storage | Strategy |
+|---|---|---|
+| Single Node process (DO app platform, plain node-server) | default (memory) | webhook (default setup) |
+| PM2 **cluster** on one host (`instances: 'max'`) | mount `fs` driver (shared disk) | webhook |
+| Multi-node / containers | mount Redis | webhook |
+| Cloudflare / Vercel Edge / Netlify (isolates) | default | **`ttl` (e.g. 60_000)** — a webhook can't reach every isolate |
+
+```ts
+// PM2 cluster example — the memory default is per worker, the webhook would
+// only update the one worker that received it:
+nitro: {
+  storage: { 'storyblok-cv': { driver: 'fs', base: './.data/storyblok-cv' } },
+},
+```
+
+If unsure, setting `ttl` **in addition to** the webhook is a safe belt-and-braces
+default: staleness is then bounded by the TTL even if webhook delivery breaks.
+
+## Integrating with an existing webhook
+
+Most TOWA projects already have a publish webhook (`update-redirects.post.ts`
+and friends). Set `webhook: false` and add one line — `refreshStoryblokCv` is
+auto-imported in server code:
+
+```ts
+// server/api/update-redirects.post.ts (existing handler, after signature check)
+await refreshStoryblokCv()
+```
+
+## Multi-tenant spaces: refresh on every publish (do not tenant-filter)
+
+Refreshing on **every content publish in the space** is the right behavior even
+for multi-tenant shared spaces where only one tenant's content changed — so the
+default needs no configuration. Filtering out sibling tenants' publishes (as
+aichelin 1.5.5 originally did) looks like it protects your CDN cache, but it
+only protects URLs that were already warm: cold fetches get 301-corrected to
+the latest `cv` and fill the cache under the new generation anyway, while your
+pinned client keeps paying that miss+301 hop on every fetch of them until your
+own next publish. It also serves stale resolved content if tenants share any
+references or datasources. Adopting the sibling's `cv` instead costs one origin
+fetch per URL identity, once.
+
+For genuinely special cases (e.g. origin rate-limit pressure from extremely
+frequent sibling publishes), the `storyblok-cv:webhook` nitro hook can veto a
+refresh: handlers receive `{ payload, refresh }` and may set `refresh = false`.
+Prefer throttling over hard filtering if you reach for this.
+
+## What this module does NOT solve
+
+- **ISR / page-cache staleness**: a fresh `cv` doesn't invalidate HTML already
+  cached by `routeRules: { isr: true }` or a CDN page cache in front of the app.
+- **URL-shape hygiene**: inconsistent trailing slashes in `cdn/stories/...`
+  paths create a second cache identity per story (flaky staleness). Normalize
+  in the app; see the audit playbook's `docs/remediation.md`.
+- On **client ≥ 7.4.0** (check the lockfile — the option doesn't exist before
+  7.4.0) you can alternatively set `cache: { cv: 'manual' }` and skip this
+  module — at the cost of losing Storyblok's `cv`-keyed CDN caching (every SSR
+  fetch hits origin). This module keeps CDN caching, and covers v5/v6/early-v7
+  where no such option exists.
+
+## Verifying an installation
+
+Don't trust a single "looks fresh" check. Use the lab method from the audit
+playbook (`docs/detection.md` Step 7): instrumented production build, publish
+via **form mode** (not the visual editor), sample repeatedly, test the warmed
+URL shape. Quick sanity check in production: `GET /api/storyblokCv` before and
+after a publish — the value must change without a restart.
+
+## Development
+
+```bash
+npm install
+npm run dev:prepare   # stub build + playground types
+npm run dev           # playground on localhost:3000
+npm run lint          # eslint (@nuxt/eslint-config, tooling + stylistic)
+npm run test          # vitest e2e against a fixture app + mocked Storyblok API
+npm run test:types    # vue-tsc, server and app contexts separately
+npm run prepack       # build dist/
+npm run release       # local: lint + test + build + changelogen + npm publish
+```
+
+## Releasing
+
+CI and releases run on **Buddy** and are **managed in Buddy** (GUI/API), not
+from a committed file — same as `@towa-digital/storyblok-nuxt-sitemap`. Two
+pipelines: *Test* (runs on branch pushes) and *Release to npm* (triggered by
+pushing a **tag** = version, publishes to public npm via
+`npm version $BUDDY_RUN_TAG`).
+
+Release flow: `npx changelogen --release --push` bumps the version + changelog
+and pushes a tag; the tag push triggers the pipeline. Publish auth comes from a
+Buddy **FILE variable** named `npmrc` (npm auth config) on the project or
+workspace — `$npmrc` resolves to its path, copied to `.npmrc` before publish.

package/dist/module.d.mts

@@ -0,0 +1,59 @@
+import * as _nuxt_schema from '@nuxt/schema';
+
+interface ModuleOptions {
+    /** Disable the module entirely (no handlers, no plugin). */
+    enabled?: boolean;
+    /** Verbose logging during setup. */
+    debug?: boolean;
+    /**
+     * Storyblok access token used to read the live `cv` from `cdn/spaces/me`.
+     * Defaults to the token found in the host's `@storyblok/nuxt` config.
+     * Overridable at runtime via `NUXT_STORYBLOK_CV_TOKEN`.
+     */
+    token?: string;
+    /** Storyblok API region. Ignored when `apiHost` is set. */
+    region?: 'eu' | 'us' | 'ap' | 'ca' | 'cn';
+    /** Full API host override, e.g. for proxies. */
+    apiHost?: string;
+    /**
+     * Nitro storage mount the `cv` is stored under. The default (unmounted) is
+     * per-process memory — fine for a single Node process. For PM2 cluster mount
+     * an `fs` driver, for multi-node mount Redis, in the host's `nitro.storage`.
+     */
+    storage?: string;
+    /** GET endpoint exposing the current `cv` (client re-pins, debugging). `false` disables. */
+    endpoint?: string | false;
+    /**
+     * Built-in Storyblok publish webhook. `true` registers it at
+     * `/api/storyblokCvWebhook`, a string sets the route, `false` disables it —
+     * then call the auto-imported `refreshStoryblokCv()` from your own webhook
+     * handler instead. Requires `NUXT_STORYBLOK_CV_WEBHOOK_SECRET`.
+     */
+    webhook?: boolean | string;
+    /**
+     * Max age (ms) of the stored `cv` before a page render triggers a background
+     * refresh. Required on serverless/edge targets (Cloudflare, Vercel, Netlify)
+     * and multi-instance setups without shared storage, where a webhook cannot
+     * reach every isolate. `false` disables (webhook/startup only).
+     */
+    ttl?: number | false;
+    /** Populate the `cv` store once at boot (fire-and-forget). */
+    onStartup?: boolean;
+}
+declare const _default: _nuxt_schema.NuxtModule<ModuleOptions, ModuleOptions, false>;
+
+declare module '@nuxt/schema' {
+    interface RuntimeConfig {
+        storyblokCv: {
+            token: string;
+            apiHost: string;
+            storage: string;
+            ttl: number;
+            onStartup: boolean;
+            webhookSecret: string;
+        };
+    }
+}
+
+export { _default as default };
+export type { ModuleOptions };

package/dist/module.json

@@ -0,0 +1,12 @@
+{
+  "name": "@towa-digital/storyblok-nuxt-cv",
+  "configKey": "storyblokCv",
+  "compatibility": {
+    "nuxt": ">=3.10.0"
+  },
+  "version": "0.1.2",
+  "builder": {
+    "@nuxt/module-builder": "1.0.2",
+    "unbuild": "3.6.1"
+  }
+}

package/dist/module.mjs

@@ -0,0 +1,121 @@
+import { defineNuxtModule, createResolver, useLogger, addServerHandler, addServerPlugin, addServerImports, addPlugin, addTypeTemplate } from '@nuxt/kit';
+import { defu } from 'defu';
+
+const API_HOSTS = {
+  eu: "https://api.storyblok.com",
+  us: "https://api-us.storyblok.com",
+  ap: "https://api-ap.storyblok.com",
+  ca: "https://api-ca.storyblok.com",
+  cn: "https://api.storyblokchina.cn"
+};
+const module$1 = defineNuxtModule({
+  meta: {
+    name: "@towa-digital/storyblok-nuxt-cv",
+    configKey: "storyblokCv",
+    compatibility: { nuxt: ">=3.10.0" }
+  },
+  defaults: {
+    enabled: true,
+    debug: false,
+    region: "eu",
+    storage: "storyblok-cv",
+    endpoint: "/api/storyblokCv",
+    webhook: true,
+    ttl: false,
+    onStartup: true
+  },
+  setup(options, nuxt) {
+    const resolver = createResolver(import.meta.url);
+    const logger = useLogger("storyblok-cv");
+    logger.level = options.debug || nuxt.options.debug ? 4 : 3;
+    if (options.enabled === false) {
+      logger.debug("The module is disabled, skipping setup.");
+      return;
+    }
+    const token = options.token || findStoryblokToken(nuxt);
+    if (!token) {
+      logger.warn(
+        "No Storyblok access token found. Set `storyblokCv.token`, configure `@storyblok/nuxt`, or provide NUXT_STORYBLOK_CV_TOKEN \u2014 the cv bridge is inert without it."
+      );
+    }
+    nuxt.options.runtimeConfig.storyblokCv = defu(
+      nuxt.options.runtimeConfig.storyblokCv,
+      {
+        token: token ?? "",
+        apiHost: options.apiHost || API_HOSTS[options.region] || API_HOSTS.eu,
+        storage: options.storage,
+        ttl: options.ttl === false ? 0 : options.ttl ?? 0,
+        onStartup: options.onStartup !== false,
+        webhookSecret: ""
+      }
+    );
+    addServerHandler({
+      middleware: true,
+      handler: resolver.resolve("./runtime/server/middleware/cv")
+    });
+    if (options.endpoint) {
+      addServerHandler({
+        route: options.endpoint,
+        method: "get",
+        handler: resolver.resolve("./runtime/server/api/cv.get")
+      });
+    }
+    if (options.webhook) {
+      addServerHandler({
+        route: typeof options.webhook === "string" ? options.webhook : "/api/storyblokCvWebhook",
+        method: "post",
+        handler: resolver.resolve("./runtime/server/api/webhook.post")
+      });
+    }
+    addServerPlugin(resolver.resolve("./runtime/server/plugins/init"));
+    const utils = resolver.resolve("./runtime/server/utils/cv");
+    addServerImports([
+      { name: "refreshStoryblokCv", from: utils },
+      { name: "readStoryblokCv", from: utils },
+      { name: "getLiveStoryblokCv", from: utils }
+    ]);
+    const hasStoryblokNuxt = nuxt.options.modules.some(
+      (m) => typeof m === "string" && m.includes("@storyblok/nuxt") || Array.isArray(m) && typeof m[0] === "string" && m[0].includes("@storyblok/nuxt")
+    );
+    if (!hasStoryblokNuxt) {
+      logger.warn(
+        "`@storyblok/nuxt` not found in the host modules \u2014 this module requires it (the render-client pin uses `useStoryblokApi`). Expect the build to fail until it is added."
+      );
+    }
+    addPlugin(resolver.resolve("./runtime/plugin"));
+    addTypeTemplate({
+      filename: "module/storyblok-nuxt-cv.d.ts",
+      getContents: () => `// Generated by @towa-digital/storyblok-nuxt-cv
+declare module 'nitropack' {
+  interface NitroRuntimeHooks {
+    'storyblok-cv:webhook': (context: {
+      payload: Record<string, unknown>
+      /** Set to false to skip the cv refresh for this webhook delivery. */
+      refresh: boolean
+    }) => void | Promise<void>
+  }
+}
+declare module 'h3' {
+  interface H3EventContext {
+    /** Current Storyblok cv, attached by the storyblok-nuxt-cv middleware. */
+    storyblokCv?: number
+  }
+}
+export {}
+`
+    }, { nitro: true, nuxt: true });
+  }
+});
+function findStoryblokToken(nuxt) {
+  const topLevel = nuxt.options.storyblok?.accessToken;
+  if (topLevel) return topLevel;
+  for (const entry of nuxt.options.modules ?? []) {
+    if (Array.isArray(entry) && typeof entry[0] === "string" && entry[0].includes("@storyblok/nuxt") && entry[1] && typeof entry[1] === "object") {
+      const inline = entry[1].accessToken;
+      if (inline) return inline;
+    }
+  }
+  return void 0;
+}
+
+export { module$1 as default };

package/dist/runtime/plugin.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Pin the current Storyblok `cv` on the render client before any content is
+ * fetched. This plugin compiles into the same Vue bundle as the render client,
+ * so `setCacheVersion()` here reaches the bundled client copy that Nitro-side
+ * code can't (the two-copies trap).
+ *
+ * Server: the `cv` comes from `event.context` (set by the Nitro middleware from
+ * shared storage) and is forwarded to the browser via the payload (`useState`),
+ * so client-side navigation stays cache-consistent.
+ */
+declare const _default: import("#app").Plugin<Record<string, unknown>> & import("#app").ObjectPlugin<Record<string, unknown>>;
+export default _default;

package/dist/runtime/plugin.js

@@ -0,0 +1,14 @@
+import { defineNuxtPlugin, useRequestEvent, useState, useStoryblokApi } from "#imports";
+export default defineNuxtPlugin((nuxtApp) => {
+  const cv = useState("storyblok-cv", () => 0);
+  if (import.meta.server) {
+    const fromContext = useRequestEvent()?.context.storyblokCv;
+    if (typeof fromContext === "number" && fromContext > 0) {
+      cv.value = fromContext;
+    }
+  }
+  nuxtApp.hook("app:created", () => {
+    if (!cv.value) return;
+    useStoryblokApi()?.setCacheVersion?.(cv.value);
+  });
+});

package/dist/runtime/server/api/cv.get.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Current `cv` from shared storage — for client-side re-pins in long-lived
+ * sessions and for checking what production currently believes.
+ */
+declare const _default: any;
+export default _default;

package/dist/runtime/server/api/cv.get.js

@@ -0,0 +1,6 @@
+import { defineEventHandler } from "#imports";
+import { readStoryblokCv } from "../utils/cv.js";
+export default defineEventHandler(async () => {
+  const record = await readStoryblokCv();
+  return { cv: record?.cv ?? 0, fetchedAt: record?.fetchedAt ?? 0 };
+});

package/dist/runtime/server/api/webhook.post.d.ts

@@ -0,0 +1,17 @@
+export interface StoryblokCvWebhookContext {
+    payload: Record<string, unknown>;
+    /** Set to `false` in a `storyblok-cv:webhook` nitro hook to skip the refresh. */
+    refresh: boolean;
+}
+/**
+ * Built-in Storyblok publish webhook: verify the HMAC-SHA1 signature, give the
+ * host a veto via the `storyblok-cv:webhook` nitro hook, then refresh the
+ * stored `cv`. Refreshing on every content publish in the space is the right
+ * default even for multi-tenant shared spaces — filtering out sibling tenants
+ * only protects already-warm URLs and adds a standing miss+301 hop to every
+ * cold fetch (see README before vetoing).
+ *
+ * Idempotent, so Storyblok's retry-on-non-2xx behaviour is safe.
+ */
+declare const _default: any;
+export default _default;

package/dist/runtime/server/api/webhook.post.js

@@ -0,0 +1,54 @@
+import { Buffer } from "node:buffer";
+import { createHmac, timingSafeEqual } from "node:crypto";
+import {
+  createError,
+  defineEventHandler,
+  readRawBody,
+  setResponseStatus,
+  useNitroApp,
+  useRuntimeConfig
+} from "#imports";
+import { refreshStoryblokCv } from "../utils/cv.js";
+const CONTENT_ACTIONS = ["published", "unpublished", "deleted", "moved"];
+export default defineEventHandler(async (event) => {
+  const { webhookSecret } = useRuntimeConfig().storyblokCv;
+  if (!webhookSecret) {
+    console.error("[storyblok-cv] webhook called but NUXT_STORYBLOK_CV_WEBHOOK_SECRET is not set");
+    throw createError({ status: 500, message: "Webhook secret not configured" });
+  }
+  const signature = event.headers.get("webhook-signature");
+  if (!signature) {
+    throw createError({ status: 401, message: "Missing signature" });
+  }
+  const bodyRaw = await readRawBody(event, "utf-8");
+  if (!bodyRaw) {
+    throw createError({ status: 400, message: "Empty payload" });
+  }
+  const expected = createHmac("sha1", webhookSecret).update(bodyRaw).digest("hex");
+  if (!safeEqual(signature, expected)) {
+    throw createError({ status: 401, message: "Invalid signature" });
+  }
+  let payload;
+  try {
+    payload = JSON.parse(bodyRaw);
+  } catch {
+    throw createError({ status: 400, message: "Malformed JSON payload" });
+  }
+  const context = {
+    payload,
+    refresh: CONTENT_ACTIONS.includes(payload.action)
+  };
+  const callHook = useNitroApp().hooks.callHook;
+  await callHook("storyblok-cv:webhook", context);
+  if (!context.refresh) {
+    setResponseStatus(event, 204);
+    return null;
+  }
+  const cv = await refreshStoryblokCv();
+  return { ok: true, cv };
+});
+function safeEqual(a, b) {
+  const bufferA = Buffer.from(a);
+  const bufferB = Buffer.from(b);
+  return bufferA.length === bufferB.length && timingSafeEqual(bufferA, bufferB);
+}

package/dist/runtime/server/middleware/cv.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Attach the stored `cv` to `event.context.storyblokCv` for every page render;
+ * the app plugin reads it from there (no HTTP self-fetch) and pins it on the
+ * render client before content is fetched.
+ *
+ * With `ttl` configured, an expired value also triggers a background refresh
+ * (stale-while-revalidate) — the freshness mechanism for serverless/edge
+ * targets and multi-instance setups a webhook cannot reliably reach.
+ */
+declare const _default: any;
+export default _default;

package/dist/runtime/server/middleware/cv.js

@@ -0,0 +1,21 @@
+import { defineEventHandler, useRuntimeConfig } from "#imports";
+import { readStoryblokCv, refreshStoryblokCv } from "../utils/cv.js";
+export default defineEventHandler(async (event) => {
+  const path = event.path;
+  if (path.startsWith("/api/") || path.startsWith("/_") || path.startsWith("/__")) return;
+  const { ttl } = useRuntimeConfig().storyblokCv;
+  const record = await readStoryblokCv();
+  if (record?.cv) {
+    event.context.storyblokCv = record.cv;
+  }
+  if (ttl > 0 && (!record || Date.now() - record.fetchedAt > ttl)) {
+    const refresh = refreshStoryblokCv().catch((error) => {
+      console.error("[storyblok-cv] ttl refresh failed:", error);
+      return 0;
+    });
+    const waitUntil = event.waitUntil;
+    if (waitUntil) {
+      waitUntil.call(event, refresh);
+    }
+  }
+});

package/dist/runtime/server/plugins/init.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Populate the shared `cv` store once at boot so the first renders read a real
+ * value instead of nothing until the first publish webhook. Fire-and-forget so
+ * a slow or unreachable Storyblok can't block startup; until it lands, SSR
+ * simply self-pins the current `cv` (a fresh process has no stale pin).
+ */
+declare const _default: any;
+export default _default;

package/dist/runtime/server/plugins/init.js

@@ -0,0 +1,9 @@
+import { defineNitroPlugin, useRuntimeConfig } from "#imports";
+import { refreshStoryblokCv } from "../utils/cv.js";
+export default defineNitroPlugin(() => {
+  const { onStartup, token } = useRuntimeConfig().storyblokCv;
+  if (!onStartup || !token) return;
+  refreshStoryblokCv().catch((error) => {
+    console.error("[storyblok-cv] startup init failed:", error);
+  });
+});

package/dist/runtime/server/tsconfig.json

@@ -0,0 +1,4 @@
+{
+  "extends": "../../../playground/.nuxt/tsconfig.server.json",
+  "include": ["./**/*"]
+}

package/dist/runtime/server/utils/cv.d.ts

@@ -0,0 +1,20 @@
+export interface StoryblokCvRecord {
+    cv: number;
+    fetchedAt: number;
+}
+/**
+ * Live space `cv` straight from the API. `cdn/spaces/me` is the one endpoint
+ * storyblok-js-client never caches or cv-pins — and this raw fetch doesn't
+ * touch any client copy at all, so it works with client v5 through v7 alike.
+ */
+export declare function getLiveStoryblokCv(): Promise<number>;
+/** Stored `cv` record from the shared storage mount, or `null` before the first refresh. */
+export declare function readStoryblokCv(): Promise<StoryblokCvRecord | null>;
+/**
+ * Fetch the live `cv` and persist it to shared storage. Auto-imported in
+ * server code — call this from your own publish-webhook handler when the
+ * built-in webhook route is disabled. Concurrent calls are deduped.
+ *
+ * @returns the live `cv` (`0` if the API reported none)
+ */
+export declare function refreshStoryblokCv(): Promise<number>;

package/dist/runtime/server/utils/cv.js

@@ -0,0 +1,30 @@
+import { $fetch } from "ofetch";
+import { useRuntimeConfig, useStorage } from "#imports";
+const KEY = "current";
+const store = () => useStorage(useRuntimeConfig().storyblokCv.storage);
+export async function getLiveStoryblokCv() {
+  const { token, apiHost } = useRuntimeConfig().storyblokCv;
+  if (!token) {
+    throw new Error("[storyblok-cv] no access token configured");
+  }
+  const response = await $fetch("/v2/cdn/spaces/me", {
+    baseURL: apiHost,
+    query: { token }
+  });
+  return response?.space?.version ?? 0;
+}
+export async function readStoryblokCv() {
+  return store().getItem(KEY);
+}
+let pending = null;
+export function refreshStoryblokCv() {
+  pending ??= getLiveStoryblokCv().then(async (cv) => {
+    if (cv) {
+      await store().setItem(KEY, { cv, fetchedAt: Date.now() });
+    }
+    return cv;
+  }).finally(() => {
+    pending = null;
+  });
+  return pending;
+}

package/dist/types.d.mts

@@ -0,0 +1,3 @@
+export { default } from './module.mjs'
+
+export { type ModuleOptions } from './module.mjs'

package/package.json

@@ -0,0 +1,59 @@
+{
+  "name": "@towa-digital/storyblok-nuxt-cv",
+  "version": "0.1.2",
+  "description": "Keeps Storyblok published content fresh on long-running Nuxt servers by bridging the live cache version (cv) to the render client — no redeploy after publish.",
+  "repository": "github:towa-digital/storyblok-nuxt-cv",
+  "author": {
+    "name": "Matthias Frank",
+    "email": "matthias.frank@towa.at"
+  },
+  "license": "MIT",
+  "type": "module",
+  "publishConfig": {
+    "access": "public"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/types.d.mts",
+      "import": "./dist/module.mjs"
+    }
+  },
+  "main": "./dist/module.mjs",
+  "types": "./dist/types.d.mts",
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "prepack": "nuxt-module-build build",
+    "dev": "nuxi dev playground",
+    "dev:build": "nuxi build playground",
+    "dev:prepare": "nuxt-module-build build --stub && nuxt-module-build prepare && nuxi prepare playground",
+    "release": "npm run lint && npm run test && npm run prepack && changelogen --release && npm publish",
+    "lint": "eslint .",
+    "test": "vitest run",
+    "test:watch": "vitest watch",
+    "test:types": "vue-tsc --noEmit -p src/runtime/server/tsconfig.json && vue-tsc --noEmit -p tsconfig.app.json"
+  },
+  "dependencies": {
+    "@nuxt/kit": "^3.10.0 || ^4.0.0",
+    "defu": "^6.1.4",
+    "ofetch": "^1.4.1"
+  },
+  "peerDependencies": {
+    "@storyblok/nuxt": ">=5.0.0"
+  },
+  "devDependencies": {
+    "@nuxt/eslint-config": "^1.4.0",
+    "@nuxt/module-builder": "^1.0.1",
+    "@nuxt/schema": "^3.17.5",
+    "@nuxt/test-utils": "^3.19.0",
+    "@storyblok/nuxt": "^9.0.0",
+    "@types/node": "latest",
+    "changelogen": "^0.6.1",
+    "eslint": "^9.29.0",
+    "nuxt": "^3.17.5",
+    "typescript": "^5.8.0",
+    "vitest": "^3.2.0",
+    "vue-tsc": "^2.2.10"
+  }
+}