@decocms/start 0.38.0 → 0.40.0

package/{.cursor/skills/deco-tanstack-storefront-patterns/SKILL.md → .agents/skills/deco-to-tanstack-migration/references/storefront-patterns.md}

@@ -1,13 +1,9 @@
----
-name: deco-tanstack-storefront-patterns
-description: Runtime patterns, fixes, and learnings for Deco storefronts running on TanStack Start/React/Cloudflare Workers. Covers nested sections, dev cache control, workerEntry guards, section loaders, Fresh-to-React JSX porting, VTEX API resilience, node:async_hooks client bundle leak, SliderJS DOM timing, cart button loading state, server functions for VTEX actions, DOM manipulation conflicts with React, TypeScript patterns, loader cache/cacheKey module exports via createCachedLoaderFromModule, and the full multi-layer VTEX cache architecture. Also covers: setup.ts import order for server functions (client-nav 404 fix), globalThis backing for module-level state (split-module RPC problem), async rendering/deferred sections with IntersectionObserver, loadDeferredSection POST instead of GET (431 fix), section ordering with index stamping (mergeSections sort-based), layout section caching (5min TTL for Header/Footer), analytics hydration mismatch fix (useScript + suppressHydrationWarning), and vite.config.ts requirements for published @decocms/start packages (esbuildOptions jsx automatic + virtual module fallback + resolve.dedupe). Use when debugging or enhancing a deco-start storefront after the initial migration.
----
 
 # Deco TanStack Storefront Patterns
 
 Patterns and fixes discovered while porting and running `espacosmart-storefront` on the `@decocms/start` + TanStack Start stack. These apply to **any** Deco site after the initial migration.
 
-## When to Use This Skill
+## When to Use This Reference
 
 - Debugging runtime errors in a deco-start storefront
 - Porting sections that use nested sections (`{ Component, props }`)
