@decocms/nextjs 8.1.0-next.0 → 8.5.0

package/src/setup.test.ts

@@ -1,253 +0,0 @@
-// @vitest-environment node
-//
-// createSiteSetup (via @decocms/blocks/setup) only calls setBlocks() when
-// `typeof document === "undefined"` — it's the server-only half of the
-// Vite dual-environment split. Next.js Route Handlers run server-side with
-// no DOM, which is exactly what createNextSetup targets, so this suite runs
-// under vitest's "node" environment rather than the package default
-// (jsdom, used by the component-rendering tests in this same package) to
-// match that real invocation context.
-import * as fs from "node:fs";
-import * as os from "node:os";
-import * as path from "node:path";
-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
-// than the CMS core — see this file's `@example` JSDoc note in setup.ts.
-// The mock applies to every test in this file; existing tests that pass
-// `meta` don't assert on setMetaData's *internal* effects (only that the
-// `meta` loader itself was invoked), so swapping the real setter for a
-// stub doesn't change what they verify.
-const adminMocks = vi.hoisted(() => ({
-  setMetaData: vi.fn(),
-  setRenderShell: vi.fn(),
-  setPreviewWrapper: vi.fn(),
-}));
-vi.mock("@decocms/blocks-admin", () => adminMocks);
-
-import { createNextSetup } from "./setup";
-
-describe("createNextSetup", () => {
-  beforeEach(() => {
-    setBlocks({});
-    vi.clearAllMocks();
-  });
-
-  it("returns a memoized ensureSetup that registers blocks, sections, meta", async () => {
-    const meta = vi.fn().mockResolvedValue({
-      major: 1,
-      version: "test",
-      namespace: "site",
-      site: "test",
-      manifest: { blocks: { sections: {} } },
-      schema: { definitions: {}, root: {} },
-      platform: "test",
-      cloudProvider: "test",
-    });
-    const ensureSetup = createNextSetup({
-      blocksDir: false,
-      blocks: { myBlock: { __resolveType: "site/sections/Hero.tsx" } },
-      sections: { "./sections/Hero.tsx": async () => ({ default: () => null }) },
-      meta,
-    });
-
-    await ensureSetup();
-    await ensureSetup(); // memoized — meta loader must run once
-
-    expect(meta).toHaveBeenCalledTimes(1);
-    expect(loadBlocks().myBlock).toBeDefined();
-    expect(listRegisteredSections()).toContain("site/sections/Hero.tsx");
-  });
-
-  it("applies section conventions when provided", async () => {
-    const ensureSetup = createNextSetup({
-      blocksDir: false,
-      sections: { "./sections/Footer.tsx": async () => ({ default: () => null }) },
-      conventions: { meta: { "site/sections/Footer.tsx": { layout: true } } },
-    });
-    await ensureSetup();
-    const { isLayoutSection } = await import("@decocms/blocks/cms");
-    expect(isLayoutSection("site/sections/Footer.tsx")).toBe(true);
-  });
-
-  it("clears the memo on a rejected bootstrap so the next call retries", async () => {
-    const meta = vi
-      .fn()
-      .mockRejectedValueOnce(new Error("transient fetch failure"))
-      .mockResolvedValueOnce({
-        major: 1,
-        version: "test",
-        namespace: "site",
-        site: "test",
-        manifest: { blocks: { sections: {} } },
-        schema: { definitions: {}, root: {} },
-        platform: "test",
-        cloudProvider: "test",
-      });
-    const ensureSetup = createNextSetup({
-      blocksDir: false,
-      sections: { "./sections/Hero.tsx": async () => ({ default: () => null }) },
-      meta,
-    });
-
-    await expect(ensureSetup()).rejects.toThrow("transient fetch failure");
-    await expect(ensureSetup()).resolves.toBeUndefined();
-    expect(meta).toHaveBeenCalledTimes(2);
-  });
-
-  describe("blocksDir", () => {
-    let tmpDir: string;
-
-    beforeEach(() => {
-      tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), "next-setup-blocksdir-"));
-    });
-
-    afterEach(() => {
-      fs.rmSync(tmpDir, { recursive: true, force: true });
-    });
-
-    it("loads a real string blocksDir path (tmp dir with one JSON decofile)", async () => {
-      fs.writeFileSync(
-        path.join(tmpDir, "myBlock.json"),
-        JSON.stringify({ __resolveType: "site/sections/Hero.tsx" }),
-      );
-
-      const ensureSetup = createNextSetup({
-        blocksDir: tmpDir,
-        sections: { "./sections/Hero.tsx": async () => ({ default: () => null }) },
-      });
-      await ensureSetup();
-
-      expect(loadBlocks().myBlock).toEqual({
-        __resolveType: "site/sections/Hero.tsx",
-      });
-    });
-
-    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" }));
-
-      const ensureSetup = createNextSetup({
-        blocksDir: tmpDir,
-        blocks: { shared: { source: "override" } },
-        sections: {},
-      });
-      await ensureSetup();
-
-      expect(loadBlocks().shared).toEqual({ source: "override" });
-    });
-  });
-
-  it("reaches blocks-admin's setRenderShell, setPreviewWrapper, and setMetaData with the given args", async () => {
-    const meta = vi.fn().mockResolvedValue({ schema: { definitions: {}, root: {} } });
-    const renderShell = { css: "https://cdn.example.com/admin.css", fonts: ["Inter"] };
-    const PreviewWrapper = () => null;
-
-    const ensureSetup = createNextSetup({
-      blocksDir: false,
-      sections: {},
-      meta,
-      renderShell,
-      previewWrapper: PreviewWrapper,
-    });
-    await ensureSetup();
-
-    expect(adminMocks.setMetaData).toHaveBeenCalledWith(await meta.mock.results[0]!.value);
-    expect(adminMocks.setRenderShell).toHaveBeenCalledWith(renderShell);
-    expect(adminMocks.setPreviewWrapper).toHaveBeenCalledWith(PreviewWrapper);
-  });
-
-  it("does not touch blocks-admin's setters when meta/renderShell/previewWrapper are all omitted", async () => {
-    const ensureSetup = createNextSetup({
-      blocksDir: false,
-      sections: {},
-    });
-    await ensureSetup();
-
-    expect(adminMocks.setMetaData).not.toHaveBeenCalled();
-    expect(adminMocks.setRenderShell).not.toHaveBeenCalled();
-    expect(adminMocks.setPreviewWrapper).not.toHaveBeenCalled();
-  });
-
-  it("passes productionOrigins, customMatchers, onResolveError, and onDanglingReference through to createSiteSetup", async () => {
-    const matcher = vi.fn();
-    const onResolveError = vi.fn();
-    const onDanglingReference = vi.fn();
-
-    // onResolveError / onDanglingReference are installed via module-scope
-    // setters (setResolveErrorHandler / setDanglingReferenceHandler) with no
-    // public getter to read the currently-installed handler back — spy on
-    // the real setters on the @decocms/blocks/cms module namespace.
-    // createSiteSetup (called by createNextSetup) imports these same two
-    // names from the identical resolved module ("./cms/index" internally,
-    // "@decocms/blocks/cms" here — same file per package.json's export
-    // map), and Vitest's SSR module transform makes named exports mutable
-    // properties on a shared namespace object, so spying here intercepts
-    // the call made from inside createSiteSetup too.
-    const resolveErrorSpy = vi.spyOn(cms, "setResolveErrorHandler");
-    const danglingRefSpy = vi.spyOn(cms, "setDanglingReferenceHandler");
-
-    const ensureSetup = createNextSetup({
-      blocksDir: false,
-      sections: {},
-      productionOrigins: ["https://www.example.com"],
-      customMatchers: [matcher],
-      onResolveError,
-      onDanglingReference,
-    });
-    await ensureSetup();
-
-    // Cheapest direct observation, per the option's own doc comment: each
-    // customMatchers thunk is called exactly once during setup.
-    expect(matcher).toHaveBeenCalledTimes(1);
-    // productionOrigins has a real, cheap getter — assert the registered
-    // value directly rather than only inferring it went through.
-    expect(getProductionOrigins()).toEqual(["https://www.example.com"]);
-    expect(resolveErrorSpy).toHaveBeenCalledWith(onResolveError);
-    expect(danglingRefSpy).toHaveBeenCalledWith(onDanglingReference);
-
-    resolveErrorSpy.mockRestore();
-    danglingRefSpy.mockRestore();
-  });
-
-  it("calls extend with the merged, loaded blocks", async () => {
-    const extend = vi.fn();
-    const ensureSetup = createNextSetup({
-      blocksDir: false,
-      blocks: { myBlock: { __resolveType: "site/sections/Hero.tsx" } },
-      sections: { "./sections/Hero.tsx": async () => ({ default: () => null }) },
-      extend,
-    });
-    await ensureSetup();
-
-    expect(extend).toHaveBeenCalledTimes(1);
-    expect(extend).toHaveBeenCalledWith(
-      expect.objectContaining({
-        myBlock: { __resolveType: "site/sections/Hero.tsx" },
-      }),
-    );
-  });
-});

