@decocms/start 2.5.0 → 2.7.0

package/.agents/skills/deco-to-tanstack-migration/SKILL.md

@@ -136,7 +136,7 @@ See: `references/deco-framework/README.md`
 
 **Actions**:
 1. `from "apps/commerce/types.ts"` → `from "@decocms/apps/commerce/types"`
-2. `from "apps/admin/widgets.ts"` → `from "~/types/widgets"` (create local file)
+2. `from "apps/admin/widgets.ts"` → `from "@decocms/start/types/widgets"` (framework owns the string aliases — do **not** create a local `src/types/widgets.ts`)
 3. `from "apps/website/components/Image.tsx"` → `from "~/components/ui/Image"` (create local)
 4. SDK utilities: `~/sdk/useOffer` → `@decocms/apps/commerce/sdk/useOffer`, etc.
 

package/.agents/skills/deco-to-tanstack-migration/references/post-migration-cleanup.md

@@ -135,7 +135,38 @@ utility). Your runtime behavior gets MUCH better — segment cookies, IS
 cookies, VTEX session auth all start working again instead of being
 silently stubbed to `{}` / `null`.
 
-## 6. Search for orphan `TODO: move into framework` comments
+## 6. Drop `src/types/widgets.ts` — framework owns it
+
+Older migrations scaffold a local `src/types/widgets.ts` containing 8
+string-aliased widget types (`ImageWidget`, `HTMLWidget`, …). The
+framework now exports the same set (plus `TextArea`) at
+`@decocms/start/types/widgets`, and the schema generator detects the
+widgets via type-text matching, so the local file is purely
+duplicated boilerplate.
+
+```bash
+# Quick check
+rg -n "from ['\"]~/types/widgets['\"]" src/ | wc -l   # >0 → cleanup applies
+```
+
+Replace all imports in one pass:
+
+```bash
+# macOS / BSD sed: drop the empty quotes after -i
+rg -l "from ['\"]~/types/widgets['\"]" src/ \
+  | xargs sed -i '' "s|from ['\"]~/types/widgets['\"]|from \"@decocms/start/types/widgets\"|g"
+```
+
+Then delete the now-orphan local file:
+
+```bash
+rm src/types/widgets.ts
+```
+
+Confirm `tsc --noEmit` is still clean — the framework version is a
+strict superset of what the migration script generated.
+
+## 7. Search for orphan `TODO: move into framework` comments
 
 Real sites accumulate `TODO` comments like `// TODO: move into decoVitePlugin
 in next @decocms/start release`. These are roadmap items the framework
@@ -152,7 +183,7 @@ For each hit, decide:
 
 ## Verification checklist
 
-After completing 1-6:
+After completing 1-7:
 
 - [ ] `npm run typecheck` baseline matches pre-cleanup count (no new errors)
 - [ ] `npm run dev` starts and `/`, `/some-pdp/p`, `/s?q=foo` all render

package/.cursor/skills/deco-to-tanstack-migration/SKILL.md

@@ -218,7 +218,7 @@ See: `references/deco-framework/README.md`
 
 **Actions**:
 1. `from "apps/commerce/types.ts"` → `from "@decocms/apps/commerce/types"`
-2. `from "apps/admin/widgets.ts"` → `from "~/types/widgets"` (create local file with string aliases)
+2. `from "apps/admin/widgets.ts"` → `from "@decocms/start/types/widgets"` (framework owns the string aliases — `ImageWidget`, `HTMLWidget`, etc.; do **not** create a local `src/types/widgets.ts`)
 3. `from "apps/website/components/Image.tsx"` → `from "~/components/ui/Image"` (create local components)
 4. SDK utilities: `~/sdk/useOffer` → `@decocms/apps/commerce/sdk/useOffer`, `~/sdk/format` → `@decocms/apps/commerce/sdk/formatPrice`, etc.
 

package/.cursor/skills/deco-to-tanstack-migration/references/post-migration-cleanup.md

@@ -135,7 +135,38 @@ utility). Your runtime behavior gets MUCH better — segment cookies, IS
 cookies, VTEX session auth all start working again instead of being
 silently stubbed to `{}` / `null`.
 
