@decocms/tanstack 7.22.0 → 7.22.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@decocms/tanstack",
-  "version": "7.22.0",
+  "version": "7.22.2",
   "type": "module",
   "description": "Deco framework binding for TanStack Start + Cloudflare Workers",
   "repository": {
@@ -24,9 +24,9 @@
     "lint:unused": "knip"
   },
   "dependencies": {
-    "@decocms/blocks": "7.22.0",
-    "@decocms/blocks-admin": "7.22.0",
-    "@decocms/blocks-cli": "7.22.0",
+    "@decocms/blocks": "7.22.2",
+    "@decocms/blocks-admin": "7.22.2",
+    "@decocms/blocks-cli": "7.22.2",
     "@deco-cx/warp-node": "^0.3.16",
     "fast-json-patch": "^3.1.0",
     "ws": "^8.18.0"

package/src/routes/cmsRoute.test.ts

@@ -1,7 +1,44 @@
 import { registerCacheableSections, registerSectionLoader } from "@decocms/blocks/cms";
 import type { ResolvedSection } from "@decocms/blocks/cms";
 import { describe, expect, it } from "vitest";
-import { runSectionLoadersWithSeo } from "./cmsRoute";
+import {
+  parseLoadCmsHomePageInput,
+  parseLoadCmsPageInput,
+  runSectionLoadersWithSeo,
+} from "./cmsRoute";
+
+describe("parseLoadCmsPageInput (#292)", () => {
+  it("treats a bare string as the path with resolveGlobals defaulting to true (back-compat)", () => {
+    expect(parseLoadCmsPageInput("/produto/tenis")).toEqual({
+      path: "/produto/tenis",
+      resolveGlobals: true,
+    });
+  });
+
+  it("accepts { path, resolveGlobals } and preserves an explicit false", () => {
+    expect(parseLoadCmsPageInput({ path: "/produto/tenis", resolveGlobals: false })).toEqual({
+      path: "/produto/tenis",
+      resolveGlobals: false,
+    });
+  });
+
+  it("defaults resolveGlobals to true when omitted from the object form", () => {
+    expect(parseLoadCmsPageInput({ path: "/produto/tenis" })).toEqual({
+      path: "/produto/tenis",
+      resolveGlobals: true,
+    });
+  });
+});
+
+describe("parseLoadCmsHomePageInput (#292)", () => {
+  it("defaults resolveGlobals to true when called with no data (back-compat)", () => {
+    expect(parseLoadCmsHomePageInput(undefined)).toEqual({ resolveGlobals: true });
+  });
+
+  it("preserves an explicit resolveGlobals: false", () => {
+    expect(parseLoadCmsHomePageInput({ resolveGlobals: false })).toEqual({ resolveGlobals: false });
+  });
+});
 
 /**
  * Regression guard for #355: body sections and the SEO section used to be

package/src/routes/cmsRoute.ts

@@ -62,6 +62,7 @@ import { normalizeUrlsInObject } from "@decocms/blocks/sdk/normalizeUrls";
 import { type Device, detectDevice } from "@decocms/blocks/sdk/useDevice";
 import { derivePageUrl, isClientNavigation } from "./pageUrl";
 import { dedupeGlobals, resolveSiteGlobals } from "./withSiteGlobals";
+import type { SiteGlobalRef } from "./withSiteGlobals";
 
 const isServer = typeof document === "undefined";
 
@@ -85,6 +86,12 @@ export function setSectionChunkMap(map: Record<string, string>): void {
 type PageResult = Awaited<ReturnType<typeof loadCmsPageInternal>>;
 const pageInflight = new Map<string, Promise<PageResult>>();
 
+/** Same shape as `resolveSiteGlobals()`'s empty result — used when `resolveGlobals: false`. */
+const EMPTY_GLOBALS: { resolvedSections: ResolvedSection[]; rawRefs: SiteGlobalRef[] } = {
+  resolvedSections: [],
+  rawRefs: [],
+};
+
 /** One year — the cohort is sticky; the `pct` fingerprint handles re-rolls. */
 const SEGMENT_COOKIE_MAX_AGE = 60 * 60 * 24 * 365;
 
@@ -154,7 +161,7 @@ export async function runSectionLoadersWithSeo(
   };
 }
 
