@decocms/nextjs 7.8.0 → 7.9.0

package/README.md

@@ -131,15 +131,59 @@ relative path:
 ```ts
 // src/deco/setup.ts
 import { createNextSetup } from "@decocms/nextjs/setup";
+import blocks from "deco/blocksManifest.gen"; // .deco/blocksManifest.gen.ts — see below
 import { sectionImports, sectionMeta, syncComponents, loadingFallbacks } from "deco/sections.gen";
 
 export const ensureSetup = createNextSetup({
+  blocks,
+  blocksDir: false, // the manifest replaces the runtime fs read
   sections: sectionImports,
   conventions: { meta: sectionMeta, syncComponents, loadingFallbacks },
   meta: () => import("deco/meta.gen.json").then((m) => m.default),
 });
 ```
 
+### Recommended block source: the static-import manifest
+
+`generate-blocks-manifest` (from `@decocms/blocks-cli`) emits
+`.deco/blocksManifest.gen.ts` — a module that **statically imports** every
+`.deco/blocks/*.json` file (raw on-disk filename in the specifier; keys are
+the filename minus `.json`, verbatim, exactly like
+`loadDecofileDirectory`). Passing its default export as `blocks` with
+`blocksDir: false` (as in the snippet above) makes the manifest the sole
+block source and the bootstrap pure — no filesystem access.
+
+Why this is the recommended wiring over the default `blocksDir` runtime
+read:
+
+- **CMS content hot-reloads in `next dev`.** The block JSONs are part of
+  Next's module graph, so editing one (Studio daemon write, sync, manual
+  edit) invalidates the server module graph, re-evaluates the setup module,
+  and rebuilds `createNextSetup`'s memo with the fresh content —
+  ~120–165ms per edit, measured on a 500-block site. The runtime fs read is
+  invisible to the bundler: edits invalidate nothing and dev serves stale
+  content until a restart.
+- **Deploys need no `outputFileTracingIncludes` hack** — the JSON is
+  bundled into the build output instead of read from disk at runtime.
+
+Trade-offs to know about:
+
+- **Content is baked at build time** in production. Studio's
+  `POST /.decofile` still overrides the in-memory snapshot at runtime
+  (live preview/publish keeps working on a warm instance); the baked
+  manifest is the cold-start baseline.
+- **Adding or removing a block *file* requires re-running the generator**
+  (content edits to existing files do not). Wire it into the site's
+  `generate` chain — see the scripts section below.
+
+If you skip the manifest, the default `blocksDir: ".deco/blocks"` runtime
+read still works — just without dev reload, and your deploy must ship the
+directory alongside the server bundle.
+
+Keep the manifest out of any client-reachable import graph (import it only
+from the server-side setup module) so 5MB of CMS JSON never lands in a
+client bundle.
+
 `createNextSetup` returns a **memoized** `ensureSetup()` function — a
 successful bootstrap is cached for the life of the warm serverless
 instance; a *rejected* bootstrap clears the memo so the next call retries
@@ -172,8 +216,8 @@ Two call sites need `ensureSetup()`:
 
 | Option | Purpose |
 | --- | --- |
-| `blocksDir` | Directory of decofile JSON snapshots (`.deco/blocks` by default). Pass `false` to skip filesystem loading entirely (e.g. when all content comes from `blocks`). |
-| `blocks` | Extra/override blocks, merged **over** the directory's blocks. |
+| `blocksDir` | Directory of decofile JSON snapshots (`.deco/blocks` by default), read with a plain fs scan at bootstrap. Pass `false` to skip filesystem loading entirely — the recommended setting when `blocks` carries the static-import manifest (see above). |
+| `blocks` | Extra/override blocks, merged **over** the directory's blocks. Pass the manifest's default export here (with `blocksDir: false`) to make it the sole block source. |
 | `sections` | The lazy section registry — `sectionImports` from `generate-sections --registry` (see below). |
 | `conventions` | `{ meta, syncComponents, loadingFallbacks }` from `sections.gen.ts` — wires the `export const sync/layout/seo/cache/eager/clientOnly` conventions (see below). |
 | `meta` | Lazy admin meta schema loader: `() => import("deco/meta.gen.json").then(m => m.default)`. Wire this even with a trivial schema — without it, `/deco/meta` (and its `/live/_meta` alias) 503s with `"Schema not initialized"`. |
@@ -184,7 +228,7 @@ Two call sites need `ensureSetup()`:
 
 ## 4. `package.json` scripts — non-colliding names
 
