npm - @decocms/start - Versions diffs - 0.19.0 - Mend

@decocms/start 0.19.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (185) hide show

package/.cursor/skills/deco-api-call-dedup/SKILL.md +443 -0
package/.cursor/skills/deco-apps-architecture/SKILL.md +255 -0
package/.cursor/skills/deco-apps-architecture/app-pattern.md +288 -0
package/.cursor/skills/deco-apps-architecture/commerce-types.md +239 -0
package/.cursor/skills/deco-apps-architecture/new-app-guide.md +268 -0
package/.cursor/skills/deco-apps-architecture/scripts-codegen.md +148 -0
package/.cursor/skills/deco-apps-architecture/shared-utils.md +181 -0
package/.cursor/skills/deco-apps-architecture/vtex-deep-structure.md +253 -0
package/.cursor/skills/deco-apps-architecture/website-app.md +169 -0
package/.cursor/skills/deco-apps-vtex-porting/SKILL.md +189 -0
package/.cursor/skills/deco-apps-vtex-porting/adaptation-patterns.md +335 -0
package/.cursor/skills/deco-apps-vtex-porting/commerce-porting.md +155 -0
package/.cursor/skills/deco-apps-vtex-porting/cookie-auth-patterns.md +148 -0
package/.cursor/skills/deco-apps-vtex-porting/structure-map.md +234 -0
package/.cursor/skills/deco-apps-vtex-porting/transform-mapping.md +99 -0
package/.cursor/skills/deco-apps-vtex-porting/website-porting.md +194 -0
package/.cursor/skills/deco-apps-vtex-review/SKILL.md +234 -0
package/.cursor/skills/deco-async-rendering-architecture/SKILL.md +270 -0
package/.cursor/skills/deco-async-rendering-site-guide/SKILL.md +417 -0
package/.cursor/skills/deco-cms-layout-caching/SKILL.md +293 -0
package/.cursor/skills/deco-cms-route-config/SKILL.md +388 -0
package/.cursor/skills/deco-core-architecture/SKILL.md +185 -0
package/.cursor/skills/deco-core-architecture/blocks.md +196 -0
package/.cursor/skills/deco-core-architecture/deco-vs-deco-start.md +191 -0
package/.cursor/skills/deco-core-architecture/engine.md +220 -0
package/.cursor/skills/deco-core-architecture/hooks-components.md +157 -0
package/.cursor/skills/deco-core-architecture/plugins-clients.md +136 -0
package/.cursor/skills/deco-core-architecture/runtime.md +116 -0
package/.cursor/skills/deco-core-architecture/site-usage.md +165 -0
package/.cursor/skills/deco-e2e-testing/SKILL.md +372 -0
package/.cursor/skills/deco-e2e-testing/discovery.md +337 -0
package/.cursor/skills/deco-e2e-testing/scripts/scaffold.sh +81 -0
package/.cursor/skills/deco-e2e-testing/selectors.md +175 -0
package/.cursor/skills/deco-e2e-testing/templates/package.json +18 -0
package/.cursor/skills/deco-e2e-testing/templates/playwright.config.ts +65 -0
package/.cursor/skills/deco-e2e-testing/templates/scripts/baseline.ts +279 -0
package/.cursor/skills/deco-e2e-testing/templates/scripts/run-e2e.ts +194 -0
package/.cursor/skills/deco-e2e-testing/templates/specs/ecommerce-flow.spec.ts +612 -0
package/.cursor/skills/deco-e2e-testing/templates/tsconfig.json +12 -0
package/.cursor/skills/deco-e2e-testing/templates/utils/metrics-collector.ts +918 -0
package/.cursor/skills/deco-e2e-testing/troubleshooting.md +602 -0
package/.cursor/skills/deco-edge-caching/SKILL.md +316 -0
package/.cursor/skills/deco-full-analysis/SKILL.md +898 -0
package/.cursor/skills/deco-full-analysis/checklists/asset-optimization.md +251 -0
package/.cursor/skills/deco-full-analysis/checklists/bug-fix.md +189 -0
package/.cursor/skills/deco-full-analysis/checklists/cache-strategy.md +144 -0
package/.cursor/skills/deco-full-analysis/checklists/dependency-update.md +150 -0
package/.cursor/skills/deco-full-analysis/checklists/hydration-fix.md +191 -0
package/.cursor/skills/deco-full-analysis/checklists/image-optimization.md +180 -0
package/.cursor/skills/deco-full-analysis/checklists/loader-optimization.md +165 -0
package/.cursor/skills/deco-full-analysis/checklists/seo-fix.md +183 -0
package/.cursor/skills/deco-full-analysis/checklists/site-cleanup.md +281 -0
package/.cursor/skills/deco-full-analysis/discovery.md +548 -0
package/.cursor/skills/deco-incident-debugging/SKILL.md +378 -0
package/.cursor/skills/deco-incident-debugging/headless-mode.md +510 -0
package/.cursor/skills/deco-incident-debugging/learnings-index.md +227 -0
package/.cursor/skills/deco-incident-debugging/triage-workflow.md +312 -0
package/.cursor/skills/deco-islands-migration/SKILL.md +251 -0
package/.cursor/skills/deco-loader-n-plus-1-detector/SKILL.md +275 -0
package/.cursor/skills/deco-performance-audit/SKILL.md +530 -0
package/.cursor/skills/deco-performance-audit/tools-reference.md +428 -0
package/.cursor/skills/deco-performance-audit/workflow.md +457 -0
package/.cursor/skills/deco-server-functions-invoke/SKILL.md +92 -0
package/.cursor/skills/deco-server-functions-invoke/architecture.md +166 -0
package/.cursor/skills/deco-server-functions-invoke/generator.md +122 -0
package/.cursor/skills/deco-server-functions-invoke/problem.md +98 -0
package/.cursor/skills/deco-server-functions-invoke/troubleshooting.md +110 -0
package/.cursor/skills/deco-site-deployment/SKILL.md +396 -0
package/.cursor/skills/deco-site-memory-debugging/SKILL.md +121 -0
package/.cursor/skills/deco-site-memory-debugging/cdp-connection.md +222 -0
package/.cursor/skills/deco-site-memory-debugging/memory-analysis.md +362 -0
package/.cursor/skills/deco-site-patterns/SKILL.md +124 -0
package/.cursor/skills/deco-site-patterns/app-composition.md +337 -0
package/.cursor/skills/deco-site-patterns/client-patterns.md +341 -0
package/.cursor/skills/deco-site-patterns/cms-wiring.md +230 -0
package/.cursor/skills/deco-site-patterns/section-patterns.md +340 -0
package/.cursor/skills/deco-site-scaling-tuning/SKILL.md +240 -0
package/.cursor/skills/deco-site-scaling-tuning/analysis-scripts.md +267 -0
package/.cursor/skills/deco-start-architecture/SKILL.md +218 -0
package/.cursor/skills/deco-start-architecture/admin-protocol.md +156 -0
package/.cursor/skills/deco-start-architecture/cms-resolution.md +201 -0
package/.cursor/skills/deco-start-architecture/code-quality.md +158 -0
package/.cursor/skills/deco-start-architecture/gap-analysis.md +129 -0
package/.cursor/skills/deco-start-architecture/sdk-utilities.md +197 -0
package/.cursor/skills/deco-start-architecture/worker-entry-caching.md +154 -0
package/.cursor/skills/deco-startup-analysis/SKILL.md +248 -0
package/.cursor/skills/deco-storefront-test-checklist/SKILL.md +369 -0
package/.cursor/skills/deco-tanstack-hydration-fixes/SKILL.md +468 -0
package/.cursor/skills/deco-tanstack-navigation/SKILL.md +681 -0
package/.cursor/skills/deco-tanstack-search/SKILL.md +411 -0
package/.cursor/skills/deco-tanstack-storefront-patterns/SKILL.md +1013 -0
package/.cursor/skills/deco-to-tanstack-migration/SKILL.md +518 -0
package/.cursor/skills/deco-to-tanstack-migration/references/codemod-commands.md +174 -0
package/.cursor/skills/deco-to-tanstack-migration/references/commerce/README.md +78 -0
package/.cursor/skills/deco-to-tanstack-migration/references/deco-framework/README.md +128 -0
package/.cursor/skills/deco-to-tanstack-migration/references/gotchas.md +719 -0
package/.cursor/skills/deco-to-tanstack-migration/references/imports/README.md +70 -0
package/.cursor/skills/deco-to-tanstack-migration/references/platform-hooks/README.md +154 -0
package/.cursor/skills/deco-to-tanstack-migration/references/signals/README.md +220 -0
package/.cursor/skills/deco-to-tanstack-migration/references/vite-config/README.md +78 -0
package/.cursor/skills/deco-to-tanstack-migration/templates/package-json.md +55 -0
package/.cursor/skills/deco-to-tanstack-migration/templates/root-route.md +110 -0
package/.cursor/skills/deco-to-tanstack-migration/templates/router.md +96 -0
package/.cursor/skills/deco-to-tanstack-migration/templates/setup-ts.md +167 -0
package/.cursor/skills/deco-to-tanstack-migration/templates/vite-config.md +122 -0
package/.cursor/skills/deco-to-tanstack-migration/templates/worker-entry.md +67 -0
package/.cursor/skills/deco-typescript-fixes/SKILL.md +178 -0
package/.cursor/skills/deco-typescript-fixes/common-fixes.md +330 -0
package/.cursor/skills/deco-typescript-fixes/strategy.md +148 -0
package/.cursor/skills/deco-variant-selection-perf/SKILL.md +272 -0
package/.cursor/skills/deco-vtex-fetch-cache/SKILL.md +225 -0
package/.cursor/skills/find-skills/SKILL.md +133 -0
package/.cursor/skills/incident-report/SKILL.md +179 -0
package/.cursor/skills/incident-report/references/5-whys.md +75 -0
package/.cursor/skills/incident-report/templates/client-report.md +187 -0
package/.cursor/skills/incident-report/templates/internal-report.md +206 -0
package/.cursor/skills/template-skill/SKILL.md +38 -0
package/.github/workflows/release.yml +32 -0
package/.releaserc.json +25 -0
package/CLAUDE.md +135 -0
package/GAP_ANALYSIS.md +224 -0
package/GAP_ANALYSIS_V2.md +1013 -0
package/biome.json +39 -0
package/knip.json +5 -0
package/package.json +87 -0
package/scripts/generate-blocks.ts +69 -0
package/scripts/generate-invoke.ts +378 -0
package/scripts/generate-schema.ts +657 -0
package/src/admin/cors.ts +29 -0
package/src/admin/decofile.ts +72 -0
package/src/admin/index.ts +24 -0
package/src/admin/invoke.ts +163 -0
package/src/admin/liveControls.ts +29 -0
package/src/admin/meta.ts +70 -0
package/src/admin/render.ts +205 -0
package/src/admin/schema.ts +686 -0
package/src/admin/setup.ts +44 -0
package/src/cms/index.ts +59 -0
package/src/cms/loader.ts +180 -0
package/src/cms/registry.ts +162 -0
package/src/cms/resolve.ts +1005 -0
package/src/cms/sectionLoaders.ts +294 -0
package/src/hooks/DecoPageRenderer.tsx +444 -0
package/src/hooks/LazySection.tsx +109 -0
package/src/hooks/LiveControls.tsx +108 -0
package/src/hooks/SectionErrorFallback.tsx +85 -0
package/src/hooks/index.ts +8 -0
package/src/index.ts +5 -0
package/src/matchers/builtins.ts +184 -0
package/src/matchers/posthog.ts +154 -0
package/src/middleware/decoState.ts +55 -0
package/src/middleware/healthMetrics.ts +131 -0
package/src/middleware/index.ts +80 -0
package/src/middleware/liveness.ts +21 -0
package/src/middleware/observability.ts +205 -0
package/src/routes/adminRoutes.ts +83 -0
package/src/routes/cmsRoute.ts +302 -0
package/src/routes/components.tsx +34 -0
package/src/routes/index.ts +15 -0
package/src/sdk/analytics.ts +72 -0
package/src/sdk/cacheHeaders.ts +268 -0
package/src/sdk/cachedLoader.ts +206 -0
package/src/sdk/clx.ts +3 -0
package/src/sdk/cookie.ts +39 -0
package/src/sdk/createInvoke.ts +57 -0
package/src/sdk/csp.ts +59 -0
package/src/sdk/env.ts +27 -0
package/src/sdk/index.ts +63 -0
package/src/sdk/instrumentedFetch.ts +137 -0
package/src/sdk/invoke.ts +133 -0
package/src/sdk/mergeCacheControl.ts +150 -0
package/src/sdk/redirects.ts +217 -0
package/src/sdk/requestContext.ts +184 -0
package/src/sdk/serverTimings.ts +68 -0
package/src/sdk/signal.ts +41 -0
package/src/sdk/sitemap.ts +143 -0
package/src/sdk/urlUtils.ts +117 -0
package/src/sdk/useDevice.ts +82 -0
package/src/sdk/useId.ts +7 -0
package/src/sdk/useScript.ts +101 -0
package/src/sdk/workerEntry.ts +703 -0
package/src/sdk/wrapCaughtErrors.ts +107 -0
package/src/types/index.ts +39 -0
package/src/types/widgets.ts +13 -0
package/tsconfig.json +13 -0

