@decocms/start 0.19.0

package/.cursor/skills/deco-cms-layout-caching/SKILL.md

@@ -0,0 +1,293 @@
+---
+name: deco-cms-layout-caching
+description: Cache layout sections (Header, Footer, Theme) in @decocms/start to avoid redundant CMS resolution and API calls on every navigation. Covers resolvedLayoutCache in resolve.ts, layoutInflight dedup in sectionLoaders.ts, pageInflight dedup in cmsRoute.ts, registerLayoutSections, staleTime in dev mode, and diagnosing repeated intelligent-search calls. Use when page loads trigger duplicate VTEX API calls for Header shelves, variant changes re-resolve the entire CMS page, or layout sections cause N+1 API patterns.
+---
+
+# CMS Layout Section Caching
+
+Multi-layer caching strategy for layout sections (Header, Footer, Theme, etc.) in `@decocms/start`. These sections appear on every page but rarely change — caching them eliminates the biggest source of redundant API calls.
+
+## When to Use This Skill
+
+- Server logs show repeated `intelligent-search/product_search` calls for Header shelves on every navigation
+- Variant changes trigger full CMS resolution including Header/Footer
+- `[CMS]` logs show the same sections being resolved multiple times
+- PDP load takes >2s and most time is spent on layout section loaders
+- Setting up a new Deco site and want optimal caching from the start
+
+---
+
+## Architecture: 3 Caching Layers for Layout Sections
+
+```
+Request → loadCmsPage (pageInflight dedup)
+  └→ resolveDecoPage
+       ├→ Layout sections → resolvedLayoutCache (5min TTL) + resolvedLayoutInflight
+       └→ Content sections → resolve normally
+  └→ runSectionLoaders
+       ├→ Layout sections → layoutCache (5min TTL) + layoutInflight
+       └→ Content sections → run loader normally
+```
+
+| Layer | File | What it caches | TTL | Key |
+|-------|------|----------------|-----|-----|
+| **Page inflight** | `cmsRoute.ts` | Entire `loadCmsPage` result | In-flight only | `basePath` (no query) |
+| **Layout resolution** | `resolve.ts` | Fully resolved CMS props for layout sections | 5 min | Block reference key |
+| **Layout loaders** | `sectionLoaders.ts` | Section loader output for layout sections | 5 min | Component key |
+
+---
+
+## Layer 1: Page In-Flight Deduplication (`cmsRoute.ts`)
+
+Prevents concurrent `loadCmsPage` calls for the same path (e.g., prefetch + click happening simultaneously).
+
+```typescript
+const pageInflight = new Map<string, Promise<unknown>>();
+
+export const loadCmsPage = createServerFn({ method: "GET" }).handler(
+  async (ctx) => {
+    const fullPath = ctx.data as string;
+    const [basePath] = fullPath.split("?");
+
+    const existing = pageInflight.get(basePath);
+    if (existing) return existing;
+
+    const promise = loadCmsPageInternal(fullPath)
+      .finally(() => pageInflight.delete(basePath));
+    pageInflight.set(basePath, promise);
+    return promise;
+  },
+);
+```
+
+### Why `basePath` (no query)?
+
+The CMS page structure is the same regardless of `?skuId=X` or other query params. Using `basePath` ensures that `/product/p?skuId=1` and `/product/p?skuId=2` share the same inflight promise.
+
+---
+
+## Layer 2: Layout Resolution Cache (`resolve.ts`)
+
+Caches the fully resolved CMS output for layout sections. This is the most impactful layer because layout sections often contain embedded commerce loaders (Header with product shelves) that make expensive API calls.
+
+### Registration
+
+In your site's `setup.ts`:
+
+```typescript
+import { registerLayoutSections } from "@decocms/start/cms";
+
+registerLayoutSections([
+  "site/sections/Header/Header.tsx",
+  "site/sections/Footer/Footer.tsx",
+  "site/sections/Theme/Theme.tsx",
+  "site/sections/Miscellaneous/CookieConsent.tsx",
+  "site/sections/Social/WhatsApp.tsx",
+]);
+```
+
+### How It Works
+
+In `resolveDecoPage`, before resolving each raw section:
+
+1. Check if the raw block eventually resolves to a registered layout section (walks up to 5 levels of block references like `"Header - 01"` → `"Header"` → `site/sections/Header/Header.tsx`)
+2. If layout: check `resolvedLayoutCache` → return cached result if fresh
+3. If inflight: return existing promise (dedup concurrent resolutions)
+4. Otherwise: resolve normally, cache result for 5 minutes
+
+```typescript
+const resolvedLayoutCache = new Map<string, { sections: ResolvedSection[]; ts: number }>();
+const resolvedLayoutInflight = new Map<string, Promise<ResolvedSection[]>>();
+const LAYOUT_CACHE_TTL = 5 * 60_000; // 5 minutes
+
+// Inside resolveDecoPage:
+const layoutKey = isRawSectionLayout(section);
+if (layoutKey) {
+  const cached = getCachedResolvedLayout(layoutKey);
+  if (cached) return cached;
+
+  const inflight = resolvedLayoutInflight.get(layoutKey);
+  if (inflight) return inflight;
+
+  const promise = resolveRawSection(section, rctx).then((results) => {
+    setCachedResolvedLayout(layoutKey, results);
+    return results;
+  });
+  resolvedLayoutInflight.set(layoutKey, promise);
+  promise.finally(() => resolvedLayoutInflight.delete(layoutKey));
+  return promise;
+}
+```
+
+### `isRawSectionLayout` — Walking Block References
+
+CMS blocks often reference other blocks:
+- `"Header - 01"` → resolves to `"Header"` → resolves to `{ __resolveType: "site/sections/Header/Header.tsx" }`
+
+```typescript
+function isRawSectionLayout(section: RawSection): string | null {
+  // Walk up to 5 levels of block indirection
+  let current = section;
+  for (let depth = 0; depth < 5; depth++) {
+    const resolveType = current.__resolveType;
+    if (isLayoutSection(resolveType)) return resolveType;
+    const block = decofileData?.[resolveType];
+    if (!block || typeof block !== "object") return null;
+    current = block as RawSection;
+  }
+  return null;
+}
+```
+
+---
+
+## Layer 3: Layout Section Loader Cache (`sectionLoaders.ts`)
+
+Caches the output of section loaders (the `export const loader` functions) for layout sections.
+
+```typescript
+const layoutSections = new Set<string>();
+const layoutCache = new Map<string, { data: ResolvedSection; ts: number }>();
+const layoutInflight = new Map<string, Promise<ResolvedSection>>();
+
+export async function runSectionLoaders(
+  sections: ResolvedSection[],
+  request: Request,
+): Promise<ResolvedSection[]> {
+  return Promise.all(
+    sections.map(async (section) => {
+      const key = section.Component;
+      const loaderFn = loaderRegistry.get(key);
+
+      if (isLayoutSection(key)) {
+        // Check cache
+        const cached = layoutCache.get(key);
+        if (cached && Date.now() - cached.ts < LAYOUT_CACHE_TTL) {
+          return cached.data;
+        }
+        // Check inflight
+        const inflight = layoutInflight.get(key);
+        if (inflight) return inflight;
+
+        const promise = runLoader(section, loaderFn, request).then((result) => {
+          layoutCache.set(key, { data: result, ts: Date.now() });
+          return result;
+        });
+        layoutInflight.set(key, promise);
+        promise.finally(() => layoutInflight.delete(key));
+        return promise;
+      }
+
+      return loaderFn ? runLoader(section, loaderFn, request) : section;
+    }),
+  );
+}
+```
+
+---
+
+## Diagnosing Layout Cache Issues
+
+### Symptom: Repeated `intelligent-search` calls in logs
+
+```
+[VTEX] ProductList: query="", count=100, collection="152", sort="price:desc"
+[VTEX] ProductList: query="", count=100, collection="200", sort="price:desc"
+[VTEX] ProductList: query="", count=20, collection="", sort="price:desc"
+```
+
+These come from Header product shelves being re-resolved on every navigation.
+
+### Fix Checklist
+
+1. Ensure `registerLayoutSections` includes the Header section key
+2. Verify the block reference chain resolves correctly (check `.deco/blocks/Header*.json`)
+3. Confirm `isLayoutSection` returns `true` for the section key
+4. Add logging to verify cache hits: `console.log("[CMS] Layout cache HIT:", layoutKey)`
+
+### Symptom: `staleTime: 0` causes re-fetch despite `loaderDeps` filtering
+
+In dev mode, if `routeCacheDefaults` returns `{ staleTime: 0, gcTime: 0 }`, TanStack Router always re-fetches even when `loaderDeps` returns the same deps.
+
+**Fix**: Set minimum staleTime in dev:
+
+```typescript
+// In cacheHeaders.ts → routeCacheDefaults()
+if (isDev) return { staleTime: 5_000, gcTime: 30_000 };
+```
+
+---
+
+## Common Errors During Implementation
+
+### Error: `isLayoutSection is not a function`
+
+The `isLayoutSection` function must be exported from `@decocms/start/cms`:
+
+```typescript
+// cms/index.ts
+export { isLayoutSection, registerLayoutSections } from "./sectionLoaders";
+```
+
+### Error: Layout sections cached but still showing stale content
+
+The 5-minute TTL means layout sections won't reflect CMS changes for up to 5 minutes in dev. Restart the dev server to clear in-memory caches.
+
+### Error: Block reference chain not found
+
+If `isRawSectionLayout` returns `null` for a block like `"Header - 01"`, the block reference in `.deco/blocks/` may not resolve to the layout section. Check:
+
+```bash
+cat '.deco/blocks/Header - 01.json' | python3 -c "import sys,json; print(json.load(sys.stdin).get('__resolveType','?'))"
+```
+
+---
+
+## Integration with `vtexCachedFetch` SWR
+
+Layout caching prevents re-execution of section loaders and CMS resolution for 5 minutes. But the underlying VTEX API calls also benefit from the `vtexCachedFetch` SWR cache (3 min TTL):
+
+```
+Request → Layout cache (5 min TTL)
+  └→ MISS → resolveDecoPage → section loaders
+       └→ vtexCachedFetch → fetchWithCache (3 min TTL)
+            └→ MISS → actual VTEX API call
+```
+
+This means even after the layout cache expires, the underlying API data may still be fresh in the fetch cache. The two caches work together:
+
+| Layer | TTL | Scope |
+|-------|-----|-------|
+| Layout resolution cache | 5 min | Full section output (props + enrichment) |
+| Layout section loader cache | 5 min | Section loader output only |
+| `fetchWithCache` SWR | 3 min | Individual HTTP responses |
+| `cachedLoader` SWR | 30-120s | Commerce loader results |
+
+### Cart Cross-Selling on PLP — Not an Issue
+
+Analysis confirmed that cart drawer cross-selling is **CMS-based** (products configured in admin), not API-based. The Header loader only runs `usePriceSimulationBatch` (a POST, which only runs when `userInfo` cookie exists with a CEP). On first visit without the cookie, no simulation runs at all.
+
+---
+
+## Performance Impact
+
+Before layout caching (variant change on PDP):
+- **~30 VTEX API calls** per navigation (Header shelves × 2 resolutions)
+- **2-3 seconds** delay
+
+After layout caching + `vtexCachedFetch` SWR:
+- **~8 VTEX API calls** on first load (only product-specific: PDP loader, cross-selling, simulation)
+- **~0-2 VTEX API calls** on subsequent navigations (everything served from SWR caches)
+- **<1 second** for cached navigations
+
+---
+
+## Related Skills
+
+| Skill | Purpose |
+|-------|---------|
+| `deco-vtex-fetch-cache` | SWR fetch cache for VTEX APIs (`fetchWithCache`, `vtexCachedFetch`) |
+| `deco-variant-selection-perf` | Eliminate server calls for same-product variant selection |
+| `deco-api-call-dedup` | In-flight deduplication + batching for VTEX API calls |
+| `deco-edge-caching` | Cloudflare edge caching configuration |
+| `deco-cms-route-config` | CMS route configuration in @decocms/start |