-async function loadCmsPageInternal(fullPath: string) {
+async function loadCmsPageInternal(fullPath: string, resolveGlobals: boolean) {
   const [basePath] = fullPath.split("?");
   // On client-side navigation getRequestUrl() is the /_serverFn/... endpoint,
   // not the page being loaded — derivePageUrl rebuilds the real page URL so
@@ -188,7 +195,7 @@ async function loadCmsPageInternal(fullPath: string) {
   // empty client-bundled `blocks.gen.ts`.
   const [{ enrichedSections, enrichedSeoSection }, globals] = await Promise.all([
     runSectionLoadersWithSeo(page.resolvedSections, page.seoSection, request),
-    resolveSiteGlobals(),
+    resolveGlobals ? resolveSiteGlobals() : Promise.resolve(EMPTY_GLOBALS),
   ]);
 
   // Page sections take precedence over globals — dedupe drops any global
@@ -228,10 +235,20 @@ async function loadCmsPageInternal(fullPath: string) {
   };
 }
 
+/** Accepted by `loadCmsPage` — a bare path (back-compat) or `{ path, resolveGlobals }`. */
+export type LoadCmsPageInput = string | { path: string; resolveGlobals?: boolean };
+
+/** @internal exported for tests */
+export function parseLoadCmsPageInput(data: unknown): { path: string; resolveGlobals: boolean } {
+  if (typeof data === "string") return { path: data, resolveGlobals: true };
+  const obj = data as { path: string; resolveGlobals?: boolean };
+  return { path: obj.path, resolveGlobals: obj.resolveGlobals ?? true };
+}
+
 export const loadCmsPage = createServerFn({ method: "GET" })
-  .inputValidator((data: unknown) => data as string)
+  .inputValidator((data: unknown) => data as LoadCmsPageInput)
   .handler(async (ctx) => {
-    const fullPath = ctx.data;
+    const { path: fullPath, resolveGlobals } = parseLoadCmsPageInput(ctx.data);
 
     // Use the full path (including query string) as the dedup key.
     // Using basePath only caused /s?q=a and /s?q=b to share one promise,
@@ -241,67 +258,84 @@ export const loadCmsPage = createServerFn({ method: "GET" })
     // for the same path may carry deferredSections; sharing that promise with a
     // concurrent SPA transition would smuggle those deferred sections in, causing
     // loadDeferredSection to run without the per-request commerce app context.
-    // Use separate dedup buckets for SSR vs client-nav.
+    // Use separate dedup buckets for SSR vs client-nav. `resolveGlobals` is also
+    // part of the key — otherwise a `resolveGlobals: false` request could return
+    // (or share a promise with) a `resolveGlobals: true` response for the same path.
     const clientNav = isClientNavigation(fullPath, getRequestUrl());
-    const inflightKey = clientNav ? `__nav:${fullPath}` : fullPath;
+    const inflightKey =
+      (clientNav ? `__nav:${fullPath}` : fullPath) + (resolveGlobals ? "" : "|noGlobals");
     const existing = pageInflight.get(inflightKey);
     if (existing) return existing;
 
-    const promise = loadCmsPageInternal(fullPath).finally(() => pageInflight.delete(inflightKey));
+    const promise = loadCmsPageInternal(fullPath, resolveGlobals).finally(() =>
+      pageInflight.delete(inflightKey),
+    );
     pageInflight.set(inflightKey, promise);
     return promise;
   });
 
+/** Accepted by `loadCmsHomePage` — optional so existing no-arg callers keep working. */
+export type LoadCmsHomePageInput = { resolveGlobals?: boolean } | undefined;
+
+/** @internal exported for tests */
+export function parseLoadCmsHomePageInput(data: unknown): { resolveGlobals: boolean } {
+  const obj = (data ?? {}) as { resolveGlobals?: boolean };
+  return { resolveGlobals: obj.resolveGlobals ?? true };
+}
+
 /**
  * Same as loadCmsPage but hardcoded to "/" path.
  * Avoids passing data through the server function for the homepage.
  */
-export const loadCmsHomePage = createServerFn({ method: "GET" }).handler(async () => {
-  const request = getRequest();
-  const ua = getRequestHeader("user-agent") ?? "";
-  const serverUrl = getRequestUrl();
-  const matcherCtx: MatcherContext = {
-    userAgent: ua,
-    url: serverUrl.toString(),
-    path: "/",
-    cookies: getCookies(),
-    request,
-    isClientNavigation: isClientNavigation("/", serverUrl),
-    flags: [],
-  };
-  const page = await resolveDecoPage("/", matcherCtx);
-  if (!page) return null;
-  const flags = persistFlags(matcherCtx);
-  const [{ enrichedSections, enrichedSeoSection }, globals] = await Promise.all([
-    runSectionLoadersWithSeo(page.resolvedSections, page.seoSection, request),
-    resolveSiteGlobals(),
-  ]);
-
-  const mergedSections: ResolvedSection[] = [
-    ...dedupeGlobals(globals.resolvedSections, enrichedSections),
-    ...enrichedSections,
-  ];
-
-  const eagerKeys = mergedSections.map((s) => s.component);
-  await preloadSectionComponents(eagerKeys);
-
-  const device = detectDevice(ua);
-  const seo = buildPageSeo(page.seoSection, enrichedSeoSection, mergedSections);
-
-  const { seoSection: _seo, ...pageData } = page;
-
-  return {
-    ...pageData,
-    resolvedSections: normalizeUrlsInObject(mergedSections),
-    deferredSections: normalizeUrlsInObject(page.deferredSections),
-    pagePath: "/",
-    pageUrl: serverUrl.toString(),
-    seo,
-    device,
-    flags,
-    siteGlobals: { rawRefs: globals.rawRefs },
-  };
-});
+export const loadCmsHomePage = createServerFn({ method: "GET" })
+  .inputValidator((data: unknown) => data as LoadCmsHomePageInput)
+  .handler(async (ctx) => {
+    const { resolveGlobals } = parseLoadCmsHomePageInput(ctx.data);
+    const request = getRequest();
+    const ua = getRequestHeader("user-agent") ?? "";
+    const serverUrl = getRequestUrl();
+    const matcherCtx: MatcherContext = {
+      userAgent: ua,
+      url: serverUrl.toString(),
+      path: "/",
+      cookies: getCookies(),
+      request,
+      isClientNavigation: isClientNavigation("/", serverUrl),
+      flags: [],
+    };
+    const page = await resolveDecoPage("/", matcherCtx);
+    if (!page) return null;
+    const flags = persistFlags(matcherCtx);
+    const [{ enrichedSections, enrichedSeoSection }, globals] = await Promise.all([
+      runSectionLoadersWithSeo(page.resolvedSections, page.seoSection, request),
+      resolveGlobals ? resolveSiteGlobals() : Promise.resolve(EMPTY_GLOBALS),
+    ]);
+
+    const mergedSections: ResolvedSection[] = [
+      ...dedupeGlobals(globals.resolvedSections, enrichedSections),
+      ...enrichedSections,
+    ];
+
+    const eagerKeys = mergedSections.map((s) => s.component);
+    await preloadSectionComponents(eagerKeys);
+
+    const device = detectDevice(ua);
+    const seo = buildPageSeo(page.seoSection, enrichedSeoSection, mergedSections);
+
+    const { seoSection: _seo, ...pageData } = page;
+
+    return {
+      ...pageData,
+      resolvedSections: normalizeUrlsInObject(mergedSections),
+      deferredSections: normalizeUrlsInObject(page.deferredSections),
+      pagePath: "/",
+      pageUrl: serverUrl.toString(),
+      seo,
+      device,
+      flags,
+      siteGlobals: { rawRefs: globals.rawRefs },
+    };
+  });
 
 // ---------------------------------------------------------------------------
 // Deferred section loader — resolves + enriches a single section on demand
@@ -448,6 +482,16 @@ export interface CmsRouteOptions {
    * - `false`: Everything runs on client only.
    */
   ssr?: boolean | "data-only";
+  /**
+   * Resolve `site.theme + site.global + site.pageSections` (the CMS `Site`
+   * block) and merge them into every page's sections.
+   *
+   * Default: `true`. Set to `false` to restore pre-6.7.4 behavior for sites
+   * that don't use the `Site` block and don't want it silently activated
+   * (see #292) — this also skips the `Theme` section's `<style>` injection,
+   * so the site's own `:root` CSS fallbacks apply instead.
+   */
+  resolveGlobals?: boolean;
 }
 
 type CmsPageLoaderData = {
@@ -658,6 +702,7 @@ export function cmsRouteConfig(options: CmsRouteOptions) {
     pendingMs = 200,
     pendingMinMs = 300,
     ssr: ssrMode,
+    resolveGlobals,
   } = options;
 
   const ignoreSet = new Set(ignoreSearchParams);
@@ -689,7 +734,9 @@ export function cmsRouteConfig(options: CmsRouteOptions) {
       const searchStr = deps.search
         ? "?" + new URLSearchParams(deps.search as Record<string, string>).toString()
         : "";
-      const page = await loadCmsPage({ data: basePath + searchStr });
+      const page = await loadCmsPage({
+        data: { path: basePath + searchStr, resolveGlobals },
+      });
       if (!page) return page;
 
       if (!isServer && page.resolvedSections) {
@@ -746,12 +793,21 @@ export function cmsHomeRouteConfig(options: {
   pendingMs?: number;
   /** Minimum display time (ms) for pending component. Default: 300. */
   pendingMinMs?: number;
+  /** See `CmsRouteOptions.resolveGlobals` — default `true`. */
+  resolveGlobals?: boolean;
 }) {
-  const { defaultTitle, defaultDescription, siteName, pendingMs = 200, pendingMinMs = 300 } = options;
+  const {
+    defaultTitle,
+    defaultDescription,
+    siteName,
+    pendingMs = 200,
+    pendingMinMs = 300,
+    resolveGlobals,
+  } = options;
 
   return {
     loader: async () => {
-      const page = await loadCmsHomePage();
+      const page = await loadCmsHomePage({ data: { resolveGlobals } });
       if (!page) return page;
 
       if (!isServer && page.resolvedSections) {

package/src/sdk/workerEntry.test.ts

@@ -430,3 +430,53 @@ describe("POST /_cache/purge-loaders", () => {
     expect(res.status).toBe(404);
   });
 });
+
+describe("X-Cache-Segment — custom SegmentKey fields (#284)", () => {
+  afterEach(() => {
+    __resetKvHydrationStateForTests();
+    setBlocks({});
+  });
+
+  const HTML_SERVER_ENTRY = {
+    fetch: async (_req: Request) =>
+      new Response("<html>hi</html>", {
+        status: 200,
+        headers: { "content-type": "text/html; charset=utf-8" },
+      }),
+  };
+
+  it("includes a custom segment field in X-Cache-Segment instead of dropping it", async () => {
+    const worker = createDecoWorkerEntry(HTML_SERVER_ENTRY, {
+      observability: false,
+      buildSegment: () => ({ device: "desktop", regionId: "RJ", delivery: "store-42" }),
+    });
+    const res = await worker.fetch(new Request("https://example.com/"), EMPTY_ENV, MOCK_CTX);
+    expect(res.headers.get("X-Cache-Segment")).toBe("desktop|r=RJ|delivery=store-42");
+  });
+
+  it("produces different X-Cache-Segment hashes for requests that only differ by a custom field", async () => {
+    let delivery = "store-1";
+    const worker = createDecoWorkerEntry(HTML_SERVER_ENTRY, {
+      observability: false,
+      buildSegment: () => ({ device: "desktop", delivery }),
+    });
+
+    const first = await worker.fetch(new Request("https://example.com/"), EMPTY_ENV, MOCK_CTX);
+    const firstSegment = first.headers.get("X-Cache-Segment");
+
+    delivery = "store-2";
+    const second = await worker.fetch(new Request("https://example.com/"), EMPTY_ENV, MOCK_CTX);
+    const secondSegment = second.headers.get("X-Cache-Segment");
+
+    expect(firstSegment).not.toBe(secondSegment);
+  });
+
+  it("keeps the existing hash format for segments using only known fields (back-compat)", async () => {
+    const worker = createDecoWorkerEntry(HTML_SERVER_ENTRY, {
+      observability: false,
+      buildSegment: () => ({ device: "desktop", salesChannel: "1", flags: ["b", "a"] }),
+    });
+    const res = await worker.fetch(new Request("https://example.com/"), EMPTY_ENV, MOCK_CTX);
+    expect(res.headers.get("X-Cache-Segment")).toBe("desktop|sc=1|f=a,b");
+  });
+});

package/src/sdk/workerEntry.ts

@@ -172,6 +172,13 @@ export interface SegmentKey {
   regionId?: string;
   /** Sorted list of active A/B flag names for cache cohort splitting. */
   flags?: string[];
+  /**
+   * Custom cache dimensions beyond the known fields above (e.g. a
+   * store/CEP-based delivery selector). `hashSegment` serializes these
+   * automatically — unlike the known fields, there's no dedicated shorthand
+   * key, so don't reuse a name already declared above.
+   */
+  [customField: string]: string | boolean | string[] | undefined;
 }
 
 /**
@@ -983,12 +990,34 @@ export function createDecoWorkerEntry(
     return detectCacheProfile(target);
   }
 
+  const KNOWN_SEGMENT_FIELDS = new Set([
+    "device",
+    "loggedIn",
+    "salesChannel",
+    "regionId",
+    "flags",
+  ]);
+
   function hashSegment(seg: SegmentKey): string {
     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(",")}`);
+    // Custom dimensions (anything beyond the known fields above) are
+    // serialized generically so they aren't silently dropped from the
+    // cache key — see #284.
+    const customKeys = Object.keys(seg)
+      .filter((k) => !KNOWN_SEGMENT_FIELDS.has(k) && seg[k] !== undefined)
+      .sort();
+    for (const k of customKeys) {
+      const v = seg[k];
+      if (v === "" || v === false || (Array.isArray(v) && v.length === 0)) {
+        continue;
+      }
+      const serialized = Array.isArray(v) ? [...v].sort().join(",") : v === true ? "" : String(v);
+      parts.push(serialized ? `${k}=${serialized}` : k);
+    }
     return parts.join("|");
   }