package/.cursor/skills/deco-to-tanstack-migration/templates/router.md ADDED Viewed

@@ -0,0 +1,96 @@
+# router.tsx Template
+```typescript
+import { createRouter as createTanStackRouter } from "@tanstack/react-router";
+import { routeTree } from "./routeTree.gen";
+export function createRouter() {
+  const router = createTanStackRouter({
+    routeTree,
+    scrollRestoration: true,
+  });
+  // Scroll to top on forward navigation (PUSH/REPLACE), skip on back/forward (GO)
+  router.subscribe("onResolved", (evt) => {
+    if (evt.type === "GO") return;
+    window.scrollTo({ top: 0 });
+  });
+  return router;
+}
+declare module "@tanstack/react-router" {
+  interface Register {
+    router: ReturnType<typeof createRouter>;
+  }
+}
+```
+## Route Files
+### src/routes/index.tsx (Homepage)
+```typescript
+import { createFileRoute } from "@tanstack/react-router";
+import { cmsHomeRouteConfig } from "@decocms/start/routes";
+import { DecoPageRenderer } from "@decocms/start/hooks";
+import { loadDeferredSection } from "@decocms/start/routes/cmsRoute";
+const { loader, head } = cmsHomeRouteConfig({
+  defaultTitle: "My Store",
+});
+export const Route = createFileRoute("/")({
+  loader,
+  head,
+  component: HomePage,
+});
+function HomePage() {
+  const { resolvedSections, deferredSections, pagePath } = Route.useLoaderData();
+  return (
+    <DecoPageRenderer
+      sections={resolvedSections}
+      deferredSections={deferredSections}
+      pagePath={pagePath}
+      loadDeferredSectionFn={loadDeferredSection}
+    />
+  );
+}
+```
+### src/routes/$.tsx (Catch-All CMS Route)
+```typescript
+import { createFileRoute, notFound } from "@tanstack/react-router";
+import { cmsRouteConfig } from "@decocms/start/routes";
+import { DecoPageRenderer } from "@decocms/start/hooks";
+import { loadDeferredSection } from "@decocms/start/routes/cmsRoute";
+const { loader, head } = cmsRouteConfig({
+  siteName: "My Store",
+  ignoreSearchParams: ["skuId"],
+});
+export const Route = createFileRoute("/$")({
+  loader: async (ctx) => {
+    const data = await loader(ctx);
+    if (!data) throw notFound();
+    return data;
+  },
+  head,
+  component: CmsPage,
+});
+function CmsPage() {
+  const { resolvedSections, deferredSections, pagePath } = Route.useLoaderData();
+  return (
+    <DecoPageRenderer
+      sections={resolvedSections}
+      deferredSections={deferredSections}
+      pagePath={pagePath}
+      loadDeferredSectionFn={loadDeferredSection}
+    />
+  );
+}
+```

