@decocms/tanstack 7.68.0 → 7.69.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@decocms/tanstack",
-  "version": "7.68.0",
+  "version": "7.69.0",
   "type": "module",
   "description": "Deco framework binding for TanStack Start + Cloudflare Workers",
   "repository": {
@@ -27,9 +27,9 @@
     "lint:unused": "knip"
   },
   "dependencies": {
-    "@decocms/blocks": "7.68.0",
-    "@decocms/blocks-admin": "7.68.0",
-    "@decocms/blocks-cli": "7.68.0",
+    "@decocms/blocks": "7.69.0",
+    "@decocms/blocks-admin": "7.69.0",
+    "@decocms/blocks-cli": "7.69.0",
     "@deco-cx/warp-node": "^0.3.16",
     "fast-json-patch": "^3.1.0",
     "ws": "^8.18.0"

package/src/sdk/kvHydration.test.ts

@@ -250,6 +250,15 @@ describe("ensureBlocksHydrated when the bundle ships no decofile", () => {
     await expect(ensureBlocksHydrated(env)).rejects.toThrow(/not found and this bundle ships no/);
   });
 
+  it("throws when fast-deploy is off at runtime instead of serving {}", async () => {
+    withStubbedBundle();
+    setBlocks({});
+    const { kv } = makeKV();
+
+    await expect(ensureBlocksHydrated({})).rejects.toThrow(/fast-deploy is off/);
+    await expect(ensureBlocksHydrated({ DECO_KV: kv })).rejects.toThrow(/fast-deploy is off/);
+  });
+
   it("throws when the snapshot exists but is empty", async () => {
     // A seed that wrote `{}` would otherwise take the success branch, latch,
     // and serve the empty edge-cached site this guard exists to prevent.

package/src/sdk/kvHydration.ts

@@ -138,7 +138,16 @@ function bundleHasNoDecofile(): boolean {
  *   request retries instead of pinning the isolate to an empty decofile.
  */
 export function ensureBlocksHydrated(env: Env, _ctx?: ExecutionContextLike): Promise<void> {
-  if (!isFastDeployEnabled(env)) return Promise.resolve();
+  if (!isFastDeployEnabled(env)) {
+    // A stubbed bundle with fast-deploy off would serve an empty 200 the edge caches.
+    return bundleHasNoDecofile()
+      ? Promise.reject(
+          new Error(
+            `[CMS/KV] this bundle ships no decofile but fast-deploy is off (set ${FAST_DEPLOY_ENV}=1 and bind DECO_KV)`,
+          ),
+        )
+      : Promise.resolve();
+  }
   if (G.__deco!.kvHydrated) return Promise.resolve();
   if (G.__deco!.kvHydration) return G.__deco!.kvHydration;
 

package/src/vite/plugin.js

@@ -173,27 +173,52 @@ export function generateSchemaArgs(siteName) {
   return ["--site", siteName];
 }
 
+/**
+ * Env var a deploy pipeline sets to declare "I seed `decofile:<deployment-id>`
+ * into KV BEFORE activating this version". Set by the cfworkers-builder under
+ * exactly the condition that guards its seed step, so the stub below and the
+ * seed can never drift apart.
+ */
+const SEEDED_DEPLOY_ENV = "DECO_SEEDED_DEPLOY";
+
+/** Whether this build runs inside a pipeline that seeds KV before activation. */
+function isSeededDeployPipeline() {
+  const v = process.env[SEEDED_DEPLOY_ENV];
+  return v === "1" || v === "true";
+}
+
 /**
  * @param {object} [opts]
- * @param {boolean} [opts.fastDeploy=false] Stub `blocks.gen` out of the SERVER
- *   bundle too, so the worker's only copy of the decofile is the one hydrated
- *   from KV at cold start.
+ * @param {boolean | "auto"} [opts.fastDeploy="auto"] Stub `blocks.gen` out of
+ *   the SERVER bundle too, so the worker's only copy of the decofile is the one
+ *   hydrated from KV at cold start.
  *
  *   Without this, a fast-deploy site holds the decofile TWICE: the bundled
  *   `JSON.parse(...)` graph stays permanently reachable through the site's
  *   `import { blocks } from ".deco/blocks.gen"` module binding, and
  *   `ensureBlocksHydrated` adds a second graph via `setBlocks()`. For a 10MB
- *   decofile that is tens of MB of avoidable isolate memory.
+ *   decofile that is tens of MB of avoidable isolate memory, on a platform
+ *   whose per-isolate cap is 128MB and has no GC knob.
+ *
+ *   It is gated because it removes the fallback: with no bundled snapshot, a
+ *   cold start that cannot read KV has no content to serve, and
+ *   `ensureBlocksHydrated` fails the request loudly (5xx) rather than serving
+ *   an empty site that the edge would then cache — see `kvHydration.ts`. That
+ *   is only safe when the deploy pipeline seeds `decofile:<deployment-id>`
+ *   BEFORE the new version activates.
  *
- *   Opt-in because it removes the fallback: with no bundled snapshot, a cold
- *   start that cannot read KV has no content to serve. `ensureBlocksHydrated`
- *   detects that case and fails the request loudly (5xx) instead of serving an
- *   empty site — see `kvHydration.ts`. Only enable alongside
- *   `DECO_FAST_DEPLOY=1` + a `DECO_KV` binding + a deploy pipeline that seeds
- *   `decofile:<deployment-id>` BEFORE the new version activates.
+ *   `"auto"` (default) stubs only when the pipeline declares it seeds, via
+ *   `DECO_SEEDED_DEPLOY`. A site building through Cloudflare Workers Builds or
+ *   a manual `wrangler deploy` never sets it, so it keeps the bundled snapshot
+ *   and behaves exactly as before — no site-side config, no way to half-enable
+ *   it. `true` forces the stub, `false` disables it. A stubbed bundle also
+ *   needs `DECO_FAST_DEPLOY=1` and a `DECO_KV` binding at runtime — without
+ *   them `ensureBlocksHydrated` fails every request rather than serve `{}`.
  * @returns {import("vite").PluginOption}
  */
-export function decoVitePlugin({ fastDeploy = false } = {}) {
+export function decoVitePlugin({ fastDeploy = "auto" } = {}) {
+  // Resolved once: the pipeline's answer cannot change mid-build.
+  const stubBlocks = fastDeploy === "auto" ? isSeededDeployPipeline() : fastDeploy === true;
   // Set from the `config` hook (which Vite always runs before `load`). The
   // fastDeploy stub must apply to production builds ONLY: `vite dev` has no KV
   // to hydrate from, and the dev bootstrap below deliberately relies on reading
@@ -239,7 +264,7 @@ export function decoVitePlugin({ fastDeploy = false } = {}) {
         // `import { blocks }` binding keeps the bundled graph alive for the
         // isolate's whole life, even after `setBlocks()` swaps in the KV one).
         // Build only — see `isBuild` above.
-        if (fastDeploy && isBuild) {
+        if (stubBlocks && isBuild) {
           return "export const blocks = {};";
         }
 
@@ -785,7 +810,7 @@ export function decoVitePlugin({ fastDeploy = false } = {}) {
         // is not equivalent — draft-preview overrides can make a stubbed bundle
         // look populated, and a legitimately-empty decofile (new site) would
         // look stubbed.
-        __DECO_BLOCKS_STUBBED__: JSON.stringify(fastDeploy && command === "build"),
+        __DECO_BLOCKS_STUBBED__: JSON.stringify(stubBlocks && command === "build"),
       };
 
       // Only split chunks for production builds — dev uses unbundled ESM.

package/src/vite/plugin.test.ts

@@ -1,4 +1,4 @@
-import { describe, expect, it } from "vitest";
+import { afterEach, describe, expect, it, vi } from "vitest";
 import { decoVitePlugin } from "./plugin.js";
 
 /**
@@ -68,6 +68,12 @@ describe("decoVitePlugin — fastDeploy server stub", () => {
   const id = "/repo/.deco/blocks.gen.ts";
   const STUB = "export const blocks = {};";
 
+  // The default is "auto", which reads DECO_SEEDED_DEPLOY. Pin it off so the
+  // "default does not stub" assertions below can't be silently satisfied (or
+  // broken) by an ambient env var.
+  vi.stubEnv("DECO_SEEDED_DEPLOY", "");
+  afterEach(() => vi.stubEnv("DECO_SEEDED_DEPLOY", ""));
+
   /** @param {{fastDeploy?: boolean}} opts @param {"build"|"serve"} command */
   const make = (opts, command) => {
     const p = /** @type {any} */ (decoVitePlugin(opts));
@@ -110,3 +116,61 @@ describe("decoVitePlugin — fastDeploy server stub", () => {
     expect(def.define.__DECO_BLOCKS_STUBBED__).toBe("false");
   });
 });
+
+/**
+ * The `"auto"` default: stub only when the deploy pipeline declares it seeds
+ * `decofile:<deployment-id>` into KV BEFORE activating the new version.
+ *
+ * Stubbing without that guarantee is a hard outage, not a degraded mode — the
+ * bundle has no decofile, so `ensureBlocksHydrated` 5xxs on purpose rather than
+ * serving an empty site the edge would cache. Cloudflare Workers Builds and a
+ * manual `wrangler deploy` do not seed, and they never set the env.
+ */
+describe("decoVitePlugin — fastDeploy auto gate", () => {
+  const id = "/repo/.deco/blocks.gen.ts";
+  const STUB = "export const blocks = {};";
+
+  afterEach(() => vi.unstubAllEnvs());
+
+  /** @param {"build"|"serve"} command */
+  const makeDefault = (command) => {
+    const p = /** @type {any} */ (decoVitePlugin());
+    const cfg = p.config({}, { command });
+    return { plugin: p, cfg };
+  };
+
+  it("does not stub when the pipeline does not declare a seed step", () => {
+    vi.stubEnv("DECO_SEEDED_DEPLOY", "");
+    const { plugin, cfg } = makeDefault("build");
+    expect(plugin.load(id, { ssr: true })).not.toBe(STUB);
+    expect(cfg.define.__DECO_BLOCKS_STUBBED__).toBe("false");
+  });
+
+  it("stubs on a production build when the pipeline declares it seeds", () => {
+    vi.stubEnv("DECO_SEEDED_DEPLOY", "1");
+    const { plugin, cfg } = makeDefault("build");
+    expect(plugin.load(id, { ssr: true })).toBe(STUB);
+    expect(cfg.define.__DECO_BLOCKS_STUBBED__).toBe("true");
+  });
+
+  it("still never stubs SSR in dev, even inside a seeding pipeline", () => {
+    vi.stubEnv("DECO_SEEDED_DEPLOY", "1");
+    const { plugin, cfg } = makeDefault("serve");
+    expect(plugin.load(id, { ssr: true })).not.toBe(STUB);
+    expect(cfg.define.__DECO_BLOCKS_STUBBED__).toBe("false");
+  });
+
+  it("explicit false wins over a seeding pipeline", () => {
+    vi.stubEnv("DECO_SEEDED_DEPLOY", "1");
+    const p = /** @type {any} */ (decoVitePlugin({ fastDeploy: false }));
+    const cfg = p.config({}, { command: "build" });
+    expect(p.load(id, { ssr: true })).not.toBe(STUB);
+    expect(cfg.define.__DECO_BLOCKS_STUBBED__).toBe("false");
+  });
+
+  it("explicit true wins over a non-seeding pipeline", () => {
+    vi.stubEnv("DECO_SEEDED_DEPLOY", "");
+    const p = /** @type {any} */ (decoVitePlugin({ fastDeploy: true }));
+    expect(p.config({}, { command: "build" }).define.__DECO_BLOCKS_STUBBED__).toBe("true");
+  });
+});