@decocms/tanstack 7.2.2 → 7.2.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@decocms/tanstack",
-  "version": "7.2.2",
+  "version": "7.2.3",
   "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.2.3",
+    "@decocms/blocks-admin": "7.2.3",
+    "@decocms/blocks-cli": "7.2.3",
     "@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/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/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"])];
       }
     },