package/.cursor/skills/deco-to-tanstack-migration/templates/setup-ts.md ADDED Viewed

@@ -0,0 +1,167 @@
+# setup.ts Template
+Annotated template based on espacosmart-storefront (100+ sections, VTEX, async rendering).
+```typescript
+// ==========================================================================
+// 1. CMS BLOCKS & META
+// ==========================================================================
+import blocksJson from "./server/cms/blocks.gen.ts";
+import metaData from "./server/admin/meta.gen.json";
+import { setBlocks } from "@decocms/start/cms/loader";
+import { setMetaData, setInvokeLoaders, setRenderShell } from "@decocms/start/admin";
+import { registerSections, registerSectionsSync, setResolvedComponent } from "@decocms/start/cms/registry";
+import { registerSectionLoaders, registerLayoutSections } from "@decocms/start/cms/sectionLoaders";
+import { registerCommerceLoaders, setAsyncRenderingConfig, onBeforeResolve } from "@decocms/start/cms/resolve";
+import { createCachedLoader } from "@decocms/start/sdk/cachedLoader";
+import appCss from "./styles/app.css?url";
+// Load CMS blocks (pages, sections, configs) from generated JSON
+setBlocks(blocksJson);
+// Set admin schema for /live/_meta endpoint
+setMetaData(metaData);
+// Configure admin preview HTML shell
+setRenderShell({
+  css: appCss,
+  fonts: ["https://fonts.googleapis.com/css2?family=YourFont:wght@400;500;600;700&display=swap"],
+  theme: "light",       // data-theme="light" on <html> for DaisyUI
+  bodyClass: "bg-base-100 text-base-content",
+  lang: "pt-BR",
+});
+// ==========================================================================
+// 2. SECTION REGISTRATION
+// ==========================================================================
+// Critical sections — above-the-fold, bundled synchronously
+import HeaderSection from "./components/header/Header";
+import FooterSection from "./sections/Footer/Footer";
+const criticalSections: Record<string, any> = {
+  "site/sections/Header/Header.tsx": HeaderSection,
+  "site/sections/Footer/Footer.tsx": FooterSection,
+};
+// Register sync components for instant SSR (no Suspense boundary)
+for (const [key, mod] of Object.entries(criticalSections)) {
+  setResolvedComponent(key, mod.default || mod);
+}
+registerSectionsSync(criticalSections);
+// All sections — lazy-loaded via dynamic import
+registerSections({
+  "site/sections/Header/Header.tsx": () => import("./sections/Header/Header"),
+  "site/sections/Footer/Footer.tsx": () => import("./sections/Footer/Footer"),
+  "site/sections/Theme/Theme.tsx": () => import("./sections/Theme/Theme"),
+  // ... register ALL sections from src/sections/ here
+  // Pattern: "site/sections/Path/Name.tsx": () => import("./sections/Path/Name")
+});
+// ==========================================================================
+// 3. LAYOUT SECTIONS
+// ==========================================================================
+// Layout sections are always rendered eagerly (never lazy/deferred),
+// even if wrapped in Lazy.tsx in the CMS.
+registerLayoutSections([
+  "site/sections/Header/Header.tsx",
+  "site/sections/Footer/Footer.tsx",
+  "site/sections/Theme/Theme.tsx",
+  "site/sections/Social/WhatsApp.tsx",
+]);
+// ==========================================================================
+// 4. SECTION LOADERS
+// ==========================================================================
+// Section loaders enrich CMS props with server-side data (e.g., VTEX API calls).
+// Only needed for sections that export `const loader`.
+registerSectionLoaders({
+  "site/sections/Product/ProductShelf.tsx": (props: any, req: Request) =>
+    import("./components/product/ProductShelf").then((m) => m.loader(props, req)),
+  "site/sections/Product/SearchResult.tsx": (props: any, req: Request) =>
+    import("./components/search/SearchResult").then((m) => m.loader(props, req)),
+  // ... add for each section that has `export const loader`
+});
+// ==========================================================================
+// 5. COMMERCE LOADERS (VTEX)
+// ==========================================================================
+import { vtexProductList } from "@decocms/apps/vtex/loaders/productList";
+import { vtexProductDetailsPage } from "@decocms/apps/vtex/loaders/productDetailsPage";
+import { vtexProductListingPage } from "@decocms/apps/vtex/loaders/productListingPage";
+import { vtexSuggestions } from "@decocms/apps/vtex/loaders/suggestions";
+import { initVtexFromBlocks } from "@decocms/apps/vtex/setup";
+// SWR-cached commerce loaders — avoids re-fetching on every page navigation
+const cachedProductList = createCachedLoader("vtex/productList", vtexProductList, {
+  policy: "stale-while-revalidate", maxAge: 60_000,
+});
+const cachedPDP = createCachedLoader("vtex/pdp", vtexProductDetailsPage, {
+  policy: "stale-while-revalidate", maxAge: 30_000,
+});
+const cachedPLP = createCachedLoader("vtex/plp", vtexProductListingPage, {
+  policy: "stale-while-revalidate", maxAge: 60_000,
+});
+const cachedSuggestions = createCachedLoader("vtex/suggestions", vtexSuggestions, {
+  policy: "stale-while-revalidate", maxAge: 120_000,
+});
+// Map CMS __resolveType strings to actual loader functions
+registerCommerceLoaders({
+  "vtex/loaders/intelligentSearch/productList.ts": cachedProductList,
+  "vtex/loaders/intelligentSearch/productListingPage.ts": cachedPLP,
+  "vtex/loaders/intelligentSearch/productDetailsPage.ts": cachedPDP,
+  "vtex/loaders/intelligentSearch/suggestions.ts": cachedSuggestions,
+  // Add passthrough loaders for types that don't need caching:
+  // "vtex/loaders/config.ts": (props) => props,
+});
+// ==========================================================================
+// 6. VTEX INITIALIZATION
+// ==========================================================================
+// onBeforeResolve runs once before the first CMS page resolution.
+// initVtexFromBlocks reads VTEX config (account, publicUrl) from CMS blocks.
+onBeforeResolve(() => {
+  initVtexFromBlocks();
+});
+// ==========================================================================
+// 7. ASYNC RENDERING
+// ==========================================================================
+// Enable deferred section loading (scroll-triggered).
+// Respects CMS Lazy wrappers. Layout sections and alwaysEager are never deferred.
+setAsyncRenderingConfig({
+  alwaysEager: [
+    "site/sections/Header/Header.tsx",
+    "site/sections/Footer/Footer.tsx",
+    "site/sections/Theme/Theme.tsx",
+    "site/sections/Images/Carousel.tsx",
+    // Add above-the-fold sections here
+  ],
+});
+// ==========================================================================
+// 8. INVOKE LOADERS (for /deco/invoke endpoint)
+// ==========================================================================
+setInvokeLoaders({
+  "vtex/loaders/intelligentSearch/productList.ts": cachedProductList,
+  "vtex/loaders/intelligentSearch/suggestions.ts": cachedSuggestions,
+  // Used by the admin to preview loader results
+});
+```
+## Key Patterns
+1. **Order matters**: blocks → meta → sections → loaders → commerce → async config
+2. **Critical sections**: Import synchronously for instant SSR, also register as lazy for client code-splitting
+3. **SWR caching**: `createCachedLoader` wraps commerce loaders with stale-while-revalidate
+4. **onBeforeResolve**: Deferred initialization — VTEX config is read from CMS blocks at first request
+5. **alwaysEager**: Sections that must render on first paint (no deferred loading)

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

