@decocms/blocks 7.0.2 → 7.1.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@decocms/blocks",
-  "version": "7.0.2",
+  "version": "7.1.0",
   "type": "module",
   "description": "Deco framework-agnostic core: CMS block resolution, section registry, matchers, portable SDK utilities",
   "repository": {
@@ -12,6 +12,7 @@
   "exports": {
     ".": "./src/index.ts",
     "./cms": "./src/cms/index.ts",
+    "./cms/client": "./src/cms/client.ts",
     "./cms/loadDecofileDirectory": "./src/cms/loadDecofileDirectory.ts",
     "./hooks": "./src/hooks/index.ts",
     "./types": "./src/types/index.ts",
@@ -92,6 +93,7 @@
   "devDependencies": {
     "@types/react": "^19.0.0",
     "@types/react-dom": "^19.0.0",
+    "esbuild": "^0.27.3",
     "knip": "^5.86.0",
     "typescript": "^5.9.0"
   },

package/src/cms/client.browserBundle.test.ts

@@ -0,0 +1,44 @@
+import { describe, expect, it } from "vitest";
+import { execFileSync } from "node:child_process";
+import { fileURLToPath } from "node:url";
+import { dirname, join } from "node:path";
+
+const here = dirname(fileURLToPath(import.meta.url));
+// esbuild's JS API relies on `new TextEncoder().encode("") instanceof
+// Uint8Array` internally, which fails across Vitest's module-isolation VM
+// boundary (a realm mismatch, not a real environment problem — `bun -e`
+// confirms the invariant holds outside Vitest). Shelling out to the esbuild
+// CLI binary sidesteps this: it's a separate OS process, no shared JS realm.
+const esbuildBin = join(here, "../../../../node_modules/.bin/esbuild");
+
+function bundleForBrowser(entry: string) {
+  return execFileSync(
+    esbuildBin,
+    [entry, "--bundle", "--platform=browser", "--format=esm", "--external:react"],
+    { encoding: "utf-8", stdio: ["ignore", "pipe", "pipe"] },
+  );
+}
+
+/**
+ * Regression test for the bug that motivated splitting `client.ts` out of
+ * `index.ts`: importing ANYTHING from the full `cms` barrel forces a
+ * bundler to evaluate `loader.ts` and `middleware/observability.ts`, which
+ * import `node:async_hooks` at the module level. Turbopack rejects that
+ * outright when bundling for a browser target; this test catches the same
+ * class of failure in CI, deterministically, without needing a real Next.js
+ * app to reproduce it.
+ */
+describe("cms/client browser bundle", () => {
+  it("bundles for a browser target with no Node built-ins", () => {
+    const output = bundleForBrowser(join(here, "client.ts"));
+    expect(output).not.toMatch(/node:async_hooks|node:fs|node:path/);
+  });
+
+  it("sanity check: the full cms barrel does NOT bundle for a browser target", () => {
+    // Confirms the test above is actually discriminating — if this ever
+    // stops throwing, either the barrel no longer has the leak (great,
+    // update this test) or esbuild's Node-builtin detection changed
+    // (investigate before trusting the test above).
+    expect(() => bundleForBrowser(join(here, "index.ts"))).toThrow();
+  });
+});

package/src/cms/client.ts

@@ -0,0 +1,65 @@
+/**
+ * Client-safe subset of `@decocms/blocks/cms`.
+ *
+ * `@decocms/blocks/cms` (the full barrel in `./index.ts`) re-exports
+ * `loader.ts` and `resolve.ts`, which transitively import `node:async_hooks`
+ * and `node:fs/promises`. Bundling ANY export from that barrel for a browser
+ * target — even one that itself has zero Node dependencies, like
+ * `getResolvedComponent` — drags the whole module graph in, since ES module
+ * imports are evaluated at the file level, not per-export. Turbopack rejects
+ * this outright in production builds ("the chunking context does not
+ * support external modules"); webpack has historically let it through
+ * uncaught, which just defers the failure to whoever notices the bloated
+ * client bundle or a runtime error.
+ *
+ * This entry point exists so Client Components can import section-registry
+ * lookups (e.g. to resolve and render a section by name, given data already
+ * fetched server-side) without pulling in the resolver/loader machinery.
+ *
+ * Verified client-safe by import-graph inspection, transitively:
+ * - `registry.ts` imports only React types.
+ * - `sectionMixins.ts` imports `useDevice.ts`, which goes through
+ *   `requestContext.ts` — that module's only `node:async_hooks` dependency
+ *   (`requestContextStorage.ts`) is itself swapped for a no-op browser stub
+ *   via this package's `"browser"` export condition (see
+ *   `sdk/requestContextStorage.browser.ts`), so it's already safe for a
+ *   browser bundle.
+ * - `schema.ts` has no imports at all.
+ *
+ * Deliberately NOT re-exported here: `loader.ts`, `resolve.ts`,
+ * `sectionLoaders.ts`, `loadDecofileDirectory.ts`, `blockSource.ts`, and
+ * `applySectionConventions.ts` (which itself pulls in `resolve.ts` and
+ * `sectionLoaders.ts` for section-registration setup). Those are resolver/
+ * storage concerns that only make sense server-side — import them from
+ * `@decocms/blocks/cms` instead.
+ */
+export type { OnBeforeResolveProps, SectionModule, SectionOptions } from "./registry";
+export {
+  getResolvedComponent,
+  getSection,
+  getSectionOptions,
+  getSectionRegistry,
+  getSyncComponent,
+  listRegisteredSections,
+  preloadSectionComponents,
+  preloadSectionModule,
+  registerOnBeforeResolveProps,
+  registerSection,
+  registerSections,
+  registerSectionsSync,
+  setResolvedComponent,
+} from "./registry";
+export type { SectionLoaderFn } from "./sectionLoaders";
+export { compose, withDevice, withMobile, withSearchParam, withSectionLoader } from "./sectionMixins";
+export type { ActionConfig, LoaderConfig, MatcherConfig, MetaResponse } from "./schema";
+export {
+  composeMeta,
+  getRegisteredLoaders,
+  getRegisteredMatchers,
+  registerActionSchema,
+  registerActionSchemas,
+  registerLoaderSchema,
+  registerLoaderSchemas,
+  registerMatcherSchema,
+  registerMatcherSchemas,
+} from "./schema";