@decocms/start 0.23.1 → 0.24.1

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

@@ -41,41 +41,72 @@ The catch-all route handles all CMS-managed pages (PDP, PLP, institutional pages
 
 ```typescript
 // src/routes/$.tsx
-import { createFileRoute, notFound } from "@tanstack/react-router";
-import { cmsRouteConfig, NotFoundPage } from "@decocms/start/routes";
+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 config = cmsRouteConfig({
+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("/$")({
-  loaderDeps: config.loaderDeps,
-  loader: async (ctx) => {
-    const page = await config.loader(ctx);
-    if (!page) throw notFound();
-    return page;
+  ...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,
-  staleTime: config.staleTime,
-  gcTime: config.gcTime,
-  headers: config.headers,
-  head: config.head,
 });
 
 function CmsPage() {
-  const page = Route.useLoaderData();
+  const data = Route.useLoaderData() as PageData;
+  const { _splat } = Route.useParams();
+  const actualPath = `/${_splat ?? ""}`;
+
+  if (!data) return <NotFoundPage />;
+
   return (
-    <div>
-      <DecoPageRenderer sections={page.resolvedSections} />
-    </div>
+    <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
@@ -152,27 +183,41 @@ Hardcoded to `/` path — no params, no deps.
 ```typescript
 // src/routes/index.tsx
 import { createFileRoute } from "@tanstack/react-router";
-import { cmsHomeRouteConfig } from "@decocms/start/routes";
+import { cmsHomeRouteConfig, loadDeferredSection } from "@decocms/start/routes";
 import { DecoPageRenderer } from "@decocms/start/hooks";
+import type { ResolvedSection, DeferredSection } from "@decocms/start/cms";
 
-const config = cmsHomeRouteConfig({
+const homeConfig = cmsHomeRouteConfig({
   defaultTitle: "My Store - Homepage",
 });
 
+type HomeData = {
+  resolvedSections: ResolvedSection[];
+  deferredSections: DeferredSection[];
+} | null;
+
 export const Route = createFileRoute("/")({
-  ...config,
+  ...homeConfig,
   component: HomePage,
 });
 
 function HomePage() {
-  const page = Route.useLoaderData();
-  if (!page) {
-    return <div>Loading...</div>;
-  }
-  return <DecoPageRenderer sections={page.resolvedSections} />;
+  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
@@ -308,15 +353,17 @@ The root route contains site-specific elements that should NOT be in the framewo
 
 ### Production
 
-Set by `routeCacheDefaults(profile)` based on page type:
+Set by `routeCacheDefaults(profile)` based on page type (from `cacheHeaders.ts`):
 
 | Profile | staleTime | gcTime |
 |---------|-----------|--------|
 | static | 5 min | 30 min |
-| product | 5 min | 30 min |
-| listing | 2 min | 10 min |
-| search | 60s | 5 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
 

package/.cursor/skills/deco-edge-caching/SKILL.md

@@ -181,6 +181,116 @@ const cachedPLP = createCachedLoader("vtex/plp", vtexPLP, {
 
 This is per-isolate in-memory cache (V8 Map). Resets on cold start. Includes request deduplication (single-flight) and LRU eviction at 500 entries.
 
+## Cache Versioning with BUILD_HASH
+
+Deploy-time cache busting uses a `BUILD_HASH` environment variable (typically the git short SHA) passed to `wrangler deploy`. The worker-entry appends this to cache keys so deploying a new version automatically serves fresh content.
+
+```yaml
+# .github/workflows/deploy.yml
+- name: Deploy to Cloudflare Workers
+  run: npx wrangler deploy
+  env:
+    BUILD_HASH: ${{ github.sha }}
+```
+
+The worker-entry reads `env.BUILD_HASH` and injects it into cache keys. On new deploys, old cache entries simply expire naturally — no purge needed.
+
+## Site-Level Cache Pattern Registration
+
+For sites with known institutional/static pages that would otherwise get the conservative 2-min "listing" TTL, register explicit patterns in `setup.ts`:
+
+```ts
+// setup.ts
+import { registerCachePattern } from "@decocms/start/sdk/cacheHeaders";
+
+// Institutional pages — content changes rarely, promote to 24h edge TTL
+registerCachePattern({
+  test: (p) =>
+    p.startsWith("/institucional") ||
+    p.startsWith("/central-de-atendimento") ||
+    p.startsWith("/politica-de-") ||
+    p.startsWith("/termos-") ||
+    p === "/fale-conosco" ||
+    p === "/trabalhe-conosco" ||
+    p === "/cadastro" ||
+    p === "/televendas",
+  profile: "static",
+});
+
+// Promotional/collection pages — already listing-like, but explicit is better
+registerCachePattern({
+  test: (p) =>
+    p.startsWith("/ofertas") ||
+    p.startsWith("/b/") ||
+    p.startsWith("/festival-"),
+  profile: "listing",
+});
+```
+
+Custom patterns are evaluated before built-in ones. This is the recommended way to tune caching per-site without modifying the framework.
+
+## Client-Side Route Caching (routeCacheDefaults)
+
+Without `routeCacheDefaults`, every SPA navigation triggers a fresh server request even if the data was just loaded. This is the most common cause of "slow navigation" reports.
+
+The catch-all route `$.tsx` MUST include `routeCacheDefaults`:
+
+```ts
+export const Route = createFileRoute("/$")({
+  ...routeCacheDefaults("listing"),   // <-- client-side cache: 1min stale, 5min gc
+  loaderDeps: routeConfig.loaderDeps,
+  loader: routeConfig.loader,
+  headers: ({ loaderData }) => {
+    return cacheHeaders(loaderData?.cacheProfile ?? "listing");
+  },
+  component: CmsPage,
+});
+```
+
+The homepage should use `cmsHomeRouteConfig` which already includes `routeCacheDefaults("static")`:
+
+```ts
+export const Route = createFileRoute("/")({
+  ...cmsHomeRouteConfig({ defaultTitle: "My Store" }),
+  component: HomePage,
+});
+```
+
+## Cache Analysis & Debugging with Stats Lake
+
+Deco sites emit CDN usage data to a ClickHouse stats-lake. This enables cache performance analysis:
+
+```sql
+-- Cache status breakdown for a site
+SELECT
+  JSONExtractString(extra, 'cacheStatus') AS cache_status,
+  count() AS requests,
+  round(count() * 100.0 / sum(count()) OVER (), 2) AS pct
+FROM fact_usage_daily
+WHERE site_id = <site_id>
+  AND date >= today() - 7
+GROUP BY cache_status
+ORDER BY requests DESC;
+```
+
+### Understanding "unknown" Cache Status
+
+When the Cloudflare Worker uses `caches.default.match()/put()` to serve cached responses internally, the outer CDN reports `cf-cache-status: DYNAMIC` because the Worker is the origin. The stats-lake logs this as "unknown" or empty.
+
+This means a high "unknown" percentage does NOT indicate a caching problem — it means the Worker's internal Cache API is handling the request before it reaches the origin CDN layer. This is expected and desirable behavior.
+
+To verify actual cache performance:
+1. Check `X-Cache: HIT|MISS` header (set by the worker-entry)
+2. Check `X-Cache-Profile` header (shows which profile was detected)
+3. Query stats-lake grouping by `cacheStatus` AND response status codes
+
+### Comparing Staging vs Production Cache
+
+When migrating to TanStack Workers, compare cache metrics:
+- Production (Deno/Fresh on Kubernetes) typically shows high HIT rates because traffic volume keeps caches warm
+- Staging Workers may show lower HIT rates due to lower traffic, plus "unknown" status from internal Cache API
+- The "unknown" requests on Workers are functionally equivalent to HITs — they're served from the Worker's Cache API without hitting the origin server function
+
 ## Key Constraints
 
 - **Cache API ignores `s-maxage`** — the factory uses `max-age` equal to `sMaxAge` when storing in Cache API
@@ -188,6 +298,8 @@ This is per-isolate in-memory cache (V8 Map). Resets on cold start. Includes req
 - **Device keys add a query param** — `__cf_device=mobile|desktop` is appended to cache keys, so purging must clear both
 - **Non-200 responses are never cached** — only 200 OK goes into Cache API
 - **`/_server` paths always bypass cache** — TanStack Start RPC requests are never edge-cached
+- **UTM parameters are stripped** — `utm_*`, `gclid`, `fbclid` are removed from cache keys to improve hit rates
+- **Segment hashing** — user segments (from matchers/flags) are hashed into the cache key so different audiences get different cached responses
 
 ## Package Exports
 

package/package.json

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

package/src/admin/invoke.ts

@@ -126,6 +126,13 @@ export async function handleInvoke(request: Request): Promise<Response> {
 
     try {
       const result = await found.handler(body, request);
+      // Response passthrough: if the loader/action returns a Response object,
+      // forward it as-is (preserving headers like Set-Cookie). This matches
+      // deco-cx/deco's invokeToHttpResponse behavior where auth loaders return
+      // Response objects with Set-Cookie headers for HttpOnly cookies.
+      if (result instanceof Response) {
+        return result;
+      }
       const filtered = selectFields(result, select);
       return new Response(JSON.stringify(filtered), { status: 200, headers: JSON_HEADERS });
     } catch (error) {
@@ -145,7 +152,13 @@ export async function handleInvoke(request: Request): Promise<Response> {
 
         if (found) {
           try {
-            const result = await found.handler(payload, request);
+            let result = await found.handler(payload, request);
+            // If a loader returns a Response, extract its JSON body for batching.
+            // Set-Cookie headers from batch items are not forwarded individually
+            // (use single invoke for auth loaders that need cookie passthrough).
+            if (result instanceof Response) {
+              try { result = await result.json(); } catch { result = null; }
+            }
             results[key] = selectFields(result, select);
           } catch (error) {
             results[key] = { error: (error as Error).message };

package/src/sdk/workerEntry.ts

@@ -69,6 +69,13 @@ export interface SegmentKey {
   loggedIn?: boolean;
   /** Commerce sales channel / price list. */
   salesChannel?: string;
+  /**
+   * VTEX region ID for regionalized pricing/availability.
+   * When present, cache entries are segmented per region.
+   * Sites without regionalization should omit this field
+   * to avoid unnecessary cache fragmentation.
+   */
+  regionId?: string;
   /** Sorted list of active A/B flag names for cache cohort splitting. */
   flags?: string[];
 }
@@ -128,6 +135,10 @@ export interface DecoWorkerEntryOptions {
    *       device: /mobile|android|iphone/i.test(request.headers.get("user-agent") ?? "") ? "mobile" : "desktop",
    *       loggedIn: vtx.isLoggedIn,
    *       salesChannel: vtx.salesChannel,
+   *       // Include regionId only if the site uses VTEX regionalization.
+   *       // When present, cache entries split by region; omit it for
+   *       // non-regionalized sites to maximize cache sharing.
+   *       regionId: vtx.regionId ?? undefined,
    *     };
    *   },
    * });
@@ -366,6 +377,7 @@ export function createDecoWorkerEntry(
     const parts: string[] = [seg.device];
     if (seg.loggedIn) parts.push("auth");
     if (seg.salesChannel) parts.push(`sc=${seg.salesChannel}`);
+    if (seg.regionId) parts.push(`r=${seg.regionId}`);
     if (seg.flags?.length) parts.push(`f=${seg.flags.sort().join(",")}`);
     return parts.join("|");
   }
@@ -415,6 +427,32 @@ export function createDecoWorkerEntry(
 
   // -- Purge handler ----------------------------------------------------------
 
+  interface PurgeRequestBody {
+    paths?: string[];
+    countries?: string[];
+    /** Sales channels to include in segment combos. Defaults to ["1"]. */
+    salesChannels?: string[];
+    /** Region IDs to include in segment combos. Each ID generates additional entries. */
+    regionIds?: string[];
+  }
+
+  function buildPurgeSegments(body: PurgeRequestBody): SegmentKey[] {
+    const devices: Array<"mobile" | "desktop"> = ["mobile", "desktop"];
+    const channels = body.salesChannels ?? ["1"];
+    const regions: Array<string | undefined> = [undefined, ...(body.regionIds ?? [])];
+
+    const segments: SegmentKey[] = [];
+    for (const device of devices) {
+      for (const salesChannel of channels) {
+        for (const regionId of regions) {
+          segments.push({ device, salesChannel, regionId });
+        }
+      }
+      segments.push({ device });
+    }
+    return segments;
+  }
+
   async function handlePurge(request: Request, env: Record<string, unknown>): Promise<Response> {
     if (purgeTokenEnv === false) {
       return new Response("Purge disabled", { status: 404 });
@@ -425,7 +463,7 @@ export function createDecoWorkerEntry(
       return new Response("Unauthorized", { status: 401 });
     }
 
-    let body: { paths?: string[]; countries?: string[] };
+    let body: PurgeRequestBody;
     try {
       body = await request.json();
     } catch {
@@ -437,10 +475,6 @@ export function createDecoWorkerEntry(
       return new Response('Body must include "paths": ["/", "/page"]', { status: 400 });
     }
 
-    // Geo strings to purge location-specific cache variants.
-    // Pass ["BR", "BR|São Paulo|Curitiba", ...] to purge specific geo variants.
-    // Each string must match the __cf_geo param format: "country|region|city".
-    // When omitted, only the non-geo cache entry is purged.
     const geoVariants = body.countries ?? [];
 
     const cache =
@@ -455,25 +489,18 @@ export function createDecoWorkerEntry(
     const baseUrl = new URL(request.url).origin;
     const purged: string[] = [];
 
-    // If using segment-based keys, purge requires known segment combos.
-    // For simplicity, purge common combos: both devices, default sales channel.
-    const segments: SegmentKey[] = buildSegment
-      ? [
-          { device: "mobile" },
-          { device: "desktop" },
-          { device: "mobile", salesChannel: "1" },
-          { device: "desktop", salesChannel: "1" },
-        ]
-      : [];
-
-    // Purge both without geo (non-geo-targeted) and with each specified geo variant
     const geoKeys: (string | null)[] = [null, ...geoVariants];
 
     for (const p of paths) {
-      if (buildSegment && segments.length > 0) {
+      if (buildSegment) {
+        const segments = buildPurgeSegments(body);
         for (const seg of segments) {
           for (const cc of geoKeys) {
             const url = new URL(p, baseUrl);
+            if (cacheVersionEnv !== false) {
+              const version = (env[cacheVersionEnv] as string) || "";
+              if (version) url.searchParams.set("__v", version);
+            }
             url.searchParams.set("__seg", hashSegment(seg));
             if (cc) url.searchParams.set("__cf_geo", cc);
             const key = new Request(url.toString(), { method: "GET" });
@@ -493,6 +520,10 @@ export function createDecoWorkerEntry(
         for (const device of devices) {
           for (const cc of geoKeys) {
             const url = new URL(p, baseUrl);
+            if (cacheVersionEnv !== false) {
+              const version = (env[cacheVersionEnv] as string) || "";
+              if (version) url.searchParams.set("__v", version);
+            }
             if (device) url.searchParams.set("__cf_device", device);
             if (cc) url.searchParams.set("__cf_geo", cc);
             const key = new Request(url.toString(), { method: "GET" });
@@ -643,16 +674,22 @@ export function createDecoWorkerEntry(
         const origin = await serverEntry.fetch(request, env, ctx);
         const profile = getProfile(url);
 
-        // If the profile is private/none/cart, strip any public cache headers
-        // the route may have set (prevents the search caching bug)
         if (profile === "private" || profile === "none" || profile === "cart") {
           const resp = new Response(origin.body, origin);
           resp.headers.set("Cache-Control", "private, no-cache, no-store, must-revalidate");
           resp.headers.delete("CDN-Cache-Control");
+          resp.headers.set("X-Cache", "BYPASS");
+          resp.headers.set("X-Cache-Reason", `non-cacheable:${profile}`);
           return resp;
         }
 
-        return origin;
+        const resp = new Response(origin.body, origin);
+        const reason = request.method !== "GET"
+          ? `method:${request.method}`
+          : "bypass-path";
+        resp.headers.set("X-Cache", "BYPASS");
+        resp.headers.set("X-Cache-Reason", reason);
+        return resp;
       }
 
       // Cacheable request — build segment-aware cache key
@@ -696,7 +733,10 @@ export function createDecoWorkerEntry(
       const origin = await serverEntry.fetch(request, env, ctx);
 
       if (origin.status !== 200) {
-        return origin;
+        const resp = new Response(origin.body, origin);
+        resp.headers.set("X-Cache", "BYPASS");
+        resp.headers.set("X-Cache-Reason", `status:${origin.status}`);
+        return resp;
       }
 
       // Responses with Set-Cookie must never be cached — they carry
@@ -717,10 +757,11 @@ export function createDecoWorkerEntry(
       const profile = getProfile(url);
       const profileConfig = getCacheProfileConfig(profile);
 
-      // Don't cache non-public profiles
       if (!profileConfig.isPublic || profileConfig.sMaxAge === 0) {
         const resp = new Response(origin.body, origin);
         resp.headers.set("Cache-Control", "private, no-cache, no-store, must-revalidate");
+        resp.headers.set("X-Cache", "BYPASS");
+        resp.headers.set("X-Cache-Reason", `profile:${profile}`);
         return resp;
       }