@@ -0,0 +1,122 @@
+# vite.config.ts Template
+Battle-tested configuration from espacosmart-storefront.
+```typescript
+import { cloudflare } from "@cloudflare/vite-plugin";
+import { tanstackStart } from "@tanstack/react-start/plugin/vite";
+import react from "@vitejs/plugin-react";
+import tailwindcss from "@tailwindcss/vite";
+import { defineConfig } from "vite";
+import path from "path";
+const srcDir = path.resolve(__dirname, "src");
+export default defineConfig({
+  plugins: [
+    cloudflare({ viteEnvironment: { name: "ssr" } }),
+    tanstackStart({ server: { entry: "server" } }),
+    react({
+      babel: {
+        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;";
+        }
+      },
+    },
+  ],
+  // Inject site name at build time (not runtime)
+  define: {
+    "process.env.DECO_SITE_NAME": JSON.stringify(
+      process.env.DECO_SITE_NAME || "my-store"
+    ),
+  },
+  esbuild: {
+    jsx: "automatic",
+    jsxImportSource: "react",
+  },
+  resolve: {
+    // CRITICAL: Without dedupe, multiple React/TanStack instances cause hook errors
+    dedupe: [
+      "@tanstack/react-start",
+      "@tanstack/react-router",
+      "@tanstack/react-start-server",
+      "@tanstack/start-server-core",
+      "@tanstack/start-client-core",
+      "@tanstack/start-plugin-core",
+      "@tanstack/start-storage-context",
+      "react",
+      "react-dom",
+    ],
+    alias: {
+      "~": srcDir,
+    },
+  },
+});
+```
+## 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.

