@decocms/tanstack 7.2.2 → 7.3.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@decocms/tanstack",
-  "version": "7.2.2",
+  "version": "7.3.0",
   "type": "module",
   "description": "Deco framework binding for TanStack Start + Cloudflare Workers",
   "repository": {
@@ -12,7 +12,8 @@
   "exports": {
     ".": "./src/index.ts",
     "./vite": "./src/vite/plugin.js",
-    "./daemon": "./src/daemon/index.ts"
+    "./daemon": "./src/daemon/index.ts",
+    "./sdk/createInvoke": "./src/sdk/createInvoke.ts"
   },
   "scripts": {
     "build": "tsc",
@@ -21,9 +22,9 @@
     "lint:unused": "knip"
   },
   "dependencies": {
-    "@decocms/blocks": "7.2.2",
-    "@decocms/blocks-admin": "7.2.2",
-    "@decocms/blocks-cli": "7.2.2",
+    "@decocms/blocks": "7.3.0",
+    "@decocms/blocks-admin": "7.3.0",
+    "@decocms/blocks-cli": "7.3.0",
     "@deco-cx/warp-node": "^0.3.16",
     "fast-json-patch": "^3.1.0",
     "ws": "^8.18.0"

package/src/index.ts

@@ -28,5 +28,17 @@ export {
   decoStringifySearch,
 } from "./sdk/router";
 export type { CreateDecoRouterOptions } from "./sdk/router";
-export { createInvokeFn } from "./sdk/createInvoke";
-export type { InvokeFnOpts } from "./sdk/createInvoke";
+// createInvokeFn is intentionally NOT re-exported from this root barrel.
+// Its body contains a `createServerFn(...).handler(...)` call that is not a
+// top-level variable declarator (it's returned from a factory function) --
+// TanStack Start's compiler statically scans every file it processes for
+// this pattern and throws "createServerFn must be assigned to a variable!"
+// on ANY occurrence, whether or not the factory is ever actually called.
+// Re-exporting it here would pull sdk/createInvoke.ts into the module graph
+// of every site that imports anything else from this barrel (which is
+// every site, for DecoRootLayout etc.), tripping that check even though
+// createInvokeFn itself is never invoked at runtime -- it exists purely as
+// a source-of-truth template that blocks-cli's generate-invoke.ts statically
+// parses (never imports) to emit real top-level createServerFn declarations
+// into each site's own src/server/invoke.gen.ts. Import it from the
+// dedicated "@decocms/tanstack/sdk/createInvoke" subpath instead.

package/src/routes/cmsRoute.ts

@@ -27,6 +27,7 @@ import {
   getRequest,
   getRequestHeader,
   getRequestUrl,
+  setCookie,
   setResponseHeader,
 } from "@tanstack/react-start/server";
 import { createElement } from "react";
@@ -44,6 +45,12 @@ import {
   runSingleSectionLoader,
 } from "@decocms/blocks/cms";
 import type { DeferredSection, MatcherContext, PageSeo, ResolvedSection } from "@decocms/blocks/cms";
+import {
+  parseSegmentCookie,
+  SEGMENT_COOKIE,
+  serializeSegmentCookie,
+  type StoredFlag,
+} from "@decocms/blocks/sdk/flags";
 import { withTracing } from "@decocms/blocks/middleware/observability";
 import {
   type CacheProfileName,
@@ -78,6 +85,45 @@ export function setSectionChunkMap(map: Record<string, string>): void {
 type PageResult = Awaited<ReturnType<typeof loadCmsPageInternal>>;
 const pageInflight = new Map<string, Promise<PageResult>>();
 
+/** One year — the cohort is sticky; the `pct` fingerprint handles re-rolls. */
+const SEGMENT_COOKIE_MAX_AGE = 60 * 60 * 24 * 365;
+
+/**
+ * Persist sticky A/B decisions recorded during resolution and return them for
+ * the client (analytics).
+ *
+ * Merges the freshly recorded flags over any already in the `deco_segment`
+ * cookie (so navigating to a second A/B page doesn't drop the first page's
+ * cohort), and only re-issues the cookie when the merged value changed.
+ * Setting the cookie also makes the worker skip caching THIS response
+ * (`deco_segment` is not a "safe" cookie), so an unassigned visitor never
+ * poisons the shared entry — their next request carries the cookie and hits
+ * the per-cohort cache entry.
+ *
+ * `encode: (v) => v` keeps the raw base64 intact — @decocms/apps
+ * OneDollarStats reads the cookie with `atob()` directly.
+ */
+function persistFlags(matcherCtx: MatcherContext): StoredFlag[] {
+  const recorded = matcherCtx.flags ?? [];
+  if (!recorded.length) return [];
+
+  const raw = matcherCtx.cookies?.[SEGMENT_COOKIE];
+  const merged = new Map<string, StoredFlag>();
+  for (const f of parseSegmentCookie(raw)) merged.set(f.name, f);
+  for (const f of recorded) merged.set(f.name, f);
+
+  const serialized = serializeSegmentCookie([...merged.values()]);
+  if (serialized !== (raw ?? "")) {
+    setCookie(SEGMENT_COOKIE, serialized, {
+      path: "/",
+      maxAge: SEGMENT_COOKIE_MAX_AGE,
+      sameSite: "lax",
+      encode: (v) => v,
+    });
+  }
+  return recorded;
+}
+
 async function loadCmsPageInternal(fullPath: string) {
   const [basePath] = fullPath.split("?");
   // On client-side navigation getRequestUrl() is the /_serverFn/... endpoint,
@@ -94,9 +140,11 @@ async function loadCmsPageInternal(fullPath: string) {
     cookies: getCookies(),
     request: originRequest,
     isClientNavigation: isClientNavigation(fullPath, serverUrl),
+    flags: [],
   };
   const page = await resolveDecoPage(basePath, matcherCtx);
   if (!page) return null;
+  const flags = persistFlags(matcherCtx);
 
   const request = new Request(urlWithSearch, {
     headers: originRequest.headers,
@@ -144,6 +192,7 @@ async function loadCmsPageInternal(fullPath: string) {
     pagePath: basePath,
     seo,
     device,
+    flags,
     siteGlobals: { rawRefs: globals.rawRefs },
   };
 }
@@ -179,9 +228,11 @@ export const loadCmsHomePage = createServerFn({ method: "GET" }).handler(async (
     cookies: getCookies(),
     request,
     isClientNavigation: isClientNavigation("/", serverUrl),
+    flags: [],
   };
   const page = await resolveDecoPage("/", matcherCtx);
   if (!page) return null;
+  const flags = persistFlags(matcherCtx);
   const [enrichedSections, globals] = await Promise.all([
     runSectionLoaders(page.resolvedSections, request),
     resolveSiteGlobals(),
@@ -208,6 +259,7 @@ export const loadCmsHomePage = createServerFn({ method: "GET" }).handler(async (
     pageUrl: serverUrl.toString(),
     seo,
     device,
+    flags,
     siteGlobals: { rawRefs: globals.rawRefs },
   };
 });

package/src/sdk/createInvoke.ts

@@ -1,12 +1,31 @@
 /**
- * Generic bridge that turns any async function into a TanStack Start server function.
+ * Type-only marker for apps-* `invoke.ts` codegen templates (e.g.
+ * `@decocms/apps-vtex/invoke.ts`) — NOT a real, callable createServerFn
+ * wrapper. Deliberately does not call `createServerFn` at runtime.
  *
- * Used by @decocms/apps to expose commerce actions/loaders as typed
- * `invoke.*` calls that execute on the server with full credentials.
+ * `invoke.ts` files are never imported/executed by any real site — they
+ * are a source-of-truth that `blocks-cli`'s `generate-invoke.ts` statically
+ * parses (via AST inspection of each `createInvokeFn(action, opts)` call
+ * site's arguments) to emit real, literal top-level `createServerFn(...)`
+ * declarations into each site's own `src/server/invoke.gen.ts`. This
+ * function's ONLY job is to give those template files a correctly-typed
+ * call site to author against.
+ *
+ * It must not contain a real `createServerFn(...)` call: TanStack Start's
+ * compiler statically scans every file reachable by a site's SSR bundle for
+ * that literal pattern and throws "createServerFn must be assigned to a
+ * variable!" on ANY occurrence that isn't a top-level declarator — even one
+ * inside a function body that's never actually invoked. `invoke.ts` isn't
+ * supposed to be reachable by a site's bundler at all (it's excluded from
+ * every apps-* package's public exports map), but Vite's `optimizeDeps`
+ * pre-bundling has been observed sweeping it in regardless of that
+ * exports-map restriction — so the only fully robust fix is for this file
+ * to never contain the literal pattern the compiler is looking for, full
+ * stop, regardless of what does or doesn't end up bundled.
  *
  * @example
  * ```ts
- * import { createInvokeFn } from "@decocms/start/sdk/createInvoke";
+ * import { createInvokeFn } from "@decocms/tanstack/sdk/createInvoke";
  * import { addItemsToCart } from "./actions/checkout";
  *
  * export const invoke = {
@@ -20,12 +39,13 @@
  *     },
  *   },
  * };
- *
- * // Client-side usage:
- * await invoke.vtex.actions.addItemsToCart({ data: { orderFormId, orderItems } });
  * ```
+ *
+ * The real, callable version of each action above only exists in the
+ * site's generated `src/server/invoke.gen.ts` (run `npm run generate:invoke`),
+ * which uses real top-level `createServerFn(...)` calls directly — never
+ * this function.
  */
-import { createServerFn } from "@tanstack/react-start";
 
 export interface InvokeFnOpts {
   /**
@@ -37,21 +57,21 @@ export interface InvokeFnOpts {
 }
 
 /**
- * Transforms an async function into a `createServerFn` wrapper.
- *
- * - Client calls: `fn({ data: input })`
- * - Server executes: `action(input)`
- * - If `unwrap: true`, extracts `.data` from VtexFetchResult-shaped results
+ * Template-only — see the module doc comment above. Throws if actually
+ * called at runtime, since that would mean something imported an
+ * `invoke.ts` template file directly instead of using the site's generated
+ * `invoke.gen.ts`, which is itself a bug worth surfacing loudly rather than
+ * silently returning wrong behavior.
  */
 export function createInvokeFn<TInput, TOutput>(
-  action: (input: TInput) => Promise<TOutput>,
-  opts?: InvokeFnOpts,
+  _action: (input: TInput) => Promise<TOutput>,
+  _opts?: InvokeFnOpts,
 ): (ctx: { data: TInput }) => Promise<TOutput> {
-  return createServerFn({ method: "POST" }).handler(async (ctx) => {
-    const result = await action(ctx.data as TInput);
-    if (opts?.unwrap && result && typeof result === "object" && "data" in result) {
-      return (result as any).data;
-    }
-    return result;
-  }) as unknown as (ctx: { data: TInput }) => Promise<TOutput>;
+  return () => {
+    throw new Error(
+      "createInvokeFn() is a codegen-time-only template marker and was never meant to be called at " +
+        "runtime. If you're seeing this, something imported an apps-*/invoke.ts template file directly " +
+        "instead of using the site's generated src/server/invoke.gen.ts (run `npm run generate:invoke`).",
+    );
+  };
 }

package/src/sdk/outboundHeaders.test.ts

@@ -0,0 +1,113 @@
+import { afterEach, describe, expect, it, vi } from "vitest";
+import {
+  _uninstallDefaultUserAgentForTests,
+  DECO_POWERED_BY,
+  DECO_USER_AGENT,
+  installDefaultUserAgent,
+} from "./outboundHeaders";
+
+/** Headers the wrapped baseFetch would put on the wire for a given call. */
+function wireHeaders(call: readonly [RequestInfo | URL, RequestInit?]): Headers {
+  const [input, init] = call;
+  if (init?.headers !== undefined) return new Headers(init.headers);
+  if (input instanceof Request) return new Headers(input.headers);
+  return new Headers();
+}
+
+describe("installDefaultUserAgent", () => {
+  const realFetch = globalThis.fetch;
+
+  afterEach(() => {
+    _uninstallDefaultUserAgentForTests();
+    globalThis.fetch = realFetch;
+    vi.restoreAllMocks();
+  });
+
+  function install(userAgent?: string) {
+    const baseFetch = vi.fn(
+      async (_input: RequestInfo | URL, _init?: RequestInit) => new Response("ok"),
+    );
+    globalThis.fetch = baseFetch as unknown as typeof fetch;
+    installDefaultUserAgent(userAgent);
+    return baseFetch;
+  }
+
+  it("sets the default UA on a bare string fetch", async () => {
+    const baseFetch = install();
+    await fetch("https://api.example.com/products");
+
+    const headers = wireHeaders(baseFetch.mock.calls[0]);
+    expect(headers.get("user-agent")).toBe(DECO_USER_AGENT);
+  });
+
+  it("keeps the caller's UA from init.headers", async () => {
+    const baseFetch = install();
+    await fetch("https://api.example.com/", {
+      headers: { "user-agent": "deco-aws-app/1.0" },
+    });
+
+    // Untouched call: init passed through verbatim.
+    expect(baseFetch.mock.calls[0][1]).toEqual({
+      headers: { "user-agent": "deco-aws-app/1.0" },
+    });
+  });
+
+  it("keeps the UA of a Request input", async () => {
+    const baseFetch = install();
+    const req = new Request("https://api.example.com/", {
+      headers: { "User-Agent": "decocx/1.0" },
+    });
+    await fetch(req);
+
+    expect(baseFetch.mock.calls[0][0]).toBe(req);
+    expect(baseFetch.mock.calls[0][1]).toBeUndefined();
+  });
+
+  it("preserves a Request's other headers when injecting the UA", async () => {
+    const baseFetch = install();
+    await fetch(
+      new Request("https://api.example.com/", {
+        headers: { accept: "application/json", "x-api-key": "k" },
+      }),
+    );
+
+    const headers = wireHeaders(baseFetch.mock.calls[0]);
+    expect(headers.get("user-agent")).toBe(DECO_USER_AGENT);
+    expect(headers.get("accept")).toBe("application/json");
+    expect(headers.get("x-api-key")).toBe("k");
+  });
+
+  it("preserves non-header init members (method, body, signal)", async () => {
+    const baseFetch = install();
+    const controller = new AbortController();
+    await fetch("https://api.example.com/", {
+      method: "POST",
+      body: "{}",
+      signal: controller.signal,
+    });
+
+    const init = baseFetch.mock.calls[0][1]!;
+    expect(init.method).toBe("POST");
+    expect(init.body).toBe("{}");
+    expect(init.signal).toBe(controller.signal);
+    expect(new Headers(init.headers).get("user-agent")).toBe(DECO_USER_AGENT);
+  });
+
+  it("honors a custom UA value", async () => {
+    const baseFetch = install("MyStore-Migration/1.0");
+    await fetch("https://api.example.com/");
+
+    expect(wireHeaders(baseFetch.mock.calls[0]).get("user-agent")).toBe("MyStore-Migration/1.0");
+  });
+
+  it("is idempotent — a second install does not re-wrap", () => {
+    install();
+    const wrapped = globalThis.fetch;
+    installDefaultUserAgent();
+    expect(globalThis.fetch).toBe(wrapped);
+  });
+
+  it("exposes the old-runtime-parity x-powered-by value", () => {
+    expect(DECO_POWERED_BY).toMatch(/^deco@\d+\.\d+\.\d+/);
+  });
+});

package/src/sdk/outboundHeaders.ts

@@ -0,0 +1,81 @@
+/**
+ * Runtime identification headers.
+ *
+ * Outbound: Cloudflare Workers' `fetch` sends NO `User-Agent` header at
+ * all — unlike the old Deno runtime, where every outbound request carried
+ * Deno's implicit `User-Agent: Deno/x.y.z`. UA-less requests are a strong
+ * bot signal: Cloudflare managed WAF rules and Bot Fight Mode on partner
+ * origins block them outright. `installDefaultUserAgent()` restores the
+ * pre-migration behavior with an honest, allowlistable value, applied only
+ * when the caller didn't set a User-Agent of its own.
+ *
+ * Responses: the old runtime stamped `x-powered-by: deco@<version>` on
+ * every response (deco-cx/deco `utils/http.ts` defaultHeaders). The worker
+ * entry reuses `DECO_POWERED_BY` for parity.
+ */
+
+import pkg from "../../package.json";
+
+/**
+ * Default outbound User-Agent. Stable prefix (`Deco/`) so partners can
+ * write one WAF allowlist rule that survives version bumps and platform
+ * changes; the URL comment tells whoever reads an access log who we are.
+ */
+export const DECO_USER_AGENT = `Deco/${pkg.version} (+https://deco.cx)`;
+
+/** Response identification header value — parity with deco-cx/deco. */
+export const DECO_POWERED_BY = `deco@${pkg.version}`;
+
+/**
+ * Cross-module guard on `globalThis` (same trick as logger.ts STATE_KEY):
+ * bundlers may duplicate this module across chunks, so a module-local
+ * boolean would not prevent double-wrapping.
+ */
+const INSTALLED_KEY = Symbol.for("deco.outboundHeaders.installed");
+
+let restoreBaseFetch: (() => void) | undefined;
+
+/**
+ * Patch `globalThis.fetch` so every outbound request carries a User-Agent.
+ *
+ * Set-if-absent only: app-specific UAs (`deco-aws-app/1.0`, `decocx/1.0`,
+ * ...) always win, matching the old runtime where Deno's default applied
+ * only when unset. All other RequestInit members (method, body, signal,
+ * `cf`, ...) pass through untouched. Idempotent — safe to call more than
+ * once (e.g. worker entry + tests).
+ */
+export function installDefaultUserAgent(userAgent: string = DECO_USER_AGENT): void {
+  const g = globalThis as Record<symbol, unknown>;
+  if (g[INSTALLED_KEY]) return;
+  g[INSTALLED_KEY] = true;
+
+  const baseFetch = globalThis.fetch;
+  restoreBaseFetch = () => {
+    globalThis.fetch = baseFetch;
+    delete g[INSTALLED_KEY];
+  };
+
+  globalThis.fetch = ((input: RequestInfo | URL, init?: RequestInit): Promise<Response> => {
+    // Fetch-spec semantics (same rule instrumentedFetch.ts documents):
+    // when both a Request and `init.headers` are passed, `init.headers`
+    // REPLACES the Request's headers — they do not union. So the headers
+    // that will actually hit the wire are init.headers if present, else
+    // the Request's own headers, else none.
+    const base =
+      init?.headers !== undefined
+        ? init.headers
+        : input instanceof Request
+          ? input.headers
+          : undefined;
+    const headers = new Headers(base ?? undefined);
+    if (headers.has("user-agent")) return baseFetch(input, init);
+    headers.set("user-agent", userAgent);
+    return baseFetch(input, { ...init, headers });
+  }) as typeof fetch;
+}
+
+/** Test-only: restore the unpatched fetch. Do not call from app code. */
+export function _uninstallDefaultUserAgentForTests(): void {
+  restoreBaseFetch?.();
+  restoreBaseFetch = undefined;
+}

package/src/sdk/workerEntry.ts

@@ -45,6 +45,7 @@ import {
   getCacheProfile,
   serverFnPagePath,
 } from "@decocms/blocks/sdk/cacheHeaders";
+import { parseSegmentCookie, SEGMENT_COOKIE, segmentCacheToken } from "@decocms/blocks/sdk/flags";
 import { buildHtmlShell } from "@decocms/blocks-admin/sdk/htmlShell";
 import { ensureBlocksHydrated, maybePollRevision } from "./kvHydration";
 import {
@@ -61,6 +62,7 @@ import {
   instrumentWorker,
   type OtelOptions,
 } from "@decocms/blocks/sdk/otel";
+import { DECO_POWERED_BY, installDefaultUserAgent } from "./outboundHeaders";
 import { setRuntimeEnv } from "@decocms/blocks/sdk/otelAdapters";
 import { parseTraceparent } from "@decocms/blocks/sdk/otelHttpTracer";
 import { RequestContext } from "@decocms/blocks/sdk/requestContext";
@@ -434,6 +436,25 @@ export interface DecoWorkerEntryOptions {
    * no-op — no buffers, no flushes, no network calls.
    */
   observability?: OtelOptions | false;
+
+  /**
+   * Default `User-Agent` for OUTBOUND `fetch` calls (loaders, commerce
+   * APIs, proxies). Cloudflare Workers sends no User-Agent at all, and
+   * UA-less requests are blocked by common WAF setups (Cloudflare managed
+   * rules / Bot Fight Mode) on partner origins. The old Deno runtime
+   * implicitly sent `Deno/x.y.z` on every outbound request, so this
+   * restores pre-migration behavior with an identifiable value.
+   *
+   * Applied only when the caller didn't set a User-Agent — app-specific
+   * UAs always win.
+   *
+   * - Pass a string to override the value (e.g. to match a partner's
+   *   existing WAF allowlist during migration).
+   * - Pass `false` to leave `globalThis.fetch` untouched.
+   *
+   * @default `Deco/<version> (+https://deco.cx)` — see DECO_USER_AGENT.
+   */
+  outboundUserAgent?: string | false;
 }
 
 // ---------------------------------------------------------------------------
@@ -707,8 +728,18 @@ export function createDecoWorkerEntry(
     staticPaths: staticPathsOpt = DEFAULT_STATIC_PATHS,
     cdnCacheControl: cdnCacheControlOpt = "no-store",
     observability: observabilityOpt,
+    outboundUserAgent: outboundUserAgentOpt,
   } = options;
 
+  // Patch global fetch once so every outbound request — apps calling
+  // `fetch` directly, RequestContext.fetch, instrumentedFetch — carries a
+  // User-Agent. Workers sends none by default, which WAFs on partner
+  // origins read as bot traffic. Set-if-absent: callers that set their
+  // own UA are untouched.
+  if (outboundUserAgentOpt !== false) {
+    installDefaultUserAgent(outboundUserAgentOpt);
+  }
+
   // Backfill `regionId` from Cloudflare geo when the consumer's buildSegment
   // doesn't set one. Without this, sites using website/matchers/location.ts
   // get a single cached response per device that leaks across regions: the
@@ -830,6 +861,25 @@ export function createDecoWorkerEntry(
     return typeof __DECO_BUILD_HASH__ !== "undefined" ? __DECO_BUILD_HASH__ : "";
   }
 
+  function readRequestCookie(request: Request, name: string): string | undefined {
+    for (const pair of (request.headers.get("cookie") ?? "").split(";")) {
+      const idx = pair.indexOf("=");
+      if (idx <= 0) continue;
+      if (pair.slice(0, idx).trim() !== name) continue;
+      const raw = pair.slice(idx + 1).trim();
+      // Decode once so this matches TanStack's getCookies() used during SSR
+      // (see cms/resolve.ts) — otherwise the worker's cache key and the render
+      // could disagree on the cohort. The deco_segment value is raw base64 (no
+      // percent-escapes), so decoding is a no-op for it and safe in general.
+      try {
+        return decodeURIComponent(raw);
+      } catch {
+        return raw;
+      }
+    }
+    return undefined;
+  }
+
   function buildCacheKey(
     request: Request,
     env: Record<string, unknown>,
@@ -904,6 +954,18 @@ export function createDecoWorkerEntry(
       url.searchParams.set("__fetch", "1");
     }
 
+    // A/B cohort split: fold the sticky `deco_segment` cookie into the cache
+    // key so each variant keeps its own cached HTML. The cookie carries the
+    // traffic fingerprint (see sdk/flags.ts), so a `traffic` change lands
+    // cohorts in fresh buckets. Empty for non-A/B visitors (no cookie) → they
+    // keep sharing one entry. A freshly-assigned visitor sets the cookie on the
+    // response, which is not a "safe" cookie, so that one response bypasses the
+    // cache and never poisons the shared entry.
+    const flagToken = segmentCacheToken(parseSegmentCookie(readRequestCookie(request, SEGMENT_COOKIE)));
+    if (flagToken) {
+      url.searchParams.set("__abf", flagToken);
+    }
+
     if (buildSegment) {
       const segment = buildSegment(request);
       url.searchParams.set("__seg", hashSegment(segment));
@@ -1311,6 +1373,18 @@ export function createDecoWorkerEntry(
         }
       }
 
+      // Old-runtime parity: deco-cx/deco stamped `x-powered-by: deco@<ver>`
+      // on every response (utils/http.ts defaultHeaders); partner-side logs
+      // and ops tooling use it to identify deco traffic. Set-if-absent so
+      // an upstream origin's own value wins.
+      if (!finalResponse.headers.has("x-powered-by")) {
+        try {
+          finalResponse.headers.set("x-powered-by", DECO_POWERED_BY);
+        } catch {
+          /* sealed headers (cached replay) — identification is best-effort */
+        }
+      }
+
       // Metrics + structured request log. Done after security headers so
       // the recorded status reflects what the client actually receives.
       // Both calls are no-ops when no meter / logger is configured.
@@ -1318,8 +1392,9 @@ export function createDecoWorkerEntry(
       try {
         // Phase 2 / D-11 canonical labels — lift the cache decision +
         // profile + region off the response we just built so dashboards
-        // can answer "cache hit rate per route" from `http_requests_total`
-        // alone, no join to `cache_*_total` required.
+        // can answer "cache hit rate per route" from
+        // `http.server.request.duration` alone, no join to a cache counter
+        // required.
         const xCacheRaw = finalResponse.headers.get("X-Cache");
         const cacheDecision = isCacheDecision(xCacheRaw) ? xCacheRaw : undefined;
         const colo = (request as unknown as { cf?: { colo?: string } }).cf?.colo;

package/src/vite/plugin.js

@@ -588,37 +588,27 @@ export function decoVitePlugin() {
         env.optimizeDeps.esbuildOptions.jsxImportSource = "react";
       }
 
-      // Force these packages through the SSR transform pipeline so
-      // TanStack Start's compiler can register their createServerFn handlers
+      // Force @decocms/tanstack through the SSR transform pipeline so
+      // TanStack Start's compiler can register its createServerFn handlers
       // (loadDeferredSection in routes/cmsRoute.ts, and loadCmsPage /
-      // loadCmsHomePage alongside it, for @decocms/tanstack) in the
-      // per-environment serverFnsById manifest. Without this, Vite
-      // pre-bundles the package via optimizeDeps before plugins run, the
-      // handler never enters the manifest, and every POST /_serverFn/* call
-      // from the browser returns HTTP 500 ("Invalid server function ID").
-      // See #197.
+      // loadCmsHomePage alongside it) in the per-environment serverFnsById
+      // manifest. Without this, Vite pre-bundles the package via
+      // optimizeDeps before plugins run, the handler never enters the
+      // manifest, and every POST /_serverFn/* call from the browser returns
+      // HTTP 500 ("Invalid server function ID"). See #197.
       //
-      // @decocms/apps-vtex needs this too: its invoke.ts wraps 18 actions/
-      // loaders via createInvokeFn (packages/tanstack/src/sdk/createInvoke.ts),
-      // each a real `createServerFn(...)` call site. This was missed when
-      // createInvokeFn's export was added to @decocms/tanstack's public
-      // barrel (apps-monorepo-migration Task 7) — worked by accident under
-      // `bun link` (Vite treats symlinked/workspace packages as live source,
-      // skipping optimizeDeps pre-bundling for them) but hard-crashes with
-      // a real npm install: "createServerFn must be assigned to a variable!"
-      // from the Cloudflare Workers runtime's static entry-export scan.
-      //
-      // @decocms/blocks does NOT need this: despite its
-      // validateSection.ts / useScript.ts doc comments mentioning
-      // `createServerFn`, neither file (nor anything else in runtime)
-      // actually calls it — those are a JSDoc usage example for a site's
-      // own server-fn file and a deprecation-message suggestion,
-      // respectively. Only add a package here once it has a real
-      // `createServerFn(...)` call site.
+      // @decocms/apps-vtex does NOT need this: its invoke.ts has zero real
+      // createServerFn call sites reachable by any site (it's a
+      // codegen-time-only template that blocks-cli's generate-invoke.ts
+      // statically parses, never imports, to emit each site's own
+      // src/server/invoke.gen.ts with real top-level createServerFn consts;
+      // createInvokeFn itself is a non-functional type-only marker for that
+      // template, see sdk/createInvoke.ts's doc comment). Only add a
+      // package here once it has a real `createServerFn(...)` call site.
       if (name === "ssr") {
         env.resolve = env.resolve || {};
         const existing = env.resolve.noExternal;
-        const additions = ["@decocms/tanstack", "@decocms/apps-vtex"];
+        const additions = ["@decocms/tanstack"];
         if (existing === true) {
           // Already noExternal everything — nothing to add.
         } else if (Array.isArray(existing)) {
@@ -628,6 +618,34 @@ export function decoVitePlugin() {
         } else {
           env.resolve.noExternal = additions;
         }
+
+        // The noExternal setting above only controls whether Vite's SSR
+        // *output* inlines vs. externalizes this package — it does NOT
+        // stop Vite's dev-server-startup dependency optimizer (esbuild via
+        // `optimizeDeps`) from pre-bundling it. Some Cloudflare Workers
+        // targets (via @cloudflare/vite-plugin) already force
+        // `resolve.noExternal = true` unconditionally for this same "ssr"
+        // environment before this hook even runs, making the block above a
+        // complete no-op there — yet the crash below still happened,
+        // proving pre-bundling (not noExternal) was always the real cause.
+        //
+        // Confirmed via direct diagnostic instrumentation of
+        // @tanstack/start-plugin-core: once esbuild pre-bundles this
+        // package into a single node_modules/.vite/deps_ssr/*.js chunk,
+        // Cloudflare's separate worker-export static-analysis pass
+        // (getWorkerEntryExportTypes, a distinct pipeline stage from
+        // Vite's own SSR transform — see workers/runner-worker in the
+        // stack trace) throws "createServerFn must be assigned to a
+        // variable!" on this package's own legitimate, already-top-level
+        // createServerFn calls (loadCmsPage / loadCmsHomePage /
+        // loadDeferredSection) — apparently that scan doesn't recognize
+        // esbuild-bundled `var X = createServerFn(...)` output the same
+        // way it recognizes the original, unbundled source. Excluding this
+        // package from `optimizeDeps` entirely routes it through Vite's
+        // normal plugin pipeline (where TanStack Start's compiler
+        // transforms it correctly) instead of esbuild's pre-bundler.
+        env.optimizeDeps = env.optimizeDeps || {};
+        env.optimizeDeps.exclude = [...new Set([...(env.optimizeDeps.exclude || []), "@decocms/tanstack"])];
       }
     },
 

package/tsconfig.json

@@ -3,5 +3,5 @@
   "compilerOptions": {
     "outDir": "dist"
   },
-  "include": ["src/**/*"]
+  "include": ["src/**/*", "package.json"]
 }