@decocms/start 2.4.2 → 2.6.0

package/.cursor/skills/deco-to-tanstack-migration/references/vite-config/README.md

@@ -1,12 +1,18 @@
 # Vite Configuration
 
-## Final Config (Post-Migration)
+For the canonical battle-tested template (with VTEX dev proxy, CSP headers,
+React Compiler, dedupe, framework plugin, and rollup chunk strategy) see
+[`../../templates/vite-config.md`](../../templates/vite-config.md).
 
-After all imports are rewritten, the config should be minimal:
+This page covers the post-migration **minimum viable config** if you've
+stripped everything optional. Real sites should use the full template.
+
+## Minimum Viable Config
 
 ```typescript
 import { cloudflare } from "@cloudflare/vite-plugin";
 import { tanstackStart } from "@tanstack/react-start/plugin/vite";
+import { decoVitePlugin } from "@decocms/start/vite";
 import react from "@vitejs/plugin-react";
 import tailwindcss from "@tailwindcss/vite";
 import { defineConfig } from "vite";
@@ -24,8 +30,23 @@ export default defineConfig({
       },
     }),
     tailwindcss(),
+    // Required — server-only stubs, blocks.gen.ts fast-path, meta.gen
+    // client stub, daemon/tunnel for dev mode. Without this, client
+    // bundle crashes on node:async_hooks / react-dom/server transitively
+    // imported by @decocms/start.
+    decoVitePlugin(),
   ],
   resolve: {
+    // Required — dedupe React/TanStack/Deco packages so there's only one
+    // instance of each. Without this you get "Invalid hook call" errors.
+    dedupe: [
+      "@decocms/start",
+      "@decocms/apps",
+      "@tanstack/react-start",
+      "@tanstack/react-router",
+      "react",
+      "react-dom",
+    ],
     alias: {
       "~": srcDir,
     },
@@ -35,6 +56,10 @@ export default defineConfig({
 
 **One alias only**: `~` -> `src/`. Nothing else.
 
+The `decoVitePlugin()` call is **mandatory** — the older skill examples
+that omitted it (or inlined the stub logic) reflect the pre-2.x state of
+`@decocms/start` and will produce build/runtime failures on current versions.
+
 ## tsconfig.json
 
 Must mirror the Vite alias:

package/.cursor/skills/deco-to-tanstack-migration/templates/vite-config.md

@@ -1,10 +1,13 @@
 # vite.config.ts Template
 
-Battle-tested configuration from espacosmart-storefront.
+Battle-tested configuration. Uses the framework's `decoVitePlugin()` for the
+server-only stub layer (rather than re-implementing it inline like older
+sites did).
 
 ```typescript
 import { cloudflare } from "@cloudflare/vite-plugin";
 import { tanstackStart } from "@tanstack/react-start/plugin/vite";
+import { decoVitePlugin } from "@decocms/start/vite";
 import react from "@vitejs/plugin-react";
 import tailwindcss from "@tailwindcss/vite";
 import { defineConfig } from "vite";
@@ -12,90 +15,86 @@ import path from "path";
 
 const srcDir = path.resolve(__dirname, "src");
 
