@decocms/start 0.19.0 → 0.20.2

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

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

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

@@ -181,116 +181,6 @@ 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
@@ -298,8 +188,6 @@ When migrating to TanStack Workers, compare cache metrics:
 - **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/.github/workflows/release.yml

@@ -6,7 +6,7 @@ on:
 
 permissions:
   contents: write
-  packages: write
+  id-token: write
   issues: write
   pull-requests: write
 
@@ -23,10 +23,11 @@ jobs:
           node-version: 22
           registry-url: https://registry.npmjs.org
 
+      - run: npm install -g npm@latest
+
       - run: npm install
 
       - name: Release
         run: npx semantic-release
         env:
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
-          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}

package/.releaserc.json

@@ -15,7 +15,10 @@
       ]
     }],
     "@semantic-release/release-notes-generator",
-    "@semantic-release/npm",
+    ["@semantic-release/exec", {
+      "prepareCmd": "npm version ${nextRelease.version} --no-git-tag-version",
+      "publishCmd": "npm publish --access public"
+    }],
     "@semantic-release/github",
     ["@semantic-release/git", {
       "assets": ["package.json"],

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@decocms/start",
-  "version": "0.19.0",
+  "version": "0.20.2",
   "type": "module",
   "description": "Deco framework for TanStack Start - CMS bridge, admin protocol, hooks, schema generation",
   "main": "./src/index.ts",
@@ -76,6 +76,7 @@
   },
   "devDependencies": {
     "@biomejs/biome": "^2.4.6",
+    "@semantic-release/exec": "^7.1.0",
     "@semantic-release/git": "^10.0.1",
     "@tanstack/store": "^0.9.1",
     "@types/react": "^19.0.0",