package/src/setup.ts

@@ -1,180 +0,0 @@
-/**
- * One-call site bootstrap for Next.js — the App Router sibling of the
- * Vite flow (`createSiteSetup` + `createAdminSetup` + import.meta.glob).
- * Next has no import.meta.glob and no Vite plugin, so this composes the
- * same framework pieces from a generated section registry
- * (`generate-sections --registry`) and a filesystem decofile directory.
- *
- * ROUTE-HANDLER-SAFE: this module (and everything it imports eagerly) must
- * never reach module-scope client-React — it is imported by route files
- * via the site's setup module. Admin setters are imported lazily for the
- * same reason createAdminSetup keeps meta lazy: they're only needed when
- * 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` — 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, setDraftPreviewHosts } from "@decocms/blocks/cms";
-import { loadDecofileDirectory } from "@decocms/blocks/cms/loadDecofileDirectory";
-import { createSiteSetup, type SiteSetupOptions } from "@decocms/blocks/setup";
-
-export interface NextSetupOptions {
-  /**
-   * 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. 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>;
-
-  /**
-   * Lazy section registry — `sectionImports` from
-   * `generate-sections --registry` (keys `./sections/X.tsx`).
-   */
-  sections: Record<string, () => Promise<any>>;
-
-  /** `{ meta: sectionMeta, syncComponents, loadingFallbacks }` from sections.gen.ts (`.deco/sections.gen.ts` by default). */
-  conventions?: Omit<ApplySectionConventionsInput, "sectionGlob">;
-
-  /** Lazy admin meta schema: `() => import("deco/meta.gen.json").then(m => m.default)` (`.deco/meta.gen.json` by default). */
-  meta?: () => Promise<unknown>;
-
-  /** Admin preview shell (CSS/font URLs) — see blocks-admin setRenderShell. */
-  renderShell?: { css?: string; fonts?: string[] };
-
-  /** Admin preview wrapper component. */
-  previewWrapper?: React.ComponentType<any>;
-
-  productionOrigins?: SiteSetupOptions["productionOrigins"];
-  customMatchers?: SiteSetupOptions["customMatchers"];
-  onResolveError?: SiteSetupOptions["onResolveError"];
-  onDanglingReference?: SiteSetupOptions["onDanglingReference"];
-
-  /**
-   * Site-specific wiring that must run after the core setup (section
-   * loaders, SEO keys for legacy decofiles, curated post-processing).
-   * Receives the loaded blocks.
-   */
-  extend?: (blocks: Record<string, unknown>) => void | Promise<void>;
-}
-
-/**
- * Returns a memoized `ensureSetup` function. A successful bootstrap is
- * cached for the lifetime of the module (warm serverless instance); a
- * *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.
- */
-/**
- * Install the site block's `previewHosts` as the draft-preview allowlist.
- *
- * Reads the BASE blocks handed to setup — never `loadBlocks()` at request
- * time, where the draft override is merged in: an allowlist readable through
- * the override could be rewritten by the very draft it gates.
- * `DECO_ALLOWED_PREVIEW_HOSTS` remains an operational override that replaces
- * this list when set.
- */
-function installPreviewHosts(blocks: Record<string, unknown> | undefined): void {
-  const site = blocks?.site as { previewHosts?: unknown } | undefined;
-  if (Array.isArray(site?.previewHosts)) setDraftPreviewHosts(site.previewHosts);
-}
-
-export function createNextSetup(options: NextSetupOptions): () => Promise<void> {
-  let setupPromise: Promise<void> | null = null;
-
-  // Draft preview opt-in from the repo: read SYNCHRONOUSLY at createNextSetup
-  // time (module evaluation), not inside the lazy ensureSetup — pages call
-  // `ensureDraft` BEFORE they resolve CMS content, so hosts installed lazily
-  // would arrive after the gate already said no on the first request.
-  installPreviewHosts(options.blocks);
-
-  return function ensureSetup(): Promise<void> {
-    setupPromise ??= (async () => {
-      const dirBlocks =
-        options.blocksDir === false
-          ? {}
-          : await loadDecofileDirectory(options.blocksDir ?? ".deco/blocks");
-      const blocks = { ...dirBlocks, ...options.blocks };
-      // Covers the blocksDir mode, where blocks only exist after the fs read.
-      installPreviewHosts(blocks);
-
-      createSiteSetup({
-        sections: options.sections,
-        blocks,
-        productionOrigins: options.productionOrigins,
-        customMatchers: options.customMatchers,
-        onResolveError: options.onResolveError,
-        onDanglingReference: options.onDanglingReference,
-      });
-
-      if (options.conventions) {
-        applySectionConventions({
-          ...options.conventions,
-          sectionGlob: options.sections,
-        });
-      }
-
-      if (options.meta || options.renderShell || options.previewWrapper) {
-        const admin = await import("@decocms/blocks-admin");
-        if (options.meta) admin.setMetaData((await options.meta()) as never);
-        if (options.renderShell) admin.setRenderShell(options.renderShell);
-        if (options.previewWrapper) admin.setPreviewWrapper(options.previewWrapper);
-      }
-
-      await options.extend?.(loadBlocks());
-    })().catch((error) => {
-      // A failed bootstrap must not poison the warm instance: clear the memo
-      // so the next request retries (transient fs/fetch failures are the
-      // common case in serverless cold starts). The error still propagates
-      // to THIS caller so the triggering request fails loudly.
-      setupPromise = null;
-      throw error;
-    });
-    return setupPromise;
-  };
-}

package/tsconfig.json

@@ -1,7 +0,0 @@
-{
-  "extends": "../../tsconfig.base.json",
-  "compilerOptions": {
-    "outDir": "dist"
-  },
-  "include": ["src/**/*"]
-}