-Add two codegen scripts. **Do not name either of these `generate:schema`** —
+Add three codegen scripts. **Do not name any of these `generate:schema`** —
 FastStore sites already own that script name for their own commerce-schema
 codegen, and a collision silently shadows one of the two generators
 depending on script-merge order. Use these names instead:
@@ -193,7 +237,8 @@ depending on script-merge order. Use these names instead:
 {
   "scripts": {
     "generate:deco-meta": "tsx node_modules/@decocms/blocks-cli/scripts/generate-schema.ts",
-    "generate:deco-sections": "tsx node_modules/@decocms/blocks-cli/scripts/generate-sections.ts --registry"
+    "generate:deco-sections": "tsx node_modules/@decocms/blocks-cli/scripts/generate-sections.ts --registry",
+    "generate:deco-blocks": "tsx node_modules/@decocms/blocks-cli/scripts/generate-blocks-manifest.ts"
   }
 }
 ```
@@ -215,9 +260,17 @@ site has a reason to put the artifact somewhere else.
   `sectionMeta`/`syncComponents`/`loadingFallbacks`, not the lazy loader map
   `setup.ts` needs for its `sections` option. Defaults to
   `.deco/sections.gen.ts`.
-
-Run both any time `src/sections/` changes (wire into a `predev`/`prebuild`
-step, or a watch script, as your site prefers).
+- `generate:deco-blocks` runs `generate-blocks-manifest.ts`, which emits the
+  static-import blocks manifest (see the recommended-block-source section
+  above) to `.deco/blocksManifest.gen.ts` by default. Regeneration is
+  idempotent — an unchanged block set rewrites nothing, so no-op runs never
+  tickle Next's file watcher.
+
+Run the first two any time `src/sections/` changes, and
+`generate:deco-blocks` any time a block file is **added or removed** in
+`.deco/blocks/` (content edits to existing files don't need it — the static
+imports pick those up by themselves). Simplest is to wire all three into a
+`predev`/`prebuild` `generate` chain.
 
 ## 5. `src/sections/` — the entry-file convention
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@decocms/nextjs",
-  "version": "7.8.0",
+  "version": "7.9.0",
   "type": "module",
   "description": "Deco framework binding for Next.js App Router",
   "repository": {
@@ -25,8 +25,8 @@
     "lint:unused": "knip"
   },
   "dependencies": {
-    "@decocms/blocks": "7.8.0",
-    "@decocms/blocks-admin": "7.8.0"
+    "@decocms/blocks": "7.9.0",
+    "@decocms/blocks-admin": "7.9.0"
   },
   "peerDependencies": {
     "next": ">=15.0.0",

package/src/setup.test.ts

@@ -10,10 +10,11 @@
 import * as fs from "node:fs";
 import * as os from "node:os";
 import * as path from "node:path";
-import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
 import * as cms from "@decocms/blocks/cms";
 import { listRegisteredSections, loadBlocks, setBlocks } from "@decocms/blocks/cms";
+import * as loadDecofileDirectoryModule from "@decocms/blocks/cms/loadDecofileDirectory";
 import { getProductionOrigins } from "@decocms/blocks/sdk/normalizeUrls";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
 
 // Mirrors routeHandlers.test.ts in this same package: @decocms/blocks-admin
 // is mocked (rather than exercised for real) because it's a heavier graph
@@ -127,11 +128,27 @@ describe("createNextSetup", () => {
       });
     });
 
+    it("manifest wiring (blocks + blocksDir: false) is pure — no filesystem read", async () => {
+      // The documented static-import-manifest path: the site passes the
+      // manifest's default export as `blocks` and disables the directory
+      // scan. Bootstrap must never touch the fs — same namespace-spy
+      // technique as the setResolveErrorHandler spies below.
+      const loadDirSpy = vi.spyOn(loadDecofileDirectoryModule, "loadDecofileDirectory");
+
+      const ensureSetup = createNextSetup({
+        blocksDir: false,
+        blocks: { "pages-Home%20(principal)-287364": { path: "/" } },
+        sections: {},
+      });
+      await ensureSetup();
+
+      expect(loadDirSpy).not.toHaveBeenCalled();
+      expect(loadBlocks()["pages-Home%20(principal)-287364"]).toEqual({ path: "/" });
+      loadDirSpy.mockRestore();
+    });
+
     it("options.blocks wins over blocksDir on an overlapping key (merge precedence)", async () => {
-      fs.writeFileSync(
-        path.join(tmpDir, "shared.json"),
-        JSON.stringify({ source: "dir" }),
-      );
+      fs.writeFileSync(path.join(tmpDir, "shared.json"), JSON.stringify({ source: "dir" }));
 
       const ensureSetup = createNextSetup({
         blocksDir: tmpDir,
@@ -158,9 +175,7 @@ describe("createNextSetup", () => {
     });
     await ensureSetup();
 
-    expect(adminMocks.setMetaData).toHaveBeenCalledWith(
-      await meta.mock.results[0]!.value,
-    );
+    expect(adminMocks.setMetaData).toHaveBeenCalledWith(await meta.mock.results[0]!.value);
     expect(adminMocks.setRenderShell).toHaveBeenCalledWith(renderShell);
     expect(adminMocks.setPreviewWrapper).toHaveBeenCalledWith(PreviewWrapper);
   });

package/src/setup.ts

@@ -12,20 +12,30 @@
  * an admin request actually arrives... and because @decocms/blocks-admin
  * is a heavier graph than the CMS core.
  *
- * @example site's `src/deco/setup.ts`
+ * @example site's `src/deco/setup.ts` — recommended wiring: the static-import
+ * blocks manifest (`generate-blocks-manifest`) as the block source, so the
+ * bundler's module graph owns CMS content (dev hot-reload on block edits, no
+ * `outputFileTracingIncludes` for `.deco/blocks` in deploys).
  * ```ts
  * import { createNextSetup } from "@decocms/nextjs/setup";
  * // Generators default to `.deco/`; `deco/*` is a tsconfig path alias for
  * // `.deco/*` (see the package README) since `src/deco/setup.ts` isn't
  * // adjacent to the site-root `.deco/` directory.
