@decocms/tanstack 7.10.0 → 7.11.0

package/package.json

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

package/src/index.ts

@@ -2,9 +2,9 @@ export {
   cmsHomeRouteConfig,
   cmsRouteConfig,
   CmsPage,
-  decoInvokeRoute,
-  decoMetaRoute,
-  decoRenderRoute,
+  decoInvokeRouteConfig,
+  decoMetaRouteConfig,
+  decoRenderRouteConfig,
   loadCmsHomePage,
   loadCmsPage,
   loadDeferredSection,

package/src/routes/adminRoutes.test.ts

@@ -0,0 +1,99 @@
+import { describe, expect, it, vi } from "vitest";
+
+vi.mock("@decocms/blocks-admin", () => ({
+  corsHeaders: vi.fn(() => ({})),
+  handleInvoke: vi.fn(),
+  handleMeta: vi.fn(),
+  handleRender: vi.fn(),
+}));
+
+vi.mock("@decocms/blocks/sdk/observability", () => ({
+  withTracing: vi.fn((_name: string, fn: () => unknown) => fn()),
+}));
+
+import * as adminRoutes from "./adminRoutes";
+import { decoInvokeRouteConfig, decoMetaRouteConfig, decoRenderRouteConfig } from "./adminRoutes";
+
+/**
+ * Regression guard for the dev-HMR brick:
+ *
+ * TanStack router-core's `BaseRoute.update()` mutates the options object it
+ * is handed (`Object.assign(this.options, options)` — injecting `id`/`path`).
+ * Before 7.10.0 this module exported shared module-scope literals
+ * (`decoMetaRoute`/`decoRenderRoute`/`decoInvokeRoute`); a site passing one
+ * by reference polluted it on first execution, and on any HMR re-execution
+ * the route constructor threw
+ * `Route cannot have both an 'id' and a 'path' option` — every route 500ed
+ * until dev restart.
+ *
+ * The `*RouteConfig()` factories must therefore return a FRESH object on
+ * every call, and the shared literals must never be (re-)exported.
+ */
+describe("admin route config factories", () => {
+  const cases = [
+    {
+      name: "decoMetaRouteConfig",
+      factory: decoMetaRouteConfig,
+      methods: ["GET", "OPTIONS"],
+    },
+    {
+      name: "decoRenderRouteConfig",
+      factory: decoRenderRouteConfig,
+      methods: ["GET", "POST", "OPTIONS"],
+    },
+    {
+      name: "decoInvokeRouteConfig",
+      factory: decoInvokeRouteConfig,
+      methods: ["GET", "POST", "OPTIONS"],
+    },
+  ] as const;
+
+  for (const { name, factory, methods } of cases) {
+    describe(name, () => {
+      it("returns a new object on every call", () => {
+        expect(factory()).not.toBe(factory());
+      });
+
+      it("returns structurally equal configs across calls", () => {
+        expect(factory()).toEqual(factory());
+      });
+
+      it(`exposes server handlers for ${methods.join("/")}`, () => {
+        const config = factory() as {
+          server: { handlers: Record<string, unknown> };
+        };
+        expect(Object.keys(config.server.handlers).sort()).toEqual([...methods].sort());
+        for (const method of methods) {
+          expect(config.server.handlers[method]).toBeTypeOf("function");
+        }
+      });
+
+      it("survives router-core-style mutation without polluting later calls", () => {
+        // Simulate BaseRoute.update(): Object.assign(this.options, options)
+        // pollutes whatever object createFileRoute was handed.
+        const options = factory() as Record<string, unknown>;
+        Object.assign(options, { id: "/deco/x", path: "/deco/x" });
+
+        // The next module execution (HMR) gets a clean object again.
+        const next = factory();
+        expect(next).not.toHaveProperty("id");
+        expect(next).not.toHaveProperty("path");
+      });
+    });
+  }
+
+  it("does NOT export the removed pre-7.10.0 literals (dev-HMR footgun)", () => {
+    // The shared module-scope literals were removed in 7.10.0. Re-exporting
+    // them would reintroduce the HMR brick for any site passing them by
+    // reference to createFileRoute.
+    const removed = ["decoMetaRoute", "decoRenderRoute", "decoInvokeRoute"];
+    for (const name of removed) {
+      expect(adminRoutes, `"${name}" must not be exported`).not.toHaveProperty(name);
+    }
+    expect(Object.keys(adminRoutes).sort()).toEqual([
+      "decoInvokeRouteConfig",
+      "decoMetaRouteConfig",
+      "decoRenderRouteConfig",
+    ]);
+  });
+});

package/src/routes/adminRoutes.ts

@@ -1,17 +1,32 @@
 /**
  * Admin Route Helpers
  *
- * Pre-built server handler configs for the Deco admin protocol routes.
- * Sites spread these into their `createFileRoute` definitions to avoid
+ * Pre-built server handler config factories for the Deco admin protocol
+ * routes. Sites call these in their `createFileRoute` definitions to avoid
  * repeating the same CORS + handler boilerplate.
  *
  * @example Site's `src/routes/deco/meta.ts`:
  * ```ts
  * import { createFileRoute } from "@tanstack/react-router";
- * import { decoMetaRoute } from "@decocms/start/routes";
+ * import { decoMetaRouteConfig } from "@decocms/tanstack";
  *
- * export const Route = createFileRoute("/deco/meta")(decoMetaRoute);
+ * export const Route = createFileRoute("/deco/meta")(decoMetaRouteConfig());
  * ```
+ *
+ * ## Why factories and not shared config objects? (dev-HMR footgun)
+ *
+ * TanStack router-core's `BaseRoute.update()` MUTATES the options object it
+ * receives (`Object.assign(this.options, options)` — injecting `id` and
+ * `path`). Before 7.10.0 this module exported the configs as module-scope
+ * LITERALS (`decoMetaRoute` / `decoRenderRoute` / `decoInvokeRoute`); a site
+ * passing one by reference (`createFileRoute("/deco/meta")(decoMetaRoute)`)
+ * polluted the shared literal on first execution, and any dev-server HMR
+ * partial re-execution then re-ran the route file against the still-cached,
+ * now-polluted literal — the route constructor threw
+ * `Route cannot have both an 'id' and a 'path' option` and every route 500ed
+ * until the dev server restarted. The factories hand each `createFileRoute`
+ * call its own fresh object, so the mutation is harmless. The base configs
+ * below are module-private and deliberately NOT exported.
  */
 import { corsHeaders, handleInvoke, handleMeta, handleRender } from "@decocms/blocks-admin";
 import { withTracing } from "@decocms/blocks/sdk/observability";
@@ -54,11 +69,15 @@ function optionsHandler(ctx: { request: Request }): Response {
   });
 }
 