@@ -994,135 +990,3 @@ export default defineConfig({
 - **Fix #1 (`esbuildOptions.jsx: "automatic"`)**: `@decocms/start` ships raw `.tsx` source. Vite's esbuild pre-bundler uses the classic transform by default. `jsx: "automatic"` makes it emit `import { jsx } from "react/jsx-runtime"` instead of `React.createElement`.
 - **Fix #2 (virtual module fallback)**: The import chain `cmsRoute.ts → @tanstack/react-start → @tanstack/start-server-core → router-manifest.js` reaches the client bundle. The `tanstack-start-injected-head-scripts:v` virtual is registered with `applyToEnvironment: server` only.
 - **Fix #3 (dedupe)**: Prevents duplicate TanStack instances when hoisting from peer deps.
-
----
-
-## 25. SEO Architecture — Three Layers
-
-### Problem
-
-Sites migrated from Fresh/Deno often have broken SEO:
-- `Seo.tsx` component returns `null` (dead stub from migration)
-- Route `head()` functions only set `<title>`, missing description/canonical/OG
-- No JSON-LD structured data on PDPs
-- No Open Graph tags for social sharing
-
-### Solution — Framework + Section + Component
-
-**Layer 1: Framework head()** (`cmsRouteConfig` / `cmsHomeRouteConfig`)
-Automatically emits title, description, canonical, OG, Twitter Card, robots from `DecoPageResult.seo`. Requires `defaultDescription` option and `registerSeoSections()` in setup.
-
-**Layer 2: Section SEO** (`registerSeoSections` + `registerSectionLoaders`)
-Sections like SEOPDP register as SEO contributors. Their section loader computes title/description/canonical from commerce data (product name, product description, breadcrumb canonical). The framework extracts these into `PageSeo`.
-
-**Layer 3: Structured data** (section component renders JSON-LD)
-The `Seo.tsx` component renders `<script type="application/ld+json">` for Product, WebSite, BreadcrumbList schemas. Meta tags are NOT rendered here — the framework handles those via `head()`.
-
-### Setup Checklist
-
-```typescript
-// setup.ts
-import { registerSeoSections } from "@decocms/start/cms";
-
-registerSeoSections(["site/sections/SEOPDP.tsx"]);
-
-// Also register the SEOPDP section loader:
-registerSectionLoaders({
-  "site/sections/SEOPDP.tsx": async (props, req) => {
-    const mod = await import("./sections/SEOPDP");
-    return mod.loader(props, req, { seo: {} } as any) ?? props;
-  },
-});
-```
-
-```typescript
-// routes/$.tsx — spread full config, framework handles SEO
-const routeConfig = cmsRouteConfig({
-  siteName: "My Store",
-  defaultTitle: "My Store - Default Title",
-  defaultDescription: "My Store — best products...",
-  ignoreSearchParams: ["skuId"],
-});
-export const Route = createFileRoute("/$")({ ...routeConfig, component: CmsPage });
-```
-
-```typescript
-// __root.tsx — fallback description and OG globals
-head: () => ({
-  meta: [
-    { charSet: "utf-8" },
-    { name: "viewport", content: "width=device-width, initial-scale=1" },
-    { title: "My Store - Default Title" },
-    { name: "description", content: "My Store — default description." },
-    { property: "og:site_name", content: "My Store" },
-    { property: "og:locale", content: "pt_BR" },
-  ],
-}),
-```
-
-### Anti-Patterns
-
-- `Seo.tsx` returning `null` — must render JSON-LD at minimum
-- Custom `head()` in routes that only sets title — use `cmsRouteConfig` which handles full SEO
-- Hardcoded Device.Provider — use matchMedia for client, section loaders for server
-
----
-
-## 26. Device Detection — No Hardcoded Provider
-
-### Problem
-
-Sites often have `<Device.Provider value={{ isMobile: false }}>` in `__root.tsx`, making ALL client-side components think they're on desktop regardless of actual viewport.
-
-### Solution — Two-Layer Detection
-
-**Server-side**: Section loaders via `registerSectionLoaders()` detect device from UA and inject `isMobile` / `device` as props. The page result also includes `device` for client use.
-
-**Client-side**: Use `useSyncExternalStore` + `window.matchMedia` instead of React context:
-
-```typescript
-// contexts/device.tsx
-import { useSyncExternalStore } from "react";
-
-const MOBILE_QUERY = "(max-width: 767px)";
-
-function subscribe(cb: () => void) {
-  if (typeof window === "undefined") return () => {};
-  const mql = window.matchMedia(MOBILE_QUERY);
-  mql.addEventListener("change", cb);
-  return () => mql.removeEventListener("change", cb);
-}
-
-function getSnapshot() { return window.matchMedia(MOBILE_QUERY).matches; }
-function getServerSnapshot() { return false; }
-
-export const useDevice = () => {
-  const isMobile = useSyncExternalStore(subscribe, getSnapshot, getServerSnapshot);
-  return { isMobile };
-};
-```
-
-### Why matchMedia > UA context
-
-- Reflects actual viewport, not a server guess
-- Reactive — updates if user resizes browser
-- No Provider needed — works anywhere in the component tree
-- SSR defaults to desktop (false), hydrates to real value
-
----
-
-## Related Skills
-
-| Skill | Purpose |
-|-------|---------|
-| `deco-to-tanstack-migration` | Initial migration playbook (imports, signals, architecture) |
-| `deco-cms-route-config` | Route config, SEO architecture, device detection |
-| `deco-tanstack-navigation` | SPA navigation patterns (`<Link>`, `useNavigate`, `loaderDeps`) |
-| `deco-islands-migration` | Eliminating the `src/islands/` directory |
-| `deco-edge-caching` | Edge caching with `createDecoWorkerEntry` |
-| `deco-vtex-fetch-cache` | SWR fetch cache for VTEX APIs (`fetchWithCache`, `vtexCachedFetch`) |
-| `deco-api-call-dedup` | API call dedup, batching, PLP filtering patterns |
-| `deco-cms-layout-caching` | Layout section caching in CMS resolve |
-| `deco-typescript-fixes` | TypeScript error patterns and fixes |
-| `deco-storefront-test-checklist` | Context-aware QA checklist generation |
-| `deco-startup-analysis` | Analyzing startup logs for issues |

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

@@ -0,0 +1,78 @@
+# Vite Configuration
+
+## Final Config (Post-Migration)
+
+After all imports are rewritten, the config should be minimal:
+
+```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(),
+  ],
+  resolve: {
+    alias: {
+      "~": srcDir,
+    },
+  },
+});
+```
+
+**One alias only**: `~` -> `src/`. Nothing else.
+
+## tsconfig.json
+
+Must mirror 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.
+
+## React Compiler
+
+The `babel-plugin-react-compiler` with `target: "19"` enables automatic memoization. Requires `@vitejs/plugin-react` instead of the default SWC plugin.
+
+Install: `npm install -D @vitejs/plugin-react babel-plugin-react-compiler`
+
+## Environment Variables
+
+For VTEX API keys, use Cloudflare Workers secrets or `.dev.vars`:
+
+```
+VTEX_ACCOUNT=mystore
+VTEX_APP_KEY=...
+VTEX_APP_TOKEN=...
+```
+
+Accessed via `process.env.*` in `createServerFn` handlers.

package/.agents/skills/deco-to-tanstack-migration/references/vtex-commerce.md

@@ -0,0 +1,165 @@
+# VTEX Commerce Gotchas
+
+> Section loaders, cart CORS, price specs, facets, URL-blind loaders, cookie handling.
+
+
+## 1. Section Loaders Don't Execute
+
+Deco sections have `export const loader = async (props, req, ctx) => { ... }` that runs server-side before the component renders. In TanStack Start, these don't execute automatically. Components typed as `SectionProps<typeof loader>` expect the augmented props, but only receive the raw CMS block props.
+
+**Symptom**: Components crash on `.find()`, `.length`, or property access of loader-provided props that are `undefined`.
+
+**Fix**: Register them via `registerSectionLoaders()` in `setup.ts`.
+
+**Safe-default pattern** (most pragmatic for initial migration):
+
+```typescript
+// Before: component expects loader-augmented props
+function ProductMain({ page, productAdditional, showTogether, priceSimulation, isMobile }: SectionProps<typeof loader>) {
+
+// After: destructure with safe defaults for all loader-only props
+function ProductMain(rawProps: any) {
+  const {
+    page,
+    productAdditional = [],         // from section loader
+    showTogether = [],               // from section loader
+    showTogetherSimulation = [],     // from section loader
+    priceSimulation = 0,             // from section loader
+    noInterestInstallmentValue = null,
+    skuProductsKit = [],             // from section loader
+    isMobile = false,                // from section loader (device detection)
+  } = rawProps;
+```
+
+This lets the core component render while gracefully degrading features that depend on loader data (cross-selling, price simulation, etc.).
+
+
+## 7. VTEX API Auth on Cloudflare Workers
+
+Env vars must be set via `wrangler secret put` or `.dev.vars`, not `.env`.
+
+
+## 8. Cookie Handling
+
+In TanStack Start, manage `checkout.vtex.com__orderFormId` cookies manually via `document.cookie`.
+
+
+## 32. Section Loader Logic Must Not Be Stripped
+
+**Severity**: HIGH — sections render empty/broken
+
+During migration, section loaders (e.g., `sections/Header/Header.tsx`) may have their async data-fetching logic removed. For example, the `ctx.invoke.vtex.loaders.categories.tree()` call that populates navigation menus. Without it, the header renders with no category links.
+
+**Fix**: Keep all section loader logic intact. The loader signature `(props, req, ctx) => {...}` and the `ctx.invoke` calls should be preserved as-is.
+
+
+## 34. Commerce Loaders Are Blind to the URL
+
+**Severity**: CRITICAL — search and category pages return wrong/no products
+
+When `resolve.ts` processes CMS blocks, it passes only the static CMS block props to commerce loaders (PLP, PDP). The current URL, query string (`?q=`), path (`/drywall`), sort, pagination, and filter parameters are never forwarded.
+
+**Symptom**: Search pages (`/s?q=parafuso`) return zero products. Category pages (`/drywall`) show random/no products. Sort and pagination controls do nothing.
+
+**Root cause**: `resolveValue()` in `resolve.ts` calls commerce loaders with `resolvedProps` (CMS block config only). The `matcherCtx` (containing URL, path, user-agent) is used for matcher evaluation but never passed to commerce loaders.
+
+**Fix**: Pass `matcherCtx` as a second argument to commerce loaders in `resolve.ts`. Then the PLP loader can extract `?q=` for search, path for categories, `?sort=` for sorting, `?page=` for pagination, and `?filter.X=Y` for facets.
+
+This is a change in `@decocms/start` (resolve.ts). Until upstreamed, use patch-package or vendor the file.
+
+
+## 35. VTEX Product Loaders Ship with Empty priceSpecification
+
+**Severity**: HIGH — no discount badges, no strikethrough prices, no installments
+
+All three VTEX product loaders (`vtexProductList`, `productListingPage`, `productDetailsPage`) build offers with `priceSpecification: []`. The `useOffer()` hook depends on this array to extract `ListPrice` (for discount math + strikethrough), `SalePrice`, and `Installment` entries.
+
+**Symptom**: Product cards show only one price (no strikethrough). No "X% OFF" discount badge. No "Ou em Nx de R$ X sem juros" installment text.
+
+**Fix**: Add a `buildPriceSpecification()` helper to each loader that transforms the VTEX `commertialOffer` data:
+
+```typescript
+function buildPriceSpecification(offer: any): any[] {
+  const specs: any[] = [];
+  if (offer.ListPrice != null) {
+    specs.push({ "@type": "UnitPriceSpecification", priceType: "https://schema.org/ListPrice", price: offer.ListPrice });
+  }
+  if (offer.Price != null) {
+    specs.push({ "@type": "UnitPriceSpecification", priceType: "https://schema.org/SalePrice", price: offer.Price });
+  }
+  // Find best no-interest installment
+  const noInterest = (offer.Installments ?? [])
+    .filter((i: any) => i.InterestRate === 0)
+    .sort((a: any, b: any) => b.NumberOfInstallments - a.NumberOfInstallments);
+  if (noInterest.length > 0) {
+    const best = noInterest[0];
+    specs.push({
+      "@type": "UnitPriceSpecification",
+      priceType: "https://schema.org/SalePrice",
+      priceComponentType: "https://schema.org/Installment",
+      billingDuration: best.NumberOfInstallments,
+      billingIncrement: best.Value,
+      price: best.TotalValuePlusInterestRate,
+    });
+  }
+  return specs;
+}
+```
+
+This is a change in `@decocms/apps`. Until upstreamed, patch or vendor the loader files.
+
+
+## 36. VTEX Facets API Response Structure Mismatch
+
+The VTEX Intelligent Search facets endpoint returns `{ facets: ISFacetGroup[] }`, NOT a direct `ISFacetGroup[]` array. Accessing `response` directly as an array yields no filter data.
+
+Additionally, `PRICERANGE` facets must be converted to `FilterToggle` format (with `value: "min:max"` strings) for the existing `Filters.tsx` component to render them. The component's `isToggle()` filter drops anything that isn't `FilterToggle`.
+
+**Fix**: Unwrap with `const facetGroups = response.facets ?? [];` and convert price ranges:
+
+```typescript
+if (group.type === "PRICERANGE") {
+  return { "@type": "FilterToggle" as const, key: "price", label: group.name, quantity: 0,
+    values: group.values.map((v) => ({
+      value: `${v.range.from}:${v.range.to}`, label: `R$ ${v.range.from} - R$ ${v.range.to}`,
+      quantity: v.quantity, selected: false, url: `?filter.price=${v.range.from}:${v.range.to}`,
+    })),
+  };
+}
+```
+
+
+## 39. Cart Requires Server-Side Proxy for VTEX API (CORS)
+
+**Severity**: HIGH — add-to-cart, minicart, and checkout flow completely broken
+
+The storefront domain (e.g., `espacosmart-tanstack.deco.site`) differs from the VTEX checkout domain (`lojaespacosmart.vtexcommercestable.com.br`). Direct browser `fetch()` calls to VTEX are blocked by CORS. Additionally, the `checkout.vtex.com__orderFormId` cookie is scoped to the VTEX domain and inaccessible from the storefront.
+
+**Fix**: Use TanStack Start `createServerFn` to create server-side proxy functions:
+
+```typescript
+// src/lib/vtex-cart-server.ts
+import { createServerFn } from "@tanstack/react-start";
+
+export const getOrCreateCart = createServerFn({ method: "GET" })
+  .validator((orderFormId: string) => orderFormId)
+  .handler(async ({ data: orderFormId }) => {
+    const url = orderFormId
+      ? `https://${ACCOUNT}.vtexcommercestable.com.br/api/checkout/pub/orderForm/${orderFormId}`
+      : `https://${ACCOUNT}.vtexcommercestable.com.br/api/checkout/pub/orderForm`;
+    const res = await fetch(url, {
+      method: "POST",
+      headers: { "Content-Type": "application/json", "X-VTEX-API-AppKey": API_KEY, "X-VTEX-API-AppToken": API_TOKEN },
+      body: JSON.stringify({ expectedOrderFormSections: ["items", "totalizers", "shippingData", "clientPreferencesData", "storePreferencesData", "marketingData"] }),
+    });
+    return res.json();
+  });
+```
+
+The `useCart` hook manages the `orderFormId` in a client-side cookie and calls these server functions.
+
+**Checkout URL**: The minicart's "Finalizar Compra" link must append the `orderFormId` as a query parameter since the VTEX checkout domain can't read the storefront's cookies:
+
+```typescript
+const checkoutUrl = `https://secure.${STORE_DOMAIN}/checkout/?orderFormId=${orderFormId}`;
+```

package/.agents/skills/deco-to-tanstack-migration/references/worker-cloudflare.md

@@ -0,0 +1,209 @@
+# Worker / Cloudflare / Build Gotchas
+
+> TanStack worker entry stripping, setup ordering, AsyncLocalStorage, cache, npm.
+
+
+## 9. Build Succeeds but Runtime Fails
+
+After import rewrites, always test: build → dev → visit pages → test interactive features.
+
+
+## 10. npm link for Local Dev
+
+```bash
+cd apps-start && npm link
+cd ../deco-start && npm link
+cd ../my-store && npm link @decocms/apps @decocms/start
+```
+
+
+## 12. No Compat Layers
+
+After migration: no `src/compat/`, only `~/*` alias, zero compat files in packages.
+
+
+## 13. AsyncLocalStorage in Client Bundles
+
+Use namespace import + runtime conditional (or the `deco-server-only-stubs` Vite plugin).
+
+
+## 14. TanStack Start Ignores Custom Worker Entry Code
+
+**Severity**: CRITICAL -- cache logic, admin routes, and any custom request interception will silently not work in production.
+
+TanStack Start's Cloudflare adapter **completely ignores** the `export default` in `server.ts`. It generates its own Worker entry that calls `createStartHandler(defaultStreamHandler)` directly. Custom logic inside `createServerEntry({ async fetch(request) { ... } })` is also stripped by Vite/Rollup in production builds.
+
+**Symptom**: Admin routes like `/live/_meta` return HTML instead of JSON. Edge caching (Cache API, X-Cache headers) doesn't work despite being implemented. Every request hits the origin at full SSR cost. The `Cache-Control` headers from route-level `headers()` functions appear correctly (because TanStack applies them), but the custom `X-Cache` header and cache storage never execute.
+
+**Diagnosis**: Search the built `dist/server/worker-entry-*.js` bundle for your custom code (e.g., `X-Cache`, `caches.open`, `_cache/purge`). If absent, TanStack stripped it.
+
+**Fix**: Create a **separate** `src/worker-entry.ts` file that wraps TanStack Start's built handler. Point `wrangler.jsonc` to this file instead of `@tanstack/react-start/server-entry`.
+
+```typescript
+// src/worker-entry.ts
+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";
+
+const serverEntry = createServerEntry({
+  async fetch(request) {
+    return await handler.fetch(request);
+  },
+});
+
+export default createDecoWorkerEntry(serverEntry, {
+  admin: { handleMeta, handleDecofileRead, handleDecofileReload, handleRender, corsHeaders },
+});
+```
+
+```jsonc
+// wrangler.jsonc -- MUST point to custom entry, NOT the default
+{
+  "main": "./src/worker-entry.ts",
+  // NOT: "main": "@tanstack/react-start/server-entry"
+}
+```
+
+This ensures admin route interception AND edge caching survive the build because they're in the Worker's own fetch handler, outside of TanStack's build pipeline.
+
+
+## 19. `import "./setup"` Ordering (CRITICAL)
+
+`import "./setup"` MUST be the first import in both `server.ts` and `worker-entry.ts`. Without it, server functions in Vite split modules execute before `setBlocks()` has been called, causing `resolveDecoPage` to return null → 404 on client-side navigation.
+
+**Symptom**: SSR works fine (F5), but clicking links shows "No CMS page block matches this URL".
+
+
+## 20. loadDeferredSection Must Use POST
+
+Without this, the admin shows "Incorrect type. Expected 'array'" for fields that contain loader references in the `.decofile`.
+
+
+## 24. new URL() with Relative Paths Fails in Workers
+
+`new URL("/product/p")` works in browsers (uses `window.location` as base) but throws `Invalid URL` in Workers/Node because there's no implicit base.
+
+**Fix**: Always provide a base URL:
+```typescript
+const parsed = new URL(url, "https://localhost");
+return parsed.pathname + parsed.search;
+```
+
+
+## 25. Global Variables Throw ReferenceError
+
+Code that references undeclared globals (e.g., `userAddressData` injected by VTEX scripts) will throw `ReferenceError: X is not defined` in Workers where those scripts don't run.
+
+**Fix**: Access via `globalThis`:
+```typescript
+const data = (globalThis as any).userAddressData;
+if (data && Array.isArray(data)) { /* use data */ }
+```
+
+
+## 26. Section-Type Props Use __resolveType Format
+
+In the new `@decocms/start`, section-type props from the CMS arrive as `{ __resolveType: "site/sections/Foo.tsx", ...props }`, NOT the old `{ Component, props }` format. Components that render section props must handle this.
+
+**Fix**: Create a `RenderSection` bridge component that:
+1. Checks for `section.Component` (old format) and renders directly
+2. Checks for `section.__resolveType` (new format), resolves via `getSection()` from `@decocms/start/cms`, and renders with `React.lazy` + `Suspense`
+
+
+## 27. jsdom Must Be Replaced in Workers
+
+`jsdom` is a heavy Node.js dependency that cannot run in Cloudflare Workers. Components using it for HTML sanitization must use `dompurify` instead.
+
+**Fix**: Replace `import { JSDOM } from "jsdom"` with:
+```typescript
+import DOMPurify from "dompurify";
+const clean = typeof document !== "undefined" ? DOMPurify.sanitize(html) : html;
+```
+
+
+## 28. Deno npm: Prefix Must Be Removed
+
+Imports like `import Color from "npm:colorjs.io"` use the Deno-specific `npm:` prefix. Vite/Node don't understand it.
+
+**Fix**: Remove the `npm:` prefix and install the package: `npm install colorjs.io`.
+
+
+## 30. Stale Edge Cache After Deploy Requires Explicit Purge
+
+**Severity**: MEDIUM — causes "Failed to fetch dynamically imported module" errors
+
+After deploying a new build to Cloudflare Workers, the edge cache may still serve old HTML that references previous JS bundle hashes. This causes module import failures.
+
+**Fix**: After every deploy, purge the cache:
+1. Set a `PURGE_TOKEN` secret: `npx wrangler secret put PURGE_TOKEN`
+2. Call the purge endpoint: `POST /_cache/purge` with `Authorization: Bearer <token>` and body `{"paths":["/"]}`
+3. Automate this in CI/CD (see the deploy.yml workflow)
+
+
+## 44. Runtime Module Import Kills Lazy-Loaded Sections
+
+**Severity**: HIGH — sections silently disappear, data appears in RSC streaming but component renders nothing
+
+Vite tree-shakes unused imports in production builds, so a section file that imports a non-existent module may pass `npm run build` without errors. But at runtime, when the section is dynamically imported via `registerSections`'s lazy `() => import("./sections/X")`, ALL imports in the module execute. A missing file kills the entire section module.
+
+**Symptom**: Product shelves or other sections disappear. HTML size drops significantly. Product data appears in React streaming data (`$R[...]` notation) but zero product cards render as actual HTML. No error in the build log.
+
+**Example**:
+```typescript
+// sections/Product/ProductShelf.tsx
+import LoadingCard from "~/components/product/loadingCard";  // file doesn't exist!
+export { default, loader } from "~/components/product/ProductShelf";
+
+export function LoadingFallback() {
+  return <LoadingCard />;  // only used here — tree-shaken in build
+}
+```
+
+Build passes because `LoadingFallback` is a named export that nothing imports. But at runtime, the dynamic `import("./sections/Product/ProductShelf")` executes the module, hits the missing `loadingCard` import, and the entire section fails to load.
+
+**Fix**: Create the missing file, even if it's a minimal stub:
+```typescript
+// components/product/loadingCard.tsx
+export default function LoadingCard() {
+  return <div className="animate-pulse bg-base-200 h-[400px] w-[200px] rounded" />;
+}
+```
+
+**Prevention**: After copying files from the original repo, verify all imports resolve:
+```bash
+npx tsc --noEmit  # catches missing modules that Vite's tree-shaking hides
+```
+
+
+## 45. GitHub Packages npm Requires Auth Even for Public Packages
+
+**Severity**: MEDIUM — blocks dependency installation for new contributors and CI
+
+GitHub Packages' npm registry (`npm.pkg.github.com`) requires authentication even for public packages. This is a known limitation that GitHub has not resolved. Attempting to `npm install` a public `@decocms/*` package without a token returns `401 Unauthorized`.
+
+**Workaround A (recommended for development)**: Use `github:` Git URL syntax instead of npm registry references. This bypasses the npm registry entirely and uses Git HTTPS (no auth needed for public repos):
+
+```json
+{
+  "@decocms/apps": "github:decocms/apps-start",
+  "@decocms/start": "github:decocms/deco-start#main"
+}
+```
+
+**Important**: The repo name in the `github:` URL must match the actual GitHub repo name, not the npm package name. `@decocms/start` is published from repo `decocms/deco-start`, NOT `decocms/start`.
+
+**Workaround B (recommended for production)**: Publish to npmjs.com instead. Only npm's public registry supports truly zero-auth public package installation.
+
+**Workaround C (if you must use GitHub Packages)**: Generate a GitHub PAT with `read:packages` scope and configure:
+```bash
+npm config set //npm.pkg.github.com/:_authToken <YOUR_TOKEN>
+```
+
+Or in project `.npmrc` with an env var (for CI):
+```
+@decocms:registry=https://npm.pkg.github.com
+//npm.pkg.github.com/:_authToken=${NODE_AUTH_TOKEN}
+```
+
+**Tradeoff with `github:` syntax**: No semver resolution — `npm update` is meaningless. Pin to a tag for stability: `github:decocms/deco-start#v0.14.2`. Without a tag, you get HEAD of the default branch.

package/.agents/skills/deco-to-tanstack-migration/templates/package-json.md

@@ -0,0 +1,55 @@
+# package.json Template
+
+```json
+{
+  "name": "my-tanstack-store",
+  "version": "0.1.0",
+  "type": "module",
+  "scripts": {
+    "dev": "npm run generate && vite dev",
+    "build": "npm run generate && vite build",
+    "generate": "npm run generate:blocks && npm run generate:invoke && npm run generate:schema",
+    "generate:blocks": "tsx node_modules/@decocms/start/scripts/generate-blocks.ts",
+    "generate:invoke": "tsx node_modules/@decocms/start/scripts/generate-invoke.ts",
+    "generate:schema": "tsx node_modules/@decocms/start/scripts/generate-schema.ts --site storefront",
+    "deploy": "wrangler deploy"
+  },
+  "dependencies": {
+    "@decocms/apps": "^0.20.1",
+    "@decocms/start": "^0.16.4",
+    "@tanstack/react-query": "^5.90.21",
+    "@tanstack/react-router": "^1.166.2",
+    "@tanstack/react-router-devtools": "^1.166.2",
+    "@tanstack/react-start": "^1.166.2",
+    "@tanstack/react-store": "^0.9.1",
+    "react": "^19.2.4",
+    "react-dom": "^19.2.4"
+  },
+  "devDependencies": {
+    "@cloudflare/vite-plugin": "^1.26.1",
+    "@tailwindcss/vite": "^4.2.1",
+    "@tanstack/router-generator": "^1.166.0",
+    "@types/react": "^19.0.0",
+    "@types/react-dom": "^19.0.0",
+    "babel-plugin-react-compiler": "^1.0.0",
+    "daisyui": "^5.5.19",
+    "tailwindcss": "^4.2.1",
+    "tsx": "^4.19.2",
+    "typescript": "^5.9.3",
+    "vite": "^7.3.1",
+    "wrangler": "^4.14.1",
+    "@vitejs/plugin-react": "^4.5.2"
+  }
+}
+```
+
+## Notes
+
+- `@decocms/start` and `@decocms/apps` come from GitHub Packages — needs `.npmrc`:
+  ```
+  @decocms:registry=https://npm.pkg.github.com
+  //npm.pkg.github.com/:_authToken=${NODE_AUTH_TOKEN}
+  ```
+- Set `NODE_AUTH_TOKEN` in `.env` (add `.env` to `.gitignore`)
+- `generate` scripts run before dev and build to produce `blocks.gen.ts`, `invoke.gen.ts`, `meta.gen.json`
+- `tsx` is needed for the generate scripts (TypeScript execution)