+ * import blocks from "deco/blocksManifest.gen";
  * import { sectionImports, sectionMeta, syncComponents } from "deco/sections.gen";
  *
  * export const ensureSetup = createNextSetup({
+ *   blocks,
+ *   blocksDir: false, // manifest IS the directory — skip the runtime fs read
  *   sections: sectionImports,
  *   conventions: { meta: sectionMeta, syncComponents },
  *   meta: () => import("deco/meta.gen.json").then((m) => m.default),
  * });
  * ```
+ * With `blocksDir: false` + `blocks`, this bootstrap is pure — no filesystem
+ * access. Sites that skip the manifest can instead rely on the default
+ * `blocksDir: ".deco/blocks"` runtime read (no dev reload on content edits;
+ * deploys must ship the directory alongside the server bundle).
  */
 import type { ApplySectionConventionsInput } from "@decocms/blocks/cms";
 import { applySectionConventions, loadBlocks } from "@decocms/blocks/cms";
@@ -34,13 +44,21 @@ import { createSiteSetup, type SiteSetupOptions } from "@decocms/blocks/setup";
 
 export interface NextSetupOptions {
   /**
-   * Directory of decofile JSON snapshots, relative to the site root.
-   * Pass `false` to skip filesystem loading (blocks come from `blocks`).
+   * Directory of decofile JSON snapshots, relative to the site root, read
+   * at bootstrap time with a plain fs scan. Pass `false` to skip filesystem
+   * loading entirely (blocks come from `blocks`) — with `blocks` set this
+   * makes the bootstrap pure, which is the recommended manifest wiring (see
+   * the module-level example).
    * @default ".deco/blocks"
    */
   blocksDir?: string | false;
 
-  /** Extra/override blocks, merged OVER the directory's blocks. */
+  /**
+   * Extra/override blocks, merged OVER the directory's blocks. Pass the
+   * default export of a generated static-import manifest
+   * (`generate-blocks-manifest` → `.deco/blocksManifest.gen.ts`) together
+   * with `blocksDir: false` to make the manifest the sole block source.
+   */
   blocks?: Record<string, unknown>;
 
   /**
@@ -80,6 +98,17 @@ export interface NextSetupOptions {
  * *rejected* bootstrap is NOT cached — the memo is cleared on failure so
  * the next call retries from scratch, while the triggering call still
  * rejects with the original error.
+ *
+ * "Lifetime of the module" is exactly what makes the static-import manifest
+ * hot-reload in `next dev`: the site's setup module imports
+ * `blocksManifest.gen.ts`, which statically imports every block JSON, so
+ * editing one invalidates the server module graph up through the setup
+ * module. Next re-evaluates it, `createNextSetup` runs again with the fresh
+ * JSON, and this memo is rebuilt from scratch — that module-graph reset IS
+ * the designed dev reload mechanism for CMS content (measured at ~120–165ms
+ * per edit on a 500-block site). With the default `blocksDir` fs read
+ * instead, nothing imports the JSON, so edits invalidate nothing and dev
+ * serves stale content until a full restart.
  */
 export function createNextSetup(options: NextSetupOptions): () => Promise<void> {
   let setupPromise: Promise<void> | null = null;