-/**
- * Route config for `/deco/meta` — serves JSON Schema + manifest.
- * Spread into `createFileRoute("/deco/meta")({...})`.
- */
-export const decoMetaRoute = {
+// ---------------------------------------------------------------------------
+// Base configs — module-PRIVATE. Never export these: router-core's update()
+// mutates whatever object createFileRoute is handed (injects id/path), so a
+// shared exported literal bricks dev HMR (see module doc above). Sites get
+// fresh copies via the *RouteConfig() factories below.
+// ---------------------------------------------------------------------------
+
+/** Base config for `/deco/meta` — serves JSON Schema + manifest. */
+const decoMetaRoute = {
   server: {
     handlers: {
       GET: withCors(({ request }) =>
@@ -69,11 +88,8 @@ export const decoMetaRoute = {
   },
 };
 
-/**
- * Route config for `/deco/render` — section/page preview in iframe.
- * Spread into `createFileRoute("/deco/render")({...})`.
- */
-export const decoRenderRoute = {
+/** Base config for `/deco/render` — section/page preview in iframe. */
+const decoRenderRoute = {
   server: {
     handlers: {
       GET: withCors(({ request }) =>
@@ -95,11 +111,8 @@ export const decoRenderRoute = {
   },
 };
 
-/**
- * Route config for `/deco/invoke/$` — loader/action execution.
- * Spread into `createFileRoute("/deco/invoke/$")({...})`.
- */
-export const decoInvokeRoute = {
+/** Base config for `/deco/invoke/$` — loader/action execution. */
+const decoInvokeRoute = {
   server: {
     handlers: {
       GET: withCors(({ request }) =>
@@ -112,3 +125,29 @@ export const decoInvokeRoute = {
     },
   },
 };
+
+// ---------------------------------------------------------------------------
+// Factories — dev-HMR-safe route configs (fresh object per call)
+// ---------------------------------------------------------------------------
+// Mirrors the `cmsRouteConfig()` / `cmsHomeRouteConfig()` convention in
+// cmsRoute.ts: a function returning a fresh options object, so router-core's
+// mutating `update()` can never pollute shared module state across HMR
+// re-executions.
+
+/**
+ * Returns a fresh route config for `/deco/meta` — serves JSON Schema + manifest.
+ * Use as `createFileRoute("/deco/meta")(decoMetaRouteConfig())`.
+ */
+export const decoMetaRouteConfig = () => ({ ...decoMetaRoute });
+
+/**
+ * Returns a fresh route config for `/deco/render` — section/page preview in iframe.
+ * Use as `createFileRoute("/deco/render")(decoRenderRouteConfig())`.
+ */
+export const decoRenderRouteConfig = () => ({ ...decoRenderRoute });
+
+/**
+ * Returns a fresh route config for `/deco/invoke/$` — loader/action execution.
+ * Use as `createFileRoute("/deco/invoke/$")(decoInvokeRouteConfig())`.
+ */
+export const decoInvokeRouteConfig = () => ({ ...decoInvokeRoute });

package/src/routes/index.ts

@@ -1,9 +1,9 @@
 export type { PageSeo } from "@decocms/blocks/cms";
 export type { Device } from "@decocms/blocks/sdk/useDevice";
 export {
-  decoInvokeRoute,
-  decoMetaRoute,
-  decoRenderRoute,
+  decoInvokeRouteConfig,
+  decoMetaRouteConfig,
+  decoRenderRouteConfig,
 } from "./adminRoutes";
 export {
   CmsPagePendingFallback,