@towa-digital/storyblok-nuxt-cv 0.3.0 → 0.5.0

package/README.md

@@ -72,6 +72,7 @@ export default defineNuxtConfig({
     region: 'eu',              // eu | us | ap | ca | cn
     endpoint: undefined,       // full API endpoint incl. /v2 (like @storyblok/nuxt); overrides region — for proxied spaces
     storage: 'storyblok-cv',   // nitro storage mount name
+    fsStore: false,            // true → module mounts an fs store at <cwd>/.data/<storage> at RUNTIME (node/PM2; owner-correct, per-deploy). string = custom base.
     statusRoute: '/api/storyblok-cv',     // GET current cv; false to disable
     webhook: true,             // built-in route /api/storyblok-cv-webhook; string = custom route; false = use refreshStoryblokCv() yourself
     ttl: false,                // seconds, e.g. 60 — background refresh when the stored cv is older (serverless/multi-instance)
@@ -85,18 +86,36 @@ export default defineNuxtConfig({
 | 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 |
+| PM2 **cluster** on one host (`instances: 'max'`) | **`fsStore: true`** (or a manual `fs` mount) | webhook |
 | Multi-node / containers | mount Redis | webhook |
 | Cloudflare / Vercel Edge / Netlify (isolates) | default | **`ttl` (seconds, e.g. `60`)** — a webhook can't reach every isolate |
 
+On a **PM2 cluster** memory is per-worker, so a webhook only updates one worker.
+The simplest correct fix is **`fsStore`** — the module mounts an `fs` store at a
+path resolved **at runtime**, inside the app's own directory (owned by the
+runtime user, unique per deployment):
+
+```ts
+storyblokCv: { fsStore: true }   // → <cwd>/.data/storyblok-cv  (or fsStore: '/abs/path')
+```
+
+Prefer this over hand-configuring `nitro.storage` — it's owner-correct and
+per-deploy, so it sidesteps the gotchas below. **Node/PM2 only** — serverless/edge
+have no writable fs, use `ttl` there.
+
+<details><summary>If you configure the <code>fs</code> mount yourself instead</summary>
+
 ```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' } },
-},
+nitro: { storage: { 'storyblok-cv': { driver: 'fs', base: '/absolute/writable/path' } } }
 ```
 
+Use an **absolute** path writable by the runtime user. A *relative* `base` is
+resolved at **build time** (it bakes the build/CI cwd, not the server's) — which
+is exactly what `fsStore` sidesteps by resolving at runtime. Persist failures are
+logged as `[storyblok-cv] … FAILED to persist`.
+
+</details>
+
 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.
 

package/dist/module.d.mts

@@ -27,6 +27,15 @@ interface ModuleOptions {
      * an `fs` driver, for multi-node mount Redis, in the host's `nitro.storage`.
      */
     storage?: string;
+    /**
+     * Mount the `cv` store on the `fs` driver at a path resolved **at runtime** —
+     * in the app's own dir, owned by the runtime user, unique per deploy.
+     * `true` → `<cwd>/.data/<storage>`; a string sets the base (relative resolved
+     * against `process.cwd()`). Node/PM2 only — not serverless/edge (no writable
+     * fs; use `ttl`). Runtime resolution avoids a static `nitro.storage` base
+     * baking the build-time cwd.
+     */
+    fsStore?: boolean | string;
     /** GET route exposing the current `cv` (client re-pins, debugging). `false` disables. */
     statusRoute?: string | false;
     /**
@@ -55,6 +64,7 @@ declare module '@nuxt/schema' {
             token: string;
             endpoint: string;
             storage: string;
+            fsStore: boolean | string;
             ttl: number;
             onStartup: boolean;
             webhookSecret: string;

package/dist/module.json

@@ -4,7 +4,7 @@
   "compatibility": {
     "nuxt": ">=3.10.0"
   },
-  "version": "0.3.0",
+  "version": "0.5.0",
   "builder": {
     "@nuxt/module-builder": "1.0.2",
     "unbuild": "3.6.1"

package/dist/module.mjs

@@ -19,6 +19,7 @@ const module$1 = defineNuxtModule({
     debug: false,
     region: "eu",
     storage: "storyblok-cv",
+    fsStore: false,
     statusRoute: "/api/storyblok-cv",
     webhook: true,
     ttl: false,
@@ -44,6 +45,7 @@ const module$1 = defineNuxtModule({
         token: token ?? "",
         endpoint: options.endpoint || API_ENDPOINTS[options.region] || API_ENDPOINTS.eu,
         storage: options.storage,
+        fsStore: options.fsStore ?? false,
         // Option is in seconds (nicer DX); convert to ms for the runtime, which
         // compares against `Date.now()`.
         ttl: options.ttl === false ? 0 : (options.ttl ?? 0) * 1e3,
@@ -69,6 +71,9 @@ const module$1 = defineNuxtModule({
         handler: resolver.resolve("./runtime/server/api/webhook.post")
       });
     }
+    if (options.fsStore) {
+      addServerPlugin(resolver.resolve("./runtime/server/plugins/mount"));
+    }
     addServerPlugin(resolver.resolve("./runtime/server/plugins/init"));
     const utils = resolver.resolve("./runtime/server/utils/cv");
     addServerImports([

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

@@ -1,11 +1,2 @@
-/**
- * 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

@@ -1,8 +1,17 @@
 import { defineEventHandler, useRuntimeConfig } from "#imports";
 import { readStoryblokCv, refreshStoryblokCv } from "../utils/cv.js";
+let lastMapSyncCheck = 0;
+const MAP_SYNC_INTERVAL = 5e3;
 export default defineEventHandler(async (event) => {
   const path = event.path;
-  if (path.startsWith("/api/") || path.startsWith("/_") || path.startsWith("/__")) return;
+  if (path.startsWith("/api/") || path.startsWith("/_") || path.startsWith("/__")) {
+    if (Date.now() - lastMapSyncCheck > MAP_SYNC_INTERVAL) {
+      lastMapSyncCheck = Date.now();
+      readStoryblokCv().catch(() => {
+      });
+    }
+    return;
+  }
   const { ttl } = useRuntimeConfig().storyblokCv;
   const record = await readStoryblokCv();
   if (record?.cv) {

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

@@ -0,0 +1,8 @@
+/**
+ * Mount the `cv` store on the fs driver at a path resolved at runtime — in the
+ * app's own dir, owned by the runtime user, unique per deploy. Runs before the
+ * init plugin (mounts before the startup refresh writes); only registered when
+ * `fsStore` is set, so edge builds never import the fs driver.
+ */
+declare const _default: any;
+export default _default;

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

@@ -0,0 +1,8 @@
+import { isAbsolute, join } from "node:path";
+import fsDriver from "unstorage/drivers/fs-lite";
+import { defineNitroPlugin, useRuntimeConfig, useStorage } from "#imports";
+export default defineNitroPlugin(() => {
+  const { storage, fsStore } = useRuntimeConfig().storyblokCv;
+  const base = typeof fsStore === "string" ? isAbsolute(fsStore) ? fsStore : join(process.cwd(), fsStore) : join(process.cwd(), ".data", storage);
+  useStorage().mount(storage, fsDriver({ base }));
+});

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

@@ -8,12 +8,13 @@ export interface StoryblokCvRecord {
  * 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. */
+/** Stored `cv` record from the storage mount, or `null` before the first refresh. */
 export declare function readStoryblokCv(): Promise<StoryblokCvRecord | null>;
+export declare function syncServerClientCv(cv: number): void;
 /**
- * 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.
+ * Fetch the live `cv` and persist it to 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)
  */

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

@@ -1,9 +1,10 @@
 import { $fetch } from "ofetch";
 import { useRuntimeConfig, useStorage } from "#imports";
 const KEY = "current";
-const store = () => useStorage(useRuntimeConfig().storyblokCv.storage);
+const cfg = () => useRuntimeConfig().storyblokCv;
+const store = () => useStorage(cfg().storage);
 export async function getLiveStoryblokCv() {
-  const { token, endpoint } = useRuntimeConfig().storyblokCv;
+  const { token, endpoint } = cfg();
   if (!token) {
     throw new Error("[storyblok-cv] no access token configured");
   }
@@ -14,13 +15,46 @@ export async function getLiveStoryblokCv() {
   return response?.space?.version ?? 0;
 }
 export async function readStoryblokCv() {
-  return store().getItem(KEY);
+  const record = await store().getItem(KEY);
+  if (record?.cv) syncServerClientCv(record.cv);
+  return record;
+}
+let serverClient = null;
+let lastSyncedCv = 0;
+export function syncServerClientCv(cv) {
+  if (!cv || cv === lastSyncedCv || serverClient === false) return;
+  if (serverClient) {
+    lastSyncedCv = cv;
+    serverClient.setCacheVersion(cv);
+    return;
+  }
+  import("storyblok-js-client").then((mod) => {
+    const StoryblokClient = mod?.default;
+    const { token } = cfg();
+    if (!StoryblokClient || !token) {
+      serverClient = false;
+      return;
+    }
+    serverClient = new StoryblokClient({ accessToken: token });
+    lastSyncedCv = cv;
+    serverClient.setCacheVersion(cv);
+  }).catch(() => {
+    serverClient = false;
+  });
 }
 let pending = null;
 export function refreshStoryblokCv() {
   pending ??= getLiveStoryblokCv().then(async (cv) => {
     if (cv) {
-      await store().setItem(KEY, { cv, fetchedAt: Date.now() });
+      syncServerClientCv(cv);
+      try {
+        await store().setItem(KEY, { cv, fetchedAt: Date.now() });
+      } catch (error) {
+        console.error(
+          "[storyblok-cv] fetched cv but FAILED to persist it \u2014 check the storage mount is writable by the runtime user:",
+          error
+        );
+      }
     }
     return cv;
   }).finally(() => {

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@towa-digital/storyblok-nuxt-cv",
-  "version": "0.3.0",
-  "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.",
+  "version": "0.5.0",
+  "description": "Keeps Storyblok published content fresh on long-running Nuxt servers by bridging the live cache version (cv) to the render client \u2014 no redeploy after publish.",
   "repository": "github:towa-digital/storyblok-nuxt-cv",
   "author": {
     "name": "Matthias Frank",
@@ -55,5 +55,6 @@
     "typescript": "^5.8.0",
     "vitest": "^3.2.0",
     "vue-tsc": "^2.2.10"
-  }
+  },
+  "packageManager": "yarn@4.11.0+sha256.b0efc6597348fab50c777d2ff4b09e814974058cf012c3d687c9e80bca824358"
 }