package/.cursor/skills/deco-to-tanstack-migration/templates/worker-entry.md ADDED Viewed

@@ -0,0 +1,67 @@
+# Worker Entry Templates
+## src/server.ts
+```typescript
+// CRITICAL: import "./setup" MUST be the first import.
+// Without it, server functions in Vite split modules have empty state
+// (blocks, registry, commerce loaders) causing 404 on client-side navigation.
+import "./setup";
+import { createStartHandler, defaultStreamHandler } from "@tanstack/react-start/server";
+export default createStartHandler(defaultStreamHandler);
+```
+## src/worker-entry.ts
+```typescript
+// CRITICAL: import "./setup" MUST be the first import.
+import "./setup";
+import handler, { createServerEntry } from "@tanstack/react-start/server-entry";
+import { createDecoWorkerEntry } from "@decocms/start/sdk/workerEntry";
+import {
+  handleMeta,
+  handleDecofileRead,
+  handleDecofileReload,
+  handleRender,
+  corsHeaders,
+} from "@decocms/start/admin";
+// Only if using VTEX:
+import { shouldProxyToVtex, proxyToVtex } from "@decocms/apps/vtex/utils/proxy";
+const serverEntry = createServerEntry({
+  async fetch(request) {
+    return await handler.fetch(request);
+  },
+});
+export default createDecoWorkerEntry(serverEntry, {
+  admin: {
+    handleMeta,
+    handleDecofileRead,
+    handleDecofileReload,
+    handleRender,
+    corsHeaders,
+  },
+  // VTEX proxy — routes like /api/*, /checkout/*, /arquivos/* go to VTEX
+  proxyHandler: (request, url) => {
+    if (shouldProxyToVtex(url.pathname)) {
+      return proxyToVtex(request);
+    }
+    return null;
+  },
+});
+```
+## Key Rules
+1. **`import "./setup"` is ALWAYS the first line** — both files. This registers sections, loaders, blocks, and commerce config before any server function executes.
+2. **Admin handlers go in `createDecoWorkerEntry`** — NOT inside `createServerEntry`. TanStack Start's build strips custom fetch logic from `createServerEntry` in production.
+3. **Proxy handler** — Optional. Only needed for platforms (VTEX, Shopify) that require server-side proxying.
+4. **Request flow**: `createDecoWorkerEntry` → admin routes (first) → cache check → proxy check → `serverEntry.fetch()` (TanStack Start).
+## Why `import "./setup"` Must Be First
+TanStack Start compiles `createServerFn()` calls into "split modules" — separate Vite module instances. Module-level state (blockData, commerceLoaders, sectionRegistry) initialized in `setup.ts` only exists in the original module instance. Without importing setup first, these split modules execute with empty state.
+The fix in `@decocms/start` uses `globalThis.__deco` to share state across all module instances. But `setup.ts` must run BEFORE any server function is called — which means it must be imported before `createStartHandler` or `createServerEntry`.

