@decocms/blocks-cli 7.34.2 → 7.34.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@decocms/blocks-cli",
-  "version": "7.34.2",
+  "version": "7.34.3",
   "type": "module",
   "description": "Deco codegen (generate-blocks, generate-schema, generate-invoke) and Fresh-to-TanStack migration tooling",
   "repository": {
@@ -31,7 +31,7 @@
     "lint:unused": "knip"
   },
   "dependencies": {
-    "@decocms/blocks": "7.34.2",
+    "@decocms/blocks": "7.34.3",
     "ts-morph": "^27.0.0",
     "tsx": "^4.22.5"
   },

package/scripts/generate-loaders.test.ts

@@ -95,10 +95,12 @@ describe("generate-loaders legacy artifact sync", () => {
     // New path must exist.
     expect(fs.existsSync(path.join(tmpDir, ".deco", "loaders.gen.ts"))).toBe(true);
 
-    // Old file must be synced (not stale placeholder).
+    // Old file must be synced as a re-export shim (not the stale placeholder,
+    // and not a verbatim copy — a byte copy would carry `.deco/`-relative
+    // import paths that break at the deeper legacy location).
     const oldContent = fs.readFileSync(path.join(oldDir, "loaders.gen.ts"), "utf-8");
     expect(oldContent).not.toBe("// stale\n");
-    expect(oldContent).toContain("site/loaders/related");
+    expect(oldContent).toContain('export * from "../../../.deco/loaders.gen"');
   }, 30_000);
 
   it("does not warn and does not sync when an explicit --out-file is passed", () => {

package/scripts/generate-sections.test.ts

@@ -72,6 +72,22 @@ describe("generate-sections walkDir exclusions", () => {
     expect(generated).not.toContain("Hero.stories.tsx");
     expect(generated).not.toContain("sections.gen.ts");
   }, 30_000);
+
+  it("extracts `export const deferred = true` into sectionMeta", () => {
+    fs.writeFileSync(
+      path.join(sectionsDir, "HeavyPLP.tsx"),
+      "export const deferred = true;\nexport default function HeavyPLP() { return null; }\n",
+    );
+
+    const { code } = runGenerator(["--sections-dir", sectionsDir, "--out-file", outFile]);
+    expect(code).toBe(0);
+
+    const generated = fs.readFileSync(outFile, "utf-8");
+    // The per-section deferral flag must survive the regex scan → sectionMeta,
+    // or applySectionConventions can never register it as always-defer.
+    expect(generated).toMatch(/"site\/sections\/HeavyPLP\.tsx":\s*\{[^}]*deferred:\s*true/);
+    expect(generated).toContain("deferred?: boolean;");
+  }, 30_000);
 });
 
 describe("generate-sections default output path (.deco/)", () => {
@@ -119,9 +135,14 @@ describe("generate-sections default output path (.deco/)", () => {
     expect(fs.existsSync(newDefault)).toBe(true);
     expect(fs.readFileSync(newDefault, "utf-8")).toContain("site/sections/Hero.tsx");
 
-    // Old file must be kept in sync so mid-migration imports still work.
+    // Old file is kept in sync as a re-export shim (NOT a verbatim copy — a
+    // byte copy would carry `.deco/`-relative import paths that break at the
+    // deeper legacy location). It re-exports the new file so mid-migration
+    // imports still resolve at any depth.
     const oldDefault = path.join(tmpDir, "src", "server", "cms", "sections.gen.ts");
-    expect(fs.readFileSync(oldDefault, "utf-8")).toContain("site/sections/Hero.tsx");
+    const oldContent = fs.readFileSync(oldDefault, "utf-8");
+    expect(oldContent).toContain('export * from "../../../.deco/sections.gen"');
+    expect(oldContent).not.toContain("site/sections/Hero.tsx");
   }, 30_000);
 
   it("does not warn when an explicit --out-file is passed, even if the OLD default file exists", () => {

package/scripts/generate-sections.ts

@@ -59,6 +59,7 @@ const EMIT_REGISTRY = args.includes("--registry");
 interface SectionMeta {
   eager?: boolean;
   neverDefer?: boolean;
+  deferred?: boolean;
   cache?: string;
   layout?: boolean;
   sync?: boolean;
@@ -67,7 +68,7 @@ interface SectionMeta {
   hasLoadingFallback?: boolean;
 }
 
-const EXPORT_CONST_RE = /export\s+const\s+(eager|neverDefer|cache|layout|sync|clientOnly|seo)\s*=\s*(.+?)(?:;|\n)/g;
+const EXPORT_CONST_RE = /export\s+const\s+(eager|neverDefer|deferred|cache|layout|sync|clientOnly|seo)\s*=\s*(.+?)(?:;|\n)/g;
 // Detects `export function LoadingFallback(...)`, `export const LoadingFallback = ...`, etc.
 const LOADING_FALLBACK_INLINE_RE = /export\s+(?:function|const|let|var)\s+LoadingFallback\b/;
 // Detects re-exports like:
@@ -209,6 +210,7 @@ lines.push("");
 lines.push("export interface SectionMetaEntry {");
 lines.push("  eager?: boolean;");
 lines.push("  neverDefer?: boolean;");
+lines.push("  deferred?: boolean;");
 lines.push("  cache?: string;");
 lines.push("  layout?: boolean;");
 lines.push("  sync?: boolean;");

package/scripts/lib/legacyArtifact.ts

@@ -23,12 +23,42 @@ export function warnLegacyArtifact(oldPath: string, newPath: string): void {
 }
 
 /**
- * Copies the freshly-generated file at `newPath` back to `oldPath` so that
- * sites mid-migration whose imports still point at the old location see
- * up-to-date output without requiring a full migration first.
- * Call this after generation completes, only when the old file was detected.
+ * Keeps the legacy `oldPath` in sync with the freshly-generated `newPath` so
+ * sites mid-migration whose imports still point at the old location keep
+ * working without a full migration first. Call this after generation
+ * completes, only when the old file was detected.
+ *
+ * For `.ts`/`.tsx` artifacts a verbatim copy would be broken: the generated
+ * file's import specifiers are relative to `newPath`'s directory (`.deco/`,
+ * one level deep), but `oldPath` lives deeper (`src/server/cms/`), so every
+ * `../src/...` specifier would resolve to a nonexistent path and crash the
+ * dev server on boot. Instead we write a re-export shim pointing at `newPath`
+ * — one specifier, correct at any depth, and self-documenting the deprecation.
+ * The generated `.gen.ts` files only have named exports, so `export *` forwards
+ * everything (including type exports). Non-TS artifacts (e.g. `.json` schema)
+ * have no import paths, so a byte copy is still correct.
  */
 export function syncLegacyArtifact(oldPath: string, newPath: string): void {
   fs.mkdirSync(path.dirname(oldPath), { recursive: true });
-  fs.copyFileSync(newPath, oldPath);
+
+  if (!/\.tsx?$/.test(oldPath)) {
+    fs.copyFileSync(newPath, oldPath);
+    return;
+  }
+
+  const newRel = path.relative(process.cwd(), newPath).replace(/\\/g, "/");
+  let specifier = path
+    .relative(path.dirname(oldPath), newPath)
+    .replace(/\\/g, "/")
+    .replace(/\.tsx?$/, "");
+  if (!specifier.startsWith(".")) specifier = `./${specifier}`;
+
+  fs.writeFileSync(
+    oldPath,
+    `// AUTO-GENERATED — DO NOT EDIT.\n` +
+      `// Deprecated path: the generator now writes to "${newRel}".\n` +
+      `// This file only re-exports it so mid-migration imports keep working.\n` +
+      `// Update your imports to the new path, then delete this file.\n` +
+      `export * from "${specifier}";\n`,
+  );
 }

package/scripts/migrate/templates/routes.test.ts

@@ -57,3 +57,34 @@ describe("scaffolded deco admin routes use HMR-safe factories", () => {
     });
   }
 });
+
+/**
+ * Regression guard: the page renderers must wire `loadDeferredSectionFn` to the
+ * `deferredSectionLoader` shim, never the raw `loadDeferredSection` server fn.
+ * `loadDeferredSection` is a createServerFn with an inputValidator, so it must
+ * be called as `fn({ data })`; DeferredSectionWrapper calls `loadFn(bareArgs)`,
+ * so passing the raw fn leaves `ctx.data` undefined and the deferred section
+ * renders blank. The shim wraps the `{ data }` envelope.
+ */
+describe("scaffolded page routes wire the deferred-loader shim, not the raw server fn", () => {
+  for (const platform of ["vtex", "custom"] as const) {
+    describe(`platform: ${platform}`, () => {
+      const files = generateRoutes(makeCtx(platform));
+
+      for (const file of ["src/routes/index.tsx", "src/routes/$.tsx"] as const) {
+        it(`${file} passes deferredSectionLoader from the sdk subpath`, () => {
+          const content = files[file];
+          expect(content, `${file} must be emitted`).toBeTypeOf("string");
+
+          expect(content).toContain(
+            'import { deferredSectionLoader } from "@decocms/tanstack/sdk/deferredSectionLoader"',
+          );
+          expect(content).toContain("loadDeferredSectionFn={deferredSectionLoader}");
+
+          // The broken form: the raw server fn passed directly.
+          expect(content).not.toContain("loadDeferredSectionFn={loadDeferredSection}");
+        });
+      }
+    });
+  }
+});

package/scripts/migrate/templates/routes.ts

@@ -115,7 +115,8 @@ function RootLayout() {
 
 function generateIndex(ctx: MigrationContext, siteTitle: string): string {
   return `import { createFileRoute } from "@tanstack/react-router";
-import { cmsHomeRouteConfig, DecoPageRenderer, loadDeferredSection } from "@decocms/tanstack";
+import { cmsHomeRouteConfig, DecoPageRenderer } from "@decocms/tanstack";
+import { deferredSectionLoader } from "@decocms/tanstack/sdk/deferredSectionLoader";
 
 // MIGRATION TODO: customize defaultTitle / defaultDescription / fallback
 // copy below for ${siteTitle}. CMS \`Site.seo\` overrides these once block
@@ -151,7 +152,7 @@ function HomePage() {
       deferredPromises={data.deferredPromises}
       pagePath={data.pagePath}
       pageUrl={data.pageUrl}
-      loadDeferredSectionFn={loadDeferredSection}
+      loadDeferredSectionFn={deferredSectionLoader}
     />
   );
 }
@@ -160,7 +161,8 @@ function HomePage() {
 
 function generateCatchAll(ctx: MigrationContext, siteTitle: string): string {
   return `import { createFileRoute } from "@tanstack/react-router";
-import { cmsRouteConfig, DecoPageRenderer, loadDeferredSection } from "@decocms/tanstack";
+import { cmsRouteConfig, DecoPageRenderer } from "@decocms/tanstack";
+import { deferredSectionLoader } from "@decocms/tanstack/sdk/deferredSectionLoader";
 
 // MIGRATION TODO: customize defaultTitle / defaultDescription for ${siteTitle}
 // (CMS \`Site.seo\` overrides these per-page once block resolution kicks in).
@@ -188,7 +190,7 @@ function CmsPage() {
       deferredPromises={data.deferredPromises}
       pagePath={data.pagePath}
       pageUrl={data.pageUrl}
-      loadDeferredSectionFn={loadDeferredSection}
+      loadDeferredSectionFn={deferredSectionLoader}
     />
   );
 }