-## 6. Search for orphan `TODO: move into framework` comments
+## 6. Drop `src/types/widgets.ts` — framework owns it
+
+Older migrations scaffold a local `src/types/widgets.ts` containing 8
+string-aliased widget types (`ImageWidget`, `HTMLWidget`, …). The
+framework now exports the same set (plus `TextArea`) at
+`@decocms/start/types/widgets`, and the schema generator detects the
+widgets via type-text matching, so the local file is purely
+duplicated boilerplate.
+
+```bash
+# Quick check
+rg -n "from ['\"]~/types/widgets['\"]" src/ | wc -l   # >0 → cleanup applies
+```
+
+Replace all imports in one pass:
+
+```bash
+# macOS / BSD sed: drop the empty quotes after -i
+rg -l "from ['\"]~/types/widgets['\"]" src/ \
+  | xargs sed -i '' "s|from ['\"]~/types/widgets['\"]|from \"@decocms/start/types/widgets\"|g"
+```
+
+Then delete the now-orphan local file:
+
+```bash
+rm src/types/widgets.ts
+```
+
+Confirm `tsc --noEmit` is still clean — the framework version is a
+strict superset of what the migration script generated.
+
+## 7. Search for orphan `TODO: move into framework` comments
 
 Real sites accumulate `TODO` comments like `// TODO: move into decoVitePlugin
 in next @decocms/start release`. These are roadmap items the framework
@@ -152,7 +183,7 @@ For each hit, decide:
 
 ## Verification checklist
 
-After completing 1-6:
+After completing 1-7:
 
 - [ ] `npm run typecheck` baseline matches pre-cleanup count (no new errors)
 - [ ] `npm run dev` starts and `/`, `/some-pdp/p`, `/s?q=foo` all render

package/package.json

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

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 });
+    }
+  });
+});

package/scripts/migrate/phase-cleanup.ts

@@ -2,6 +2,10 @@ import * as fs from "node:fs";
 import * as path from "node:path";
 import type { MigrationContext } from "./types";
 import { log, logPhase } from "./types";