package/.cursor/skills/deco-typescript-fixes/SKILL.md ADDED Viewed

@@ -0,0 +1,178 @@
+---
+name: deco-typescript-fixes
+description: Strategies and patterns for fixing TypeScript errors in deco.cx storefronts, especially after migrations or dependency updates.
+---
+# Deco TypeScript Fixes
+This skill provides strategies for systematically fixing TypeScript errors in deco.cx storefronts. It's especially useful after:
+- Migrating from forked apps to official `deco-cx/apps`
+- Updating `@deco/deco` or `@deco/dev` versions
+- Adding stricter TypeScript settings
+## When to Use This Skill
+- User asks to "fix all type errors" or "make deno check pass"
+- After a migration that introduces many TypeScript errors
+- When enabling stricter type checking in a deco project
+## Critical: Use Fast Type Checker
+Standard `deno check` takes 30-60+ seconds. With 200+ errors, iterating is painful.
+**Always use the fast TSGo checker (Deno 2.1+, ideally 2.6+):**
+```bash
+# FAST (~3-5s) - ALWAYS use this
+deno check --unstable-tsgo --allow-import main.ts
+```
+## Quick Start
+1. Run `deno check --unstable-tsgo --allow-import main.ts` to get the full error list
+2. Count errors: `deno check --unstable-tsgo --allow-import main.ts 2>&1 | grep -c "error:"`
+3. Categorize errors (see Common Error Categories below)
+4. Fix in batches by category, committing after each batch
+5. Repeat until zero errors
+## Files in This Skill
+| File | Purpose |
+|------|---------|
+| `SKILL.md` | This overview and quick reference |
+| `common-fixes.md` | Detailed patterns and code examples |
+| `strategy.md` | The incremental fixing strategy |
+## Common Error Categories
+### 1. Missing Props Exports (Deco Compatibility)
+**Symptom**: Deco admin can't load the component/section properly
+**Pattern**: All components used as deco blocks need an exported `Props` type/interface
+```typescript
+// BEFORE - Props not exported
+interface Props {
+  title: string;
+}
+// AFTER - Export the Props
+export interface Props {
+  title: string;
+}
+```
+### 2. Global Type Declarations (Third-Party Scripts)
+**Symptom**: `Cannot find name 'AnalyticsQueue'` or similar for injected globals
+**Pattern**: Declare globals in `types/global.d.ts`
+```typescript
+// types/global.d.ts
+declare global {
+  // deno-lint-ignore no-var
+  var AnalyticsQueue: AnalyticsCommand[];
+  // deno-lint-ignore no-var
+  var dataLayer: unknown[];
+  // deno-lint-ignore no-var
+  var thirdPartyTracker: TrackerFn;
+}
+```
+### 3. Possibly Undefined Values
+**Symptom**: `Object is possibly 'undefined'`
+**Pattern**: Use optional chaining or nullish coalescing
+```typescript
+// BEFORE
+const name = product.name.toLowerCase();
+// AFTER - optional chaining + fallback
+const name = product?.name?.toLowerCase() ?? "";
+// AFTER - nullish coalescing for defaults
+const quantity = item.quantity ?? 1;
+```
+### 4. External API Type Mismatches
+**Symptom**: VTEX/external API returns different shape than expected types
+**Pattern**: Create custom types for API responses, use type assertions with comments
+```typescript
+// Create specific types for GraphQL responses
+// types/myorders.ts
+export interface LogisticsInfo {
+  deliveryChannel?: string;
+  shippingEstimateDate?: string;
+}
+// Use type assertion when SDK types don't match reality
+const order = data as unknown as VtexOrderData;
+```
+### 5. Platform Import Cleanup
+**Symptom**: Imports from removed platforms (Linx, Wake, etc.) fail
+**Pattern**: Search and remove unused platform code entirely
+```bash
+# Find all platform-specific files
+find . -name "*linx*" -o -name "*wake*" -o -name "*vnda*"
+# Remove them if not using those platforms
+```
+### 6. Optional Props Without Defaults
+**Symptom**: `Type 'undefined' is not assignable to type 'string'`
+**Pattern**: Make props explicitly optional or provide defaults
+```typescript
+// BEFORE
+interface Props {
+  href: string;
+}
+// AFTER - make optional with fallback in usage
+export interface Props {
+  href?: string;
+}
+// In component:
+const link = href ?? "#";
+```
+## Strategy Summary
+1. **Batch by category** - Fix all "possibly undefined" errors together, all "Props exports" together
+2. **Commit frequently** - Small commits let you track progress and rollback if needed
+3. **Document type assertions** - When using `as unknown as X`, add a comment explaining why
+4. **Create custom types** - Better to have explicit custom types than to silence errors
+5. **Check deco admin** - After fixes, verify blocks still load in the deco admin
+## Related Commands
+```bash
+# Fast type check (use this for iteration)
+deno check --unstable-tsgo --allow-import main.ts
+# Count errors
+deno check --unstable-tsgo --allow-import main.ts 2>&1 | grep -c "error:"
+# Find errors by category
+deno check --unstable-tsgo --allow-import main.ts 2>&1 | grep "possibly 'undefined'"
+deno check --unstable-tsgo --allow-import main.ts 2>&1 | grep "Cannot find name"
+deno check --unstable-tsgo --allow-import main.ts 2>&1 | grep "not assignable"
+# Find files with most errors
+deno check --unstable-tsgo --allow-import main.ts 2>&1 | grep "error:" | \
+  sed 's/:.*//g' | sort | uniq -c | sort -rn | head -20
+```