@towa-digital/storyblok-nuxt-cv 0.2.0 → 0.4.0

package/README.md

@@ -72,9 +72,10 @@ 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,                // e.g. 60_000 — background refresh when the stored cv is older (serverless/multi-instance)
+    ttl: false,                // seconds, e.g. 60 — background refresh when the stored cv is older (serverless/multi-instance)
     onStartup: true,           // populate the store once at boot
   },
 })
@@ -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` (e.g. 60_000)** — a webhook can't reach every isolate |
+| 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;
     /**
@@ -37,10 +46,11 @@ interface ModuleOptions {
      */
     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).
+     * Max age of the stored `cv`, **in seconds**, before a page render triggers a
+     * background refresh (e.g. `60` = one minute). 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). */
@@ -54,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.2.0",
+  "version": "0.4.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,7 +45,10 @@ const module$1 = defineNuxtModule({
         token: token ?? "",
         endpoint: options.endpoint || API_ENDPOINTS[options.region] || API_ENDPOINTS.eu,
         storage: options.storage,
-        ttl: options.ttl === false ? 0 : options.ttl ?? 0,
+        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,
         onStartup: options.onStartup !== false,
         webhookSecret: ""
       }
@@ -67,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/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,12 @@ 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>;
 /**
- * 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");
   }
@@ -20,7 +21,14 @@ let pending = null;
 export function refreshStoryblokCv() {
   pending ??= getLiveStoryblokCv().then(async (cv) => {
     if (cv) {
-      await store().setItem(KEY, { cv, fetchedAt: Date.now() });
+      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,6 +1,6 @@
 {
   "name": "@towa-digital/storyblok-nuxt-cv",
-  "version": "0.2.0",
+  "version": "0.4.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.",
   "repository": "github:towa-digital/storyblok-nuxt-cv",
   "author": {
@@ -55,5 +55,6 @@
     "typescript": "^5.8.0",
     "vitest": "^3.2.0",
     "vue-tsc": "^2.2.10"
-  }
+  },
+  "packageManager": "yarn@4.11.0+sha256.b0efc6597348fab50c777d2ff4b09e814974058cf012c3d687c9e80bca824358"
 }