+// VTEX dev proxy — adjust to your account / commerce backend.
+const VTEX_ACCOUNT = process.env.VTEX_ACCOUNT || "mystore";
+const VTEX_ORIGIN = `https://${VTEX_ACCOUNT}.vtexcommercestable.com.br`;
+
 export default defineConfig({
+  server: {
+    port: parseInt(process.env.PORT ?? "5173", 10),
+    // When the deco daemon injects PORT, bind to all interfaces so Deno's
+    // TCP connect (127.0.0.1) can reach Vite regardless of IPv4/IPv6.
+    host: process.env.PORT ? "0.0.0.0" : undefined,
+    headers: {
+      // Allow embedding in iframes from trusted admin origins.
+      "Content-Security-Policy":
+        "frame-ancestors 'self' https://*.deco.studio http://localhost:* https://localhost:* https://admin.deco.cx https://studio.decocms.com",
+    },
+    proxy: {
+      "/api/": {
+        target: VTEX_ORIGIN,
+        changeOrigin: true,
+        cookieDomainRewrite: { "*": "" },
+      },
+      "/checkout": {
+        target: VTEX_ORIGIN,
+        changeOrigin: true,
+        cookieDomainRewrite: { "*": "" },
+      },
+    },
+  },
   plugins: [
     cloudflare({ viteEnvironment: { name: "ssr" } }),
     tanstackStart({ server: { entry: "server" } }),
     react({
       babel: {
-        plugins: [
-          ["babel-plugin-react-compiler", { target: "19" }],
-        ],
+        plugins: [["babel-plugin-react-compiler", { target: "19" }]],
       },
     }),
     tailwindcss(),
-    // CRITICAL: Stubs for client bundles that transitively import server modules.
-    // Without this, client build crashes on node:async_hooks, react-dom/server, etc.
-    {
-      name: "deco-server-only-stubs",
-      enforce: "pre" as const,
-      resolveId(id, _importer, options) {
-        if (options?.ssr) return undefined;
-        const CLIENT_STUBS: Record<string, string> = {
-          "react-dom/server": "\0stub:react-dom-server",
-          "react-dom/server.browser": "\0stub:react-dom-server",
-          "node:stream": "\0stub:node-stream",
-          "node:stream/web": "\0stub:node-stream-web",
-          "node:async_hooks": "\0stub:node-async-hooks",
-          "tanstack-start-injected-head-scripts:v": "\0stub:tanstack-head-scripts",
-        };
-        return CLIENT_STUBS[id];
-      },
-      configEnvironment(name: string, env: any) {
-        if (name === "ssr" || name === "client") {
-          env.optimizeDeps = env.optimizeDeps || {};
-          env.optimizeDeps.esbuildOptions = env.optimizeDeps.esbuildOptions || {};
-          env.optimizeDeps.esbuildOptions.jsx = "automatic";
-          env.optimizeDeps.esbuildOptions.jsxImportSource = "react";
-        }
-      },
-      load(id) {
-        if (id === "\0stub:react-dom-server") {
-          return [
-            "const noop = () => '';",
-            "export const renderToString = noop;",
-            "export const renderToStaticMarkup = noop;",
-            "export const renderToReadableStream = noop;",
-            "export const resume = noop;",
-            "export const version = '19.0.0';",
-            "export default { renderToString: noop, renderToStaticMarkup: noop, renderToReadableStream: noop, resume: noop, version: '19.0.0' };",
-          ].join("\n");
-        }
-        if (id === "\0stub:node-stream") {
-          return "export class PassThrough {}; export class Readable {}; export class Writable {}; export default { PassThrough, Readable, Writable };";
-        }
-        if (id === "\0stub:node-stream-web") {
-          return "export const ReadableStream = globalThis.ReadableStream; export const WritableStream = globalThis.WritableStream; export const TransformStream = globalThis.TransformStream; export default { ReadableStream, WritableStream, TransformStream };";
-        }
-        if (id === "\0stub:node-async-hooks") {
-          return [
-            "class _ALS { getStore() { return undefined; } run(_store, fn, ...args) { return fn(...args); } enterWith() {} disable() {} }",
-            "export const AsyncLocalStorage = _ALS;",
-            "export const AsyncResource = class {};",
-            "export function executionAsyncId() { return 0; }",
-            "export function createHook() { return { enable() {}, disable() {} }; }",
-            "export default { AsyncLocalStorage: _ALS, AsyncResource, executionAsyncId, createHook };",
-          ].join("\n");
-        }
-        if (id === "\0stub:tanstack-head-scripts") {
-          return "export const injectedHeadScripts = undefined;";
+    // Framework plugin — provides server-only stubs (react-dom/server,
+    // node:async_hooks, etc.), blocks.gen.ts JSON-fast-path, meta.gen
+    // client stub, daemon/tunnel for dev mode, and correct manualChunks
+    // (NOT splitting @decocms/start / @decocms/apps which have circular
+    // re-exports). Replaces ~80 lines of boilerplate that older sites
+    // had inline.
+    decoVitePlugin(),
+  ],
+  build: {
+    sourcemap: "hidden",
+    rollupOptions: {
+      onLog(level, log, handler) {
+        // Silence harmless "dynamic import will not move module" warning
+        // emitted when a module is imported both statically and dynamically.
+        if (
+          log.code === "PLUGIN_WARNING" &&
+          log.plugin === "vite:reporter" &&
+          log.message?.includes("dynamic import will not move module")
+        ) {
+          return;
         }
+        handler(level, log);
       },
     },
-  ],
-  // Inject site name at build time (not runtime)
+  },
   define: {
+    // Inject site name at build time, not read at runtime.
     "process.env.DECO_SITE_NAME": JSON.stringify(
-      process.env.DECO_SITE_NAME || "my-store"
+      process.env.DECO_SITE_NAME || "my-store",
     ),
   },
   esbuild: {
     jsx: "automatic",
     jsxImportSource: "react",
+    // Strip console.log in production; keep .warn / .error for debugging.
+    pure: ["console.log"],
   },
   resolve: {
-    // CRITICAL: Without dedupe, multiple React/TanStack instances cause hook errors
+    // CRITICAL: without dedupe, multiple React/TanStack instances cause
+    // "Invalid hook call" errors at runtime.
     dedupe: [
+      "@decocms/start",
+      "@decocms/apps",
       "@tanstack/react-start",
       "@tanstack/react-router",
       "@tanstack/react-start-server",
@@ -115,8 +114,84 @@ export default defineConfig({
 
 ## Key Points
 
-1. **deco-server-only-stubs plugin** — Required. Client bundles transitively import `node:async_hooks`, `react-dom/server`, etc. Without stubs, build crashes.
-2. **resolve.dedupe** — Required. Without it, multiple React instances cause "Invalid hook call" errors.
-3. **process.env.DECO_SITE_NAME via define** — Must be injected at build time, not read at runtime.
-4. **React Compiler** — `babel-plugin-react-compiler` with target 19 for automatic memoization.
-5. **esbuild.jsx** — Must be `"automatic"` with `jsxImportSource: "react"` for proper JSX transform.
+1. **`decoVitePlugin()`** — Required. Replaces ~80 lines of inline boilerplate
+   that older sites had to copy. Provides:
+   - Client stubs for server-only modules (`react-dom/server`,
+     `node:async_hooks`, `node:stream`, etc.)
+   - `blocks.gen.ts` JSON fast-path (10-100x parse speedup for large registries)
+   - `meta.gen.{json,ts}` client stub (cuts admin schema 0.5-5MB out of
+     browser bundle)
+   - Daemon/tunnel for dev mode (when `DECO_SITE_NAME` env is set)
+   - Production `manualChunks` that does NOT split `@decocms/start` or
+     `@decocms/apps` (those have circular re-exports and crash when chunked
+     separately)
+   - `allowedHosts` for tunnel domains (`.deco.host`, `.decocdn.com`,
+     `.deco.studio`)
+   - JSX automatic / react import-source defaults
+
+2. **`resolve.dedupe`** — Required. Without it, multiple React instances
+   cause "Invalid hook call" errors. The list MUST include both
+   `@decocms/start` and `@decocms/apps` because they re-export TanStack
+   types and registry singletons.
+
+3. **`process.env.DECO_SITE_NAME` via `define`** — Must be injected at
+   build time, not read at runtime. Workers don't have a Node-style
+   `process.env` at runtime.
+
+4. **React Compiler** — `babel-plugin-react-compiler` with `target: "19"`
+   for automatic memoization. Requires `@vitejs/plugin-react`, not the
+   default SWC plugin.
+
+5. **`esbuild.jsx: "automatic"` with `jsxImportSource: "react"`** — Without
+   it, JSX falls back to `React.createElement` references that may not
+   resolve.
+
+6. **CSP `frame-ancestors`** — Required for the admin (`*.deco.studio`,
+   `admin.deco.cx`, `studio.decocms.com`) to embed previews in iframes.
+
+7. **VTEX dev proxy** — Local `/api/`, `/checkout` requests proxied to
+   the upstream commerce backend so cookie-based session works in dev
+   without CORS gymnastics.
+
+## What older site templates inline (and why this template doesn't)
+
+Some older guides show two extra inline plugins:
+
+```ts
+// site-manual-chunks — overrides framework default chunking
+{ name: "site-manual-chunks", config(_cfg, { command }) { ... } }
+
+// deco-stub-meta-gen — stubs admin schema on client
+{ name: "deco-stub-meta-gen", enforce: "pre", resolveId(...), load(...) }
+```
+
+Both are obsolete after `@decocms/start` >= 2.5.0:
+- The framework's `manualChunks` no longer splits `@decocms/start` /
+  `@decocms/apps` (the old split caused circular-dep load-order crashes —
+  every site overrode it).
+- The framework now stubs `meta.gen.{json,ts}` on the client by default.
+
+If you're on an older version, keep the inline plugins until you can bump.
+
+## tsconfig.json (matches the Vite alias)
+
+```json
+{
+  "compilerOptions": {
+    "jsx": "react-jsx",
+    "moduleResolution": "bundler",
+    "module": "ESNext",
+    "target": "ES2022",
+    "skipLibCheck": true,
+    "strictNullChecks": true,
+    "baseUrl": ".",
+    "paths": {
+      "~/*": ["./src/*"]
+    }
+  },
+  "include": ["src/**/*", "vite.config.ts"]
+}
+```
+
+No `$store/*`, `site/*`, `apps/*`, `preact`, `@preact/signals`,
+`@deco/deco` paths. Those are all dead.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@decocms/start",
-  "version": "2.4.2",
+  "version": "2.6.0",
   "type": "module",
   "description": "Deco framework for TanStack Start - CMS bridge, admin protocol, hooks, schema generation",
   "main": "./src/index.ts",

package/scripts/deco-migrate-cli.ts

@@ -25,7 +25,7 @@ import * as fs from "node:fs";
 import * as path from "node:path";
 import { fileURLToPath } from "node:url";
 import { execSync, spawnSync } from "node:child_process";
-import { banner, stat, red, green, yellow, cyan, bold, dim, icons } from "./migrate/colors.ts";
+import { banner, stat, red, green, yellow, cyan, bold, dim, icons } from "./migrate/colors";
 
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = path.dirname(__filename);

package/scripts/migrate/analyzers/island-classifier.ts

@@ -1,7 +1,7 @@
 import * as fs from "node:fs";
 import * as path from "node:path";
-import type { MigrationContext, IslandClassification } from "../types.ts";
-import { log } from "../types.ts";
+import type { MigrationContext, IslandClassification } from "../types";
+import { log } from "../types";
 
 const REEXPORT_RE = /^export\s+\{\s*default\s*\}\s+from\s+["']([^"']+)["']/m;
 const NAMED_REEXPORT_RE = /^export\s+\{[^}]+\}\s+from\s+["']([^"']+)["']/m;

package/scripts/migrate/analyzers/loader-inventory.ts

@@ -1,7 +1,7 @@
 import * as fs from "node:fs";
 import * as path from "node:path";
-import type { MigrationContext, LoaderInfo, Platform } from "../types.ts";
-import { log } from "../types.ts";
+import type { MigrationContext, LoaderInfo, Platform } from "../types";
+import { log } from "../types";
 
 /** Well-known loaders that map directly to @decocms/apps equivalents */
 const APPS_EQUIVALENTS: Record<string, string> = {

package/scripts/migrate/analyzers/section-metadata.ts

@@ -1,7 +1,7 @@
 import * as fs from "node:fs";
 import * as path from "node:path";
-import type { MigrationContext, SectionMeta } from "../types.ts";
-import { log } from "../types.ts";
+import type { MigrationContext, SectionMeta } from "../types";
+import { log } from "../types";
 
 const HEADER_RE = /\bheader\b/i;
 const FOOTER_RE = /\bfooter\b/i;

package/scripts/migrate/analyzers/theme-extractor.ts

@@ -1,7 +1,7 @@
 import * as fs from "node:fs";
 import * as path from "node:path";
-import type { MigrationContext } from "../types.ts";
-import { log } from "../types.ts";
+import type { MigrationContext } from "../types";
+import { log } from "../types";
 
 export interface ExtractedTheme {
   /** Raw CSS variable -> hex color map from DEFAULT_THEME */

package/scripts/migrate/phase-analyze.ts

@@ -5,11 +5,11 @@ import type {
   FileRecord,
   MigrationContext,
   Platform,
-} from "./types.ts";
-import { log, logPhase } from "./types.ts";
-import { extractSectionMetadata } from "./analyzers/section-metadata.ts";
-import { classifyIslands } from "./analyzers/island-classifier.ts";
-import { inventoryLoaders } from "./analyzers/loader-inventory.ts";
+} from "./types";
+import { log, logPhase } from "./types";
+import { extractSectionMetadata } from "./analyzers/section-metadata";
+import { classifyIslands } from "./analyzers/island-classifier";
+import { inventoryLoaders } from "./analyzers/loader-inventory";
 
 const PATTERN_DETECTORS: Array<[DetectedPattern, RegExp]> = [
   ["preact-hooks", /from\s+["']preact\/hooks["']/],
@@ -390,7 +390,7 @@ function scanDir(
 
     let content = "";
     let patterns: DetectedPattern[] = [];
-    let reExport = { is: false, target: undefined as string | undefined };
+    let reExport: { is: boolean; target?: string } = { is: false };
 
     if (isCode) {
       content = fs.readFileSync(fullPath, "utf-8");

package/scripts/migrate/phase-cleanup.test.ts

@@ -0,0 +1,141 @@
+import * as fs from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+import { afterEach, beforeEach, describe, expect, it } from "vitest";
+import { writeImportedLibShims } from "./phase-cleanup";
+import type { MigrationContext } from "./types";
+
+/**
+ * Build a minimal `MigrationContext` for integration tests of
+ * `writeImportedLibShims`. Only the fields that function reads are
+ * non-default; everything else is a placeholder with the right shape.
+ */
+function makeCtx(sourceDir: string, dryRun = false): MigrationContext {
+  return {
+    sourceDir,
+    siteName: "test-site",
+    platform: "vtex",
+    vtexAccount: null,
+    gtmId: null,
+    importMap: {},
+    discoveredNpmDeps: {},
+    themeColors: {},
+    fontFamily: null,
+    files: [],
+    sectionMetas: [],
+    islandClassifications: [],
+    islandWrapperTargets: new Map(),
+    loaderInventory: [],
+    scaffoldedFiles: [],
+    transformedFiles: [],
+    deletedFiles: [],
+    movedFiles: [],
+    manualReviewItems: [],
+    frameworkFindings: [],
+    dryRun,
+    verbose: false,
+  };
+}
+
+describe("writeImportedLibShims (integration)", () => {
+  let tmpDir: string;
+
+  beforeEach(() => {
+    tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), "lazy-shim-test-"));
+    fs.mkdirSync(path.join(tmpDir, "src", "loaders"), { recursive: true });
+  });
+
+  afterEach(() => {
+    fs.rmSync(tmpDir, { recursive: true, force: true });
+  });
+
+  it("writes nothing when no ~/lib imports are found", () => {
+    fs.writeFileSync(
+      path.join(tmpDir, "src", "loaders", "products.ts"),
+      `import { something } from "@decocms/apps/vtex";\nexport const x = 1;\n`,
+    );
+
+    writeImportedLibShims(makeCtx(tmpDir));
+
+    expect(fs.existsSync(path.join(tmpDir, "src", "lib"))).toBe(false);
+  });
+
+  it("writes only the shim files matching imports actually present in src/", () => {
+    fs.writeFileSync(
+      path.join(tmpDir, "src", "loaders", "search.ts"),
+      `import { getSegmentFromBag } from "~/lib/vtex-segment";\n` +
+        `import { toFilterSearchString } from "~/lib/filter-navigate";\n`,
+    );
+
+    writeImportedLibShims(makeCtx(tmpDir));
+
+    const libDir = path.join(tmpDir, "src", "lib");
+    expect(fs.existsSync(libDir)).toBe(true);
+    const written = fs.readdirSync(libDir).sort();
+    expect(written).toEqual(["filter-navigate.ts", "vtex-segment.ts"]);
+  });
+
+  it("writes nothing in dry-run mode (but does not throw)", () => {
+    fs.writeFileSync(
+      path.join(tmpDir, "src", "loaders", "search.ts"),
+      `import { getSegmentFromBag } from "~/lib/vtex-segment";\n`,
+    );
+
+    writeImportedLibShims(makeCtx(tmpDir, /* dryRun */ true));
+
+    expect(fs.existsSync(path.join(tmpDir, "src", "lib"))).toBe(false);
+  });
+
+  it("strips trailing .ts from the import specifier when scanning", () => {
+    // Some Fresh sites use explicit .ts extensions in their imports.
+    fs.writeFileSync(
+      path.join(tmpDir, "src", "loaders", "search.ts"),
+      `import { fn } from "~/lib/vtex-transform.ts";\n`,
+    );
+
+    writeImportedLibShims(makeCtx(tmpDir));
+
+    expect(
+      fs.existsSync(path.join(tmpDir, "src", "lib", "vtex-transform.ts")),
+    ).toBe(true);
+  });
+
+  it("ignores imports inside the lib dir itself (no self-amplification)", () => {
+    fs.mkdirSync(path.join(tmpDir, "src", "lib"));
+    fs.writeFileSync(
+      path.join(tmpDir, "src", "lib", "existing.ts"),
+      `import { x } from "~/lib/should-not-be-generated";\nexport const y = 1;\n`,
+    );
+
+    writeImportedLibShims(makeCtx(tmpDir));
+
+    // Only the existing file should remain; nothing new generated.
+    const files = fs.readdirSync(path.join(tmpDir, "src", "lib"));
+    expect(files).toEqual(["existing.ts"]);
+  });
+
+  it("scans .tsx files too, not just .ts", () => {
+    fs.mkdirSync(path.join(tmpDir, "src", "components"), { recursive: true });
+    fs.writeFileSync(
+      path.join(tmpDir, "src", "components", "Filter.tsx"),
+      `import { toFilterSearchString } from "~/lib/filter-navigate";\n` +
+        `export const C = () => null;\n`,
+    );
+
+    writeImportedLibShims(makeCtx(tmpDir));
+
+    expect(
+      fs.existsSync(path.join(tmpDir, "src", "lib", "filter-navigate.ts")),
+    ).toBe(true);
+  });
+
+  it("does nothing when src/ does not exist", () => {
+    const empty = fs.mkdtempSync(path.join(os.tmpdir(), "no-src-"));
+    try {
+      writeImportedLibShims(makeCtx(empty));
+      expect(fs.readdirSync(empty)).toEqual([]);
+    } finally {
+      fs.rmSync(empty, { recursive: true, force: true });
+    }
+  });
+});