+import {
+  LIB_TEMPLATES,
+  selectImportedLibTemplates,
+} from "./templates/lib-utils";
 
 /** Directories to remove entirely after migration */
 const DIRS_TO_DELETE = [
@@ -1479,7 +1483,106 @@ export function cleanup(ctx: MigrationContext): void {
   console.log("  Fixing Worker-incompatible APIs...");
   fixWorkerIncompatibleApis(ctx);
 
+  // 14. LAZY: write only the src/lib/* shim files that the migrated
+  //     codebase actually imports. Run after every previous step so we
+  //     observe the final import graph (transforms + cleanup rewrites
+  //     + inline-stub hoisting all settled).
+  console.log("  Writing src/lib/* shims (lazy)...");
+  writeImportedLibShims(ctx);
+
   console.log(
     `  Deleted ${ctx.deletedFiles.length} files/dirs, moved ${ctx.movedFiles.length} files`,
   );
 }
+
+/**
+ * Walk `src/**\/*.{ts,tsx}` looking for `from "~/lib/<name>"` imports.
+ * For each unique `<name>` that has a registered template in
+ * `LIB_TEMPLATES`, write `src/lib/<name>.ts` with the template content.
+ *
+ * Sites that import none of the shims end up with no `src/lib/` directory
+ * at all, instead of 11 dead files.
+ *
+ * Exported (rather than file-local) for unit testability — see
+ * `phase-cleanup.test.ts`.
+ */
+export function writeImportedLibShims(ctx: MigrationContext): void {
+  const srcRoot = path.join(ctx.sourceDir, "src");
+  if (!fs.existsSync(srcRoot)) return;
+
+  const importedSpecifiers = new Set<string>();
+  // Match `from "~/lib/<name>"` or `from '~/lib/<name>'`. We don't care
+  // about default vs named imports here — only the path matters.
+  const importRe = /from\s+["']~\/lib\/([^"']+?)(?:\.ts)?["']/g;
+
+  /** Recursively scan a directory for .ts/.tsx files and collect specifiers. */
+  const walk = (dir: string) => {
+    for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+      const full = path.join(dir, entry.name);
+      if (entry.isDirectory()) {
+        // Skip the lib dir itself so we don't count internal cross-refs
+        // when we later add them.
+        if (full === path.join(srcRoot, "lib")) continue;
+        walk(full);
+        continue;
+      }
+      if (!entry.isFile()) continue;
+      if (!/\.(ts|tsx)$/.test(entry.name)) continue;
+      const content = fs.readFileSync(full, "utf-8");
+      let m: RegExpExecArray | null;
+      while ((m = importRe.exec(content)) !== null) {
+        importedSpecifiers.add(m[1]);
+      }
+    }
+  };
+  walk(srcRoot);
+
+  if (importedSpecifiers.size === 0) {
+    log(ctx, "  No ~/lib/* imports detected — no shims written.");
+    return;
+  }
+
+  const known = new Set(
+    Object.keys(LIB_TEMPLATES).map((k) =>
+      k.replace(/^src\/lib\//, "").replace(/\.ts$/, ""),
+    ),
+  );
+  const unknown: string[] = [];
+  for (const spec of importedSpecifiers) {
+    if (!known.has(spec)) unknown.push(spec);
+  }
+  if (unknown.length > 0) {
+    log(
+      ctx,
+      `  Warning: ~/lib/{${unknown.join(", ")}} imported but no template registered. ` +
+        `Write the file by hand or add a template to scripts/migrate/templates/lib-utils.ts.`,
+    );
+  }
+
+  const toWrite = selectImportedLibTemplates(importedSpecifiers);
+  if (Object.keys(toWrite).length === 0) return;
+
+  if (ctx.dryRun) {
+    for (const relPath of Object.keys(toWrite)) {
+      log(ctx, `  [DRY] Would write: ${relPath}`);
+    }
+    return;
+  }
+
+  const libDir = path.join(srcRoot, "lib");
+  if (!fs.existsSync(libDir)) {
+    fs.mkdirSync(libDir, { recursive: true });
+  }
+
+  for (const [relPath, content] of Object.entries(toWrite)) {
+    const fullPath = path.join(ctx.sourceDir, relPath);
+    fs.writeFileSync(fullPath, content, "utf-8");
+    log(ctx, `  Wrote: ${relPath}`);
+  }
+
+  log(
+    ctx,
+    `  Generated ${Object.keys(toWrite).length} src/lib/* shim(s) ` +
+      `(out of ${Object.keys(LIB_TEMPLATES).length} available templates).`,
+  );
+}

package/scripts/migrate/phase-scaffold.ts

@@ -18,7 +18,9 @@ import { generateCommerceLoaders } from "./templates/commerce-loaders";
 import { generateSectionLoaders } from "./templates/section-loaders";
 import { generateCacheConfig } from "./templates/cache-config";
 import { generateSdkFiles } from "./templates/sdk-gen";
-import { generateLibUtils } from "./templates/lib-utils";
+// `lib-utils` is imported lazily — see end of phase-cleanup. Eager
+// generation of all 11 shims left every site with dead code that had
+// to be cleaned up by hand.
 import { extractTheme } from "./analyzers/theme-extractor";
 
 function writeFile(ctx: MigrationContext, relPath: string, content: string) {
@@ -108,8 +110,10 @@ export function scaffold(ctx: MigrationContext): void {
   writeFile(ctx, "src/sdk/logger.ts", generateLoggerStub());
   writeMultiFile(ctx, generateSdkFiles(ctx));
 
-  // VTEX utility wrappers (signature-compatible stubs for custom loaders)
-  writeMultiFile(ctx, generateLibUtils(ctx));
+  // VTEX utility wrappers (signature-compatible stubs) are no longer
+  // generated eagerly here. They're written lazily at end of phase-cleanup,
+  // after all import rewrites have run, so that we only emit shims that
+  // some file actually imports. See `writeImportedLibShims` in phase-cleanup.
 
   // Replace Context-based useDevice with SSR-safe useSyncExternalStore version.
   // @decocms/start shell-renders sections in a separate React root without

package/scripts/migrate/phase-verify.ts

@@ -30,7 +30,9 @@ const REQUIRED_FILES = [
   "src/hooks/useCart.ts",
   "src/hooks/useUser.ts",
   "src/hooks/useWishlist.ts",
-  "src/types/widgets.ts",
+  // src/types/widgets.ts intentionally omitted — provided by the
+  // framework at `@decocms/start/types/widgets`; sites no longer
+  // shadow the file locally.
   "src/types/deco.ts",
   "src/types/commerce-app.ts",
   "src/components/ui/Image.tsx",
@@ -442,7 +444,8 @@ const checks: Check[] = [
     severity: "warning",
     fn: (ctx) => {
       const typeFiles = [
-        "src/types/widgets.ts",
+        // widgets.ts is provided by @decocms/start/types/widgets, not
+        // scaffolded locally.
         "src/types/deco.ts",
         "src/types/commerce-app.ts",
       ];

package/scripts/migrate/templates/lib-utils.test.ts

@@ -0,0 +1,91 @@
+import { describe, expect, it } from "vitest";
+import {
+  LIB_TEMPLATES,
+  selectImportedLibTemplates,
+} from "./lib-utils";
+
+describe("LIB_TEMPLATES registry", () => {
+  it("has entries", () => {
+    expect(Object.keys(LIB_TEMPLATES).length).toBeGreaterThan(0);
+  });
+
+  it("uses src/lib/<name>.ts keys (relative paths the writer expects)", () => {
+    for (const key of Object.keys(LIB_TEMPLATES)) {
+      expect(key).toMatch(/^src\/lib\/[a-z][a-z0-9-]*\.ts$/);
+    }
+  });
+
+  it("has non-empty contents for every entry", () => {
+    for (const [key, value] of Object.entries(LIB_TEMPLATES)) {
+      expect(value, `${key} should have content`).toBeTruthy();
+      expect(value.length, `${key} length`).toBeGreaterThan(20);
+    }
+  });
+
+  it("has unique keys (no shadowing)", () => {
+    const keys = Object.keys(LIB_TEMPLATES);
+    const set = new Set(keys);
+    expect(set.size).toBe(keys.length);
+  });
+});
+
+describe("selectImportedLibTemplates()", () => {
+  it("returns empty record when no specifiers are imported", () => {
+    expect(selectImportedLibTemplates(new Set())).toEqual({});
+  });
+
+  it("returns only the templates whose specifier is in the set", () => {
+    const result = selectImportedLibTemplates(new Set(["vtex-segment"]));
+    expect(Object.keys(result)).toEqual(["src/lib/vtex-segment.ts"]);
+    expect(result["src/lib/vtex-segment.ts"]).toBe(LIB_TEMPLATES["src/lib/vtex-segment.ts"]);
+  });
+
+  it("returns multiple templates when multiple specifiers are imported", () => {
+    const result = selectImportedLibTemplates(
+      new Set(["vtex-segment", "vtex-transform", "filter-navigate"]),
+    );
+    const keys = Object.keys(result).sort();
+    expect(keys).toEqual([
+      "src/lib/filter-navigate.ts",
+      "src/lib/vtex-segment.ts",
+      "src/lib/vtex-transform.ts",
+    ]);
+  });
+
+  it("ignores unknown specifiers without throwing", () => {
+    const result = selectImportedLibTemplates(
+      new Set(["vtex-segment", "this-template-does-not-exist"]),
+    );
+    expect(Object.keys(result)).toEqual(["src/lib/vtex-segment.ts"]);
+  });
+
+  it("does not mutate LIB_TEMPLATES (returns a fresh object)", () => {
+    const before = JSON.stringify(LIB_TEMPLATES);
+    const result = selectImportedLibTemplates(new Set(["vtex-segment"]));
+    result["src/lib/vtex-segment.ts"] = "// HIJACKED";
+    expect(JSON.stringify(LIB_TEMPLATES)).toBe(before);
+  });
+
+  it("covers every well-known migration target the writer might emit", () => {
+    // Sanity check: the names that `transforms/imports.ts` rewrites to
+    // and that phase-cleanup hoists for inline-stub injection MUST all
+    // have templates registered, otherwise migrated sites get import
+    // errors with no warning.
+    const expectedSpecifiers = [
+      "vtex-transform",
+      "vtex-intelligent-search",
+      "vtex-segment",
+      "vtex-fetch",
+      "vtex-id",
+      "vtex-client",
+      "fetch-utils",
+      "http-utils",
+      "graphql-utils",
+      "filter-navigate",
+    ];
+    for (const spec of expectedSpecifiers) {
+      const key = `src/lib/${spec}.ts`;
+      expect(LIB_TEMPLATES, `expected template for ${key}`).toHaveProperty(key);
+    }
+  });
+});

package/scripts/migrate/templates/lib-utils.ts

@@ -1,25 +1,41 @@
-import type { MigrationContext } from "../types";
+/**
+ * Templates for src/lib/ utility wrappers that bridge signature gaps
+ * between deco-cx/apps (old stack) and @decocms/apps-start (new stack).
+ *
+ * These are written *lazily*: only shims that are actually imported by
+ * the migrated codebase get generated. See `selectImportedLibTemplates`.
+ *
+ * Lazy generation matters because:
+ * - Most sites end up importing zero of these (apps-start exports
+ *   direct equivalents for most VTEX utilities — see migrate#107).
+ * - Eager generation creates dead `src/lib/*.ts` files that every site
+ *   then has to clean up by hand (see baggagio-tanstack#7, ~235 LOC).
+ *
+ * Registry shape: `"src/lib/<name>.ts"` → file contents.
+ */
+export const LIB_TEMPLATES: Record<string, string> = {
+  // Filled in below after the const declarations to keep the registry
+  // and template literals colocated. See trailing assignment.
+};
 
 /**
- * Generates src/lib/ utility wrappers that provide signature-compatible
- * stubs for VTEX utilities. The old stack (deco-cx/apps) exports functions
- * with different signatures than @decocms/apps-start, and some types
- * (VTEXCommerceStable, LabelledFuzzy) don't exist at all. These wrappers
- * bridge the gap so custom loaders continue to compile and run.
+ * Given the set of `~/lib/X` imports actually present in the migrated
+ * codebase, return the subset of templates to write.
+ *
+ * `importedSpecifiers` are the `X` parts (without `~/lib/` prefix and
+ * without `.ts` extension), e.g. `"vtex-transform"`, `"http-utils"`.
  */
-export function generateLibUtils(_ctx: MigrationContext): Record<string, string> {
-  return {
-    "src/lib/vtex-transform.ts": LIB_VTEX_TRANSFORM,
-    "src/lib/vtex-intelligent-search.ts": LIB_VTEX_INTELLIGENT_SEARCH,
-    "src/lib/vtex-segment.ts": LIB_VTEX_SEGMENT,
-    "src/lib/http-utils.ts": LIB_HTTP_UTILS,
-    "src/lib/vtex-client.ts": LIB_VTEX_CLIENT,
-    "src/lib/fetch-utils.ts": LIB_FETCH_UTILS,
-    "src/lib/vtex-fetch.ts": LIB_VTEX_FETCH,
-    "src/lib/vtex-id.ts": LIB_VTEX_ID,
-    "src/lib/graphql-utils.ts": LIB_GRAPHQL_UTILS,
-    "src/lib/filter-navigate.ts": LIB_FILTER_NAVIGATE,
-  };
+export function selectImportedLibTemplates(
+  importedSpecifiers: Set<string>,
+): Record<string, string> {
+  const out: Record<string, string> = {};
+  for (const spec of importedSpecifiers) {
+    const key = `src/lib/${spec}.ts`;
+    if (key in LIB_TEMPLATES) {
+      out[key] = LIB_TEMPLATES[key];
+    }
+  }
+  return out;
 }
 
 const LIB_VTEX_TRANSFORM = `import type { Product } from "@decocms/apps/commerce/types";
@@ -253,3 +269,19 @@ export function toFilterSearchString(filterUrl: string): string {
   return clean ? \`?\${clean}\` : "";
 }
 `;
+
+// Populate the registry now that all template literals are declared.
+// Keys must match the relative path the migration script writes; values
+// are the file contents.
+Object.assign(LIB_TEMPLATES, {
+  "src/lib/vtex-transform.ts": LIB_VTEX_TRANSFORM,
+  "src/lib/vtex-intelligent-search.ts": LIB_VTEX_INTELLIGENT_SEARCH,
+  "src/lib/vtex-segment.ts": LIB_VTEX_SEGMENT,
+  "src/lib/http-utils.ts": LIB_HTTP_UTILS,
+  "src/lib/vtex-client.ts": LIB_VTEX_CLIENT,
+  "src/lib/fetch-utils.ts": LIB_FETCH_UTILS,
+  "src/lib/vtex-fetch.ts": LIB_VTEX_FETCH,
+  "src/lib/vtex-id.ts": LIB_VTEX_ID,
+  "src/lib/graphql-utils.ts": LIB_GRAPHQL_UTILS,
+  "src/lib/filter-navigate.ts": LIB_FILTER_NAVIGATE,
+});

package/scripts/migrate/templates/types-gen.ts

@@ -3,15 +3,12 @@ import type { MigrationContext } from "../types";
 export function generateTypeFiles(ctx: MigrationContext): Record<string, string> {
   const files: Record<string, string> = {};
 
-  files["src/types/widgets.ts"] = `export type ImageWidget = string;
-export type HTMLWidget = string;
-export type VideoWidget = string;
-export type TextWidget = string;
-export type RichText = string;
-export type Secret = string;
-export type Color = string;
-export type ButtonWidget = string;
-`;
+  // src/types/widgets.ts is no longer generated — the framework owns these
+  // string aliases (`ImageWidget`, `HTMLWidget`, …) at
+  // `@decocms/start/types/widgets`, and `transforms/imports.ts` rewrites
+  // `apps/admin/widgets.ts` directly to that path. Schema generation
+  // works the same way: the generator matches by type *text*, not module
+  // identity (see scripts/generate-schema.ts:WIDGET_TYPE_FORMATS).
 
   files["src/types/deco.ts"] = `export type SectionProps<T extends (...args: any[]) => any> = Awaited<
   ReturnType<T>

package/scripts/migrate/transforms/imports.ts

@@ -29,7 +29,12 @@ const IMPORT_RULES: Array<[RegExp, string | null]> = [
   [/^"@deco\/deco"$/, `"~/types/deco"`],
 
   // Apps — widgets & components
-  [/^"apps\/admin\/widgets\.ts"$/, `"~/types/widgets"`],
+  // Widget aliases (ImageWidget, HTMLWidget, ...) are framework-owned —
+  // every site has the same type set, and the schema generator detects
+  // them via type-text matching, not module identity. Re-export from
+  // @decocms/start/types/widgets so we don't keep a duplicated 8-line
+  // file in every site.
+  [/^"apps\/admin\/widgets\.ts"$/, `"@decocms/start/types/widgets"`],
   [/^"apps\/website\/components\/Image\.tsx"$/, `"~/components/ui/Image"`],
   [/^"apps\/website\/components\/Picture\.tsx"$/, `"~/components/ui/Picture"`],
   [/^"apps\/website\/components\/Video\.tsx"$/, `"~/components/ui/Video"`],

package/vitest.config.ts

@@ -1,9 +1,19 @@
 import { defineConfig } from "vitest/config";
 
+// Two test suites, one runner:
+// - `src/**` runs in jsdom (React rendering, hooks, browser globals).
+// - `scripts/**` runs in node (filesystem, migration script logic).
+// vitest applies env-per-file via the `environmentMatchGlobs` map.
 export default defineConfig({
   test: {
     environment: "jsdom",
-    include: ["src/**/*.test.{ts,tsx}"],
+    environmentMatchGlobs: [
+      ["scripts/**", "node"],
+    ],
+    include: [
+      "src/**/*.test.{ts,tsx}",
+      "scripts/**/*.test.ts",
+    ],
     globals: true,
   },
 });