package/.cursor/skills/deco-cms-route-config/SKILL.md

@@ -0,0 +1,388 @@
+---
+name: deco-cms-route-config
+description: Configure CMS-driven routes in @decocms/start using cmsRouteConfig, cmsHomeRouteConfig, and admin routes. Covers the catch-all route ($.tsx), homepage route (index.tsx), admin protocol routes (meta, render, invoke), ignoreSearchParams for variant selection, staleTime/gcTime configuration, cache headers, and head/SEO setup. Use when creating a new Deco site, migrating routes from Fresh, or debugging route-level caching issues.
+---
+
+# CMS Route Configuration in @decocms/start
+
+Reusable route configuration factories that live in `@decocms/start/routes`. Sites use thin wrappers that delegate to these factories, keeping route files small and consistent across all Deco sites.
+
+## When to Use This Skill
+
+- Setting up routes for a new Deco TanStack storefront
+- Migrating Fresh routes to TanStack Start
+- Debugging why variant changes trigger server re-fetches
+- Configuring cache headers per page type
+- Setting up admin protocol routes (meta, render, invoke)
+- Understanding the relationship between `loaderDeps`, `staleTime`, and server-side caching
+
+---
+
+## Route Architecture
+
+```
+Site Routes (thin wrappers)          Framework (@decocms/start/routes)
+─────────────────────────           ──────────────────────────────────
+src/routes/$.tsx          ───────→  cmsRouteConfig()
+src/routes/index.tsx      ───────→  cmsHomeRouteConfig()
+src/routes/deco/meta.ts   ───────→  decoMetaRoute
+src/routes/deco/render.ts ───────→  decoRenderRoute
+src/routes/deco/invoke.$.ts ─────→  decoInvokeRoute
+src/routes/__root.tsx     ×         Site-specific (fonts, theme, CSS)
+```
+
+---
+
+## Catch-All CMS Route (`$.tsx`)
+
+The catch-all route handles all CMS-managed pages (PDP, PLP, institutional pages, etc.).
+
+### Site File (minimal)
+
+```typescript
+// src/routes/$.tsx
+import { createFileRoute } from "@tanstack/react-router";
+import { cmsRouteConfig, loadDeferredSection } from "@decocms/start/routes";
+import { DecoPageRenderer } from "@decocms/start/hooks";
+import type { ResolvedSection, DeferredSection } from "@decocms/start/cms";
+import type { CacheProfile } from "@decocms/start/sdk/cacheHeaders";
+import { cacheHeaders, routeCacheDefaults } from "@decocms/start/sdk/cacheHeaders";
+
+const routeConfig = cmsRouteConfig({
+  siteName: "My Store",
+  defaultTitle: "My Store - Default Title",
+  ignoreSearchParams: ["skuId"],
+});
+
+type PageData = {
+  resolvedSections: ResolvedSection[];
+  deferredSections: DeferredSection[];
+  cacheProfile: CacheProfile;
+  name: string;
+  path: string;
+  params: Record<string, string>;
+} | null;
+
+export const Route = createFileRoute("/$")({
+  ...routeCacheDefaults("listing"),
+  loaderDeps: routeConfig.loaderDeps,
+  loader: routeConfig.loader as any,
+  headers: ({ loaderData }) => {
+    const data = loaderData as PageData;
+    return cacheHeaders(data?.cacheProfile ?? "listing");
+  },
+  head: ({ loaderData }) => {
+    const data = loaderData as PageData;
+    return {
+      meta: [
+        {
+          title: data?.name
+            ? `${data.name} | My Store`
+            : "My Store - Default Title",
+        },
+      ],
+    };
+  },
+  component: CmsPage,
+  notFoundComponent: NotFoundPage,
+});
+
+function CmsPage() {
+  const data = Route.useLoaderData() as PageData;
+  const { _splat } = Route.useParams();
+  const actualPath = `/${_splat ?? ""}`;
+
+  if (!data) return <NotFoundPage />;
+
+  return (
+    <DecoPageRenderer
+      sections={data.resolvedSections ?? []}
+      deferredSections={data.deferredSections ?? []}
+      pagePath={actualPath}
+      loadDeferredSectionFn={(d) => loadDeferredSection({ data: d }) as Promise<ResolvedSection | null>}
+    />
+  );
+}
+```
+
+**CRITICAL**: The `...routeCacheDefaults("listing")` spread is essential. Without it, every SPA navigation triggers a full server re-fetch even when the data was just loaded seconds ago. This is the most common cause of perceived slow navigation.
+
+### `cmsRouteConfig` Options
+
+```typescript
+interface CmsRouteOptions {
+  siteName: string;        // Used in page title: "Page Name | siteName"
+  defaultTitle: string;    // Fallback title when CMS page has no name
+  ignoreSearchParams?: string[];  // Search params excluded from loaderDeps
+}
+```
+
+### `ignoreSearchParams` — Critical for Variants
+
+`ignoreSearchParams: ["skuId"]` tells TanStack Router that `?skuId` changes should NOT trigger a loader re-fetch:
+
+```typescript
+loaderDeps: ({ search }) => {
+  const filtered = Object.fromEntries(
+    Object.entries(search ?? {}).filter(([k]) => !ignoreSet.has(k)),
+  );
+  return { search: Object.keys(filtered).length ? filtered : undefined };
+},
+```
+
+The `loader` only sees `deps.search` (which excludes `skuId`), so it builds the CMS path without `?skuId`:
+
+```typescript
+loader: async ({ params, deps }) => {
+  const basePath = "/" + (params._splat || "");
+  const searchStr = deps.search
+    ? "?" + new URLSearchParams(deps.search).toString()
+    : "";
+  return loadCmsPage({ data: basePath + searchStr });
+},
+```
+
+### Cache Headers — Dynamic per Page Type
+
+```typescript
+headers: ({ loaderData }) => {
+  const profile = loaderData?.cacheProfile ?? "listing";
+  return cacheHeaders(profile);
+},
+```
+
+The `cacheProfile` is determined by `detectCacheProfile(basePath)` inside `loadCmsPage`:
+
+| URL Pattern | Profile | Edge TTL |
+|-------------|---------|----------|
+| `*/p` | product | 5 min |
+| `/s`, `?q=` | search | 60s |
+| `/cart`, `/checkout` | private | none |
+| Everything else | listing | 2 min |
+
+### Head/SEO
+
+```typescript
+head: ({ loaderData }) => ({
+  meta: [
+    { title: loaderData?.pageName
+        ? `${loaderData.pageName} | ${siteName}`
+        : defaultTitle },
+  ],
+}),
+```
+
+---
+
+## Homepage Route (`index.tsx`)
+
+Hardcoded to `/` path — no params, no deps.
+
+### Site File
+
+```typescript
+// src/routes/index.tsx
+import { createFileRoute } from "@tanstack/react-router";
+import { cmsHomeRouteConfig, loadDeferredSection } from "@decocms/start/routes";
+import { DecoPageRenderer } from "@decocms/start/hooks";
+import type { ResolvedSection, DeferredSection } from "@decocms/start/cms";
+
+const homeConfig = cmsHomeRouteConfig({
+  defaultTitle: "My Store - Homepage",
+});
+
+type HomeData = {
+  resolvedSections: ResolvedSection[];
+  deferredSections: DeferredSection[];
+} | null;
+
+export const Route = createFileRoute("/")({
+  ...homeConfig,
+  component: HomePage,
+});
+
+function HomePage() {
+  const data = Route.useLoaderData() as HomeData;
+  if (!data) return null;
+
+  return (
+    <DecoPageRenderer
+      sections={data.resolvedSections ?? []}
+      deferredSections={data.deferredSections ?? []}
+      pagePath="/"
+      loadDeferredSectionFn={(d) => loadDeferredSection({ data: d }) as Promise<ResolvedSection | null>}
+    />
+  );
+}
+```
+
+`cmsHomeRouteConfig` already includes `routeCacheDefaults("static")` and `cacheHeaders("static")`, giving the homepage a 5-min client staleTime and 24h edge TTL. Do NOT add additional cache config.
+
+### `cmsHomeRouteConfig` Options
+
+```typescript
+interface CmsHomeRouteOptions {
+  defaultTitle: string;
+}
+```
+
+---
+
+## Admin Protocol Routes
+
+These routes enable the Deco CMS admin (admin.deco.cx) to communicate with the storefront:
+
+### Meta Route — Schema & Manifest
+
+```typescript
+// src/routes/deco/meta.ts
+import { createFileRoute } from "@tanstack/react-router";
+import { decoMetaRoute } from "@decocms/start/routes";
+
+export const Route = createFileRoute("/deco/meta")({
+  ...decoMetaRoute,
+});
+```
+
+### Render Route — Section Preview
+
+```typescript
+// src/routes/deco/render.ts
+import { createFileRoute } from "@tanstack/react-router";
+import { decoRenderRoute } from "@decocms/start/routes";
+
+export const Route = createFileRoute("/deco/render")({
+  ...decoRenderRoute,
+});
+```
+
+### Invoke Route — Loader/Action Execution
+
+```typescript
+// src/routes/deco/invoke.$.ts
+import { createFileRoute } from "@tanstack/react-router";
+import { decoInvokeRoute } from "@decocms/start/routes";
+
+export const Route = createFileRoute("/deco/invoke/$")({
+  ...decoInvokeRoute,
+});
+```
+
+### Important: Use Spread Operator
+
+Always use `{ ...frameworkRoute }` — NOT `createFileRoute("/path")(frameworkRoute)`:
+
+```typescript
+// BAD — "Route cannot have both an 'id' and a 'path' option"
+export const Route = createFileRoute("/deco/meta")(decoMetaRoute);
+
+// GOOD — spread into new object
+export const Route = createFileRoute("/deco/meta")({ ...decoMetaRoute });
+```
+
+TanStack Router injects internal properties (`id`, `path`) that conflict if the config object already has them.
+
+---
+
+## Framework Exports
+
+```typescript
+// @decocms/start/routes
+export {
+  cmsRouteConfig,        // Catch-all CMS route config factory
+  cmsHomeRouteConfig,    // Homepage route config factory
+  loadCmsPage,           // Server function for CMS page resolution
+  loadCmsHomePage,       // Server function for homepage resolution
+  type CmsRouteOptions,
+  CmsPage,              // Generic CMS page component
+  NotFoundPage,         // Generic 404 component
+  decoMetaRoute,        // Admin meta route config
+  decoRenderRoute,      // Admin render route config
+  decoInvokeRoute,      // Admin invoke route config
+};
+```
+
+Add to `package.json` exports:
+```json
+{
+  "exports": {
+    "./routes": "./src/routes/index.ts"
+  }
+}
+```
+
+---
+
+## Common Errors
+
+### `Cannot find module '@decocms/start/routes'`
+
+TypeScript server needs restart after adding new exports to `package.json`. In VSCode/Cursor:
+- Cmd+Shift+P → "TypeScript: Restart TS Server"
+- Or restart the dev server
+
+### `Route cannot have both an 'id' and a 'path' option`
+
+Use spread: `{ ...decoMetaRoute }` instead of direct assignment.
+
+### `Property 'resolvedSections' does not exist on type 'never'`
+
+TypeScript inference limitation with `createServerFn` + `useLoaderData()`. The `page` could be `null`. Add a null check:
+
+```typescript
+function CmsPage() {
+  const page = Route.useLoaderData();
+  if (!page) return <NotFoundPage />;
+  return <DecoPageRenderer sections={page.resolvedSections} />;
+}
+```
+
+### Root Route (`__root.tsx`) — Keep Site-Specific
+
+The root route contains site-specific elements that should NOT be in the framework:
+- HTML lang attribute
+- Favicon
+- CSS stylesheet imports
+- Font loading
+- Theme configuration
+- QueryClient setup
+
+---
+
+## `staleTime` / `gcTime` Configuration
+
+### Production
+
+Set by `routeCacheDefaults(profile)` based on page type (from `cacheHeaders.ts`):
+
+| Profile | staleTime | gcTime |
+|---------|-----------|--------|
+| static | 5 min | 30 min |
+| product | 1 min | 5 min |
+| listing | 1 min | 5 min |
+| search | 30s | 2 min |
+| cart | 0 | 0 |
+| private | 0 | 0 |
+| none | 0 | 0 |
+
+### Development
+
+`staleTime: 5_000` (5 seconds) — not zero!
+
+With `staleTime: 0`, TanStack Router re-fetches on every navigation even if `loaderDeps` returns identical deps. This causes:
+- Double-fetch on variant changes (despite `ignoreSearchParams`)
+- Prefetch + click = 2 server calls
+
+Setting 5s staleTime allows rapid interactions (variant clicks, back/forward) to use cached data while still reflecting changes within a few seconds.
+
+---
+
+## Related Skills
+
+| Skill | Purpose |
+|-------|---------|
+| `deco-variant-selection-perf` | Variant selection optimization using replaceState |
+| `deco-cms-layout-caching` | Layout section caching in CMS resolve |
+| `deco-edge-caching` | Cloudflare edge caching with workerEntry |
+| `deco-tanstack-storefront-patterns` | General storefront patterns |
+| `deco-start-architecture` | Full @decocms/start architecture reference |