@decocms/nextjs 7.3.1 → 7.5.0

package/README.md

@@ -0,0 +1,270 @@
+# `@decocms/nextjs`
+
+Deco framework binding for Next.js App Router — the Next.js sibling of
+`@decocms/tanstack`. Three surfaces, composed together:
+
+- **`@decocms/nextjs/config`** — `withDeco(nextConfig)`, a `next.config`
+  wrapper that adds the rewrites and `transpilePackages` Deco's admin
+  protocol needs.
+- **`@decocms/nextjs/routeHandlers`** — `createDecoRouteHandlers({ setup })`,
+  a single catch-all dispatcher for the whole Studio admin protocol
+  (decofile read/reload, meta schema, invoke, live previews).
+- **`@decocms/nextjs/setup`** — `createNextSetup(options)`, a one-call site
+  bootstrap: the Next.js analogue of Vite's
+  `createSiteSetup` + `createAdminSetup` + `import.meta.glob`.
+
+This document is the complete recipe a new Next.js site follows to wire all
+three together. Every code block below is meant to be copied, not
+paraphrased.
+
+## Install
+
+```bash
+bun add @decocms/nextjs @decocms/blocks @decocms/blocks-admin
+```
+
+`next`, `react`, and `react-dom` are peer dependencies — the site already
+has them.
+
+## 1. `next.config` — `withDeco`
+
+`withDeco` adds three rewrites (mapping the Studio-protocol URLs Next.js
+cannot express as route segments onto `/deco/*`, where the catch-all route
+below serves them) and appends the three `@decocms/*` packages (which ship
+raw TypeScript, not a prebuilt `dist/`) to `transpilePackages`.
+
+TypeScript (`next.config.ts`):
+
+```ts
+import type { NextConfig } from "next";
+import { withDeco } from "@decocms/nextjs/config";
+
+const nextConfig: NextConfig = {
+  // ...your own config
+};
+
+export default withDeco(nextConfig);
+```
+
+CommonJS (`next.config.js`) — most Next.js sites still use this form:
+
+```js
+/** @type {import('next').NextConfig} */
+const { withDeco } = require("@decocms/nextjs/config");
+
+const nextConfig = {
+  // ...your own config
+};
+
+module.exports = withDeco(nextConfig);
+```
+
+`withDeco` merges with a `rewrites`/`transpilePackages` you already have —
+it never replaces them. If your own `rewrites()` returns the array form,
+Deco's rewrites are prepended; if it returns the `{ beforeFiles, afterFiles,
+fallback }` object form, Deco's rewrites are prepended to `beforeFiles`.
+
+## 2. The catch-all route
+
+Mount `createDecoRouteHandlers` at `app/deco/[[...deco]]/route.ts` — this
+one file serves the entire admin protocol (decofile, meta, invoke, live
+previews) for both the rewritten public URLs (`/.decofile`, `/live/_meta`,
+`/live/previews/*`) and their `/deco/*` destinations directly.
+
+```ts
+// src/app/deco/[[...deco]]/route.ts
+import { createDecoRouteHandlers } from "@decocms/nextjs/routeHandlers";
+import { ensureSetup } from "../../../deco/setup";
+
+export const dynamic = "force-dynamic";
+
+export const { GET, POST } = createDecoRouteHandlers({ setup: ensureSetup });
+```
+
+`dynamic = "force-dynamic"` is required — this route must never be
+statically cached (decofile reloads, invoke calls, and previews all need a
+fresh response per request).
+
+### Route-handler import rule: subpaths, never the root barrel
+
+**Always import from `@decocms/nextjs/routeHandlers` (or `/config`,
+`/setup`) in a `route.ts` file. Never `import { ... } from "@decocms/nextjs"`
+there.**
+
+App Router route handlers evaluate their entire module graph against
+React's **react-server** build, and this happens regardless of any
+`"use client"` directive in that graph — route handlers have no client
+bundle to move a `"use client"` module into, so the directive is simply
+ignored. The root barrel (`@decocms/nextjs`'s `.` export) re-exports the
+render components (`DecoRootLayout`, `SectionRenderer`, `DecoPageRenderer`,
+...), whose module graph reaches component code that uses client-only React
+APIs (`createContext`, `useContext`, class components with
+`componentDidCatch`, etc.) at module scope. Importing the root barrel from
+a route file pulls that whole graph into react-server evaluation and
+crashes at **import time**, before your handler ever runs, with errors like
+`"...createContext is not a function"` or `"Class extends value undefined
+is not a constructor"` — even if the route handler itself never touches
+those components. The `/routeHandlers`, `/config`, and `/setup` subpaths
+are each scoped to keep their own module graph free of component code, so
+they're safe to import from anywhere, including a route file.
+
+## 3. `src/deco/setup.ts` — `createNextSetup`
+
+The codegen artifacts (`sections.gen.ts`, `meta.gen.json`) are generated into
+`.deco/` at the site root — the same default `@decocms/blocks-cli`'s
+generators use everywhere else (framework artifacts live in the framework's
+folder, not scattered across `src/`). `src/deco/setup.ts` isn't adjacent to
+`.deco/`, so import it through a `deco/*` tsconfig path alias instead of a
+relative path:
+
+```json
+// tsconfig.json
+{
+  "compilerOptions": {
+    "paths": {
+      "deco/*": [".deco/*"]
+    }
+  }
+}
+```
+
+```ts
+// src/deco/setup.ts
+import { createNextSetup } from "@decocms/nextjs/setup";
+import { sectionImports, sectionMeta, syncComponents, loadingFallbacks } from "deco/sections.gen";
+
+export const ensureSetup = createNextSetup({
+  sections: sectionImports,
+  conventions: { meta: sectionMeta, syncComponents, loadingFallbacks },
+  meta: () => import("deco/meta.gen.json").then((m) => m.default),
+});
+```
+
+`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
+from scratch (the triggering call still rejects with the original error).
+
+Two call sites need `ensureSetup()`:
+
+1. **The catch-all route** (above) passes it as `{ setup: ensureSetup }` —
+   `createDecoRouteHandlers` awaits it before dispatching every admin
+   request.
+2. **The root layout** (`app/layout.tsx`) must await it directly before
+   rendering, since page rendering (`createDecoPage`'s resolver) has no
+   setup hook of its own:
+
+   ```tsx
+   // src/app/layout.tsx
+   import { DecoRootLayout } from "@decocms/nextjs";
+   import { ensureSetup } from "../deco/setup";
+
+   export default async function RootLayout({ children }: { children: React.ReactNode }) {
+     await ensureSetup();
+     return <DecoRootLayout siteName="my-site">{children}</DecoRootLayout>;
+   }
+   ```
+
+   (`app/layout.tsx` is a Server Component, not a route handler, so it's
+   fine to import the root barrel here — see the rule above.)
+
+### `NextSetupOptions` at a glance
+
+| 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. |
+| `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"`. |
+| `renderShell` | Admin preview shell config (`{ css, fonts }`). |
+| `previewWrapper` | Admin preview wrapper component. |
+| `productionOrigins`, `customMatchers`, `onResolveError`, `onDanglingReference` | Passed through to `createSiteSetup`. |
+| `extend` | Site-specific wiring that must run *after* core setup (section loaders, legacy SEO key shims, curated post-processing). Receives the loaded blocks. |
+
+## 4. `package.json` scripts — non-colliding names
+
+Add two codegen scripts. **Do not name either 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:
+
+```json
+{
+  "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"
+  }
+}
+```
+
+Neither script needs an `--out`/`--out-file` flag — both generators default
+to `.deco/`, which is exactly where `src/deco/setup.ts` reads them from via
+the `deco/*` path alias (see above). Only pass `--out`/`--out-file` if your
+site has a reason to put the artifact somewhere else.
+
+- `generate:deco-meta` runs `blocks-cli`'s `generate-schema.ts`, which scans
+  `src/sections/`, `src/loaders/`, and `src/apps/` for `Props` interfaces
+  and emits the JSON Schema the admin's `/deco/meta` endpoint serves, to
+  `.deco/meta.gen.json` by default.
+- `generate:deco-sections` runs `generate-sections.ts` **with `--registry`**
+  — the flag that additionally emits `sectionImports`, the Next.js/webpack
+  equivalent of Vite's `import.meta.glob("./sections/**/*.tsx")` (Next has
+  no `import.meta.glob` or Vite plugin, so this is generated instead of
+  computed at build time). Without `--registry` you only get
+  `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).
+
+## 5. `src/sections/` — the entry-file convention
+
+Every non-test `.tsx`/`.ts` file directly under `src/sections/` (recursively)
+becomes a section key, keyed as `site/sections/<path-relative-to-sections-dir>`.
+**This is not opt-in** — `generate-sections.ts` walks the whole directory
+and turns every matching file into a registry entry, whether or not it
+carries any convention exports. Files ending in `.test.ts(x)`, `.spec.ts(x)`,
+`.stories.ts(x)`, or `.gen.ts(x)` are the only ones excluded.
+
+The established pattern is a **thin re-export entry file** per section, with
+the actual component implementation living elsewhere (e.g. alongside its
+own subcomponents, styles, and tests, outside `src/sections/`):
+
+```ts
+// src/sections/Hero.tsx — thin entry file, becomes "site/sections/Hero.tsx"
+export { default } from "../components/Hero/Hero";
+export type { HeroProps as Props } from "../components/Hero/Hero";
+```
+
+This keeps `src/sections/` a clean, flat index of exactly what's
+CMS-addressable, instead of a directory contest between "real" component
+code and registry wiring.
+
+### Convention exports
+
+A section's entry file (or the file it re-exports from — the scanner reads
+the entry file's own source, so re-exported `export const` conventions must
+be re-declared or forwarded on the entry file itself, not just the
+implementation file) can opt into these, each read as a literal
+`export const <name> = <value>`:
+
+| Export | Effect |
+| --- | --- |
+| `export const sync = true` | Bundled synchronously (not lazy-loaded) — for above-the-fold, always-rendered sections. |
+| `export const layout = true` | Cached as a layout section (Header, Footer, Theme) — resolved once, not per-page. |
+| `export const seo = true` | SEO section — its resolved props are merged into page-level SEO. |
+| `export const cache = "listing"` | SWR-cached section loader results, keyed by the given cache name. |
+| `export const eager = true` | Prefers eager rendering (defers only past the fold threshold). |
+| `export const neverDefer = true` | Always eager, ignoring the fold threshold entirely. |
+| `export const clientOnly = true` | Skips SSR — client-only rendering. |
+| `export function LoadingFallback` | Skeleton component shown while the section loads. |
+
+## Verifying your setup
+
+`examples/nextjs-smoke` in this monorepo is a minimal, real Next.js App
+Router build exercising all three surfaces end to end — `withDeco` rewrites,
+the catch-all route, `createNextSetup`, and a resolved page render. Use it
+as a working reference if any of the above doesn't compose the way you
+expect.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@decocms/nextjs",
-  "version": "7.3.1",
+  "version": "7.5.0",
   "type": "module",
   "description": "Deco framework binding for Next.js App Router",
   "repository": {
@@ -11,7 +11,12 @@
   "main": "./src/index.ts",
   "exports": {
     ".": "./src/index.ts",
-    "./routeHandlers": "./src/routeHandlers.ts"
+    "./routeHandlers": "./src/routeHandlers.ts",
+    "./setup": "./src/setup.ts",
+    "./config": {
+      "types": "./src/config.d.cts",
+      "default": "./src/config.cjs"
+    }
   },
   "scripts": {
     "build": "tsc",
@@ -20,8 +25,8 @@
     "lint:unused": "knip"
   },
   "dependencies": {
-    "@decocms/blocks": "7.3.1",
-    "@decocms/blocks-admin": "7.3.1"
+    "@decocms/blocks": "7.5.0",
+    "@decocms/blocks-admin": "7.5.0"
   },
   "peerDependencies": {
     "next": ">=15.0.0",

package/src/config.cjs

@@ -0,0 +1,37 @@
+/**
+ * next.config wrapper for Deco sites. CommonJS on purpose: next.config.js
+ * is CJS in most sites and this package is "type": "module", so a .js
+ * file here would be ESM and unrequireable on Node < 22.
+ *
+ * Adds:
+ * 1. Rewrites for the Studio-protocol URLs Next cannot express as route
+ *    segments — `/.decofile` (segments can't start with a dot) and
+ *    `/live/_meta` (`_`-prefixed segments are Next "private folders",
+ *    silently excluded from routing) — plus `/live/previews/*`, all
+ *    funneled to `/deco/*` where a single catch-all route
+ *    (`app/deco/[[...deco]]/route.ts` + createDecoRouteHandlers) serves
+ *    the whole protocol.
+ * 2. transpilePackages for the raw-TS @decocms packages.
+ */
+const DECO_REWRITES = [
+  { source: "/.decofile", destination: "/deco/decofile" },
+  { source: "/live/_meta", destination: "/deco/meta" },
+  { source: "/live/previews/:path*", destination: "/deco/previews/:path*" },
+];
+
+const DECO_TRANSPILE = ["@decocms/blocks", "@decocms/blocks-admin", "@decocms/nextjs"];
+
+function withDeco(nextConfig = {}) {
+  const userRewrites = nextConfig.rewrites;
+  return {
+    ...nextConfig,
+    transpilePackages: [...new Set([...(nextConfig.transpilePackages ?? []), ...DECO_TRANSPILE])],
+    async rewrites() {
+      const user = typeof userRewrites === "function" ? await userRewrites() : (userRewrites ?? []);
+      if (Array.isArray(user)) return [...DECO_REWRITES, ...user];
+      return { ...user, beforeFiles: [...DECO_REWRITES, ...(user.beforeFiles ?? [])] };
+    },
+  };
+}
+
+module.exports = { withDeco, DECO_REWRITES };

package/src/config.d.cts

@@ -0,0 +1,4 @@
+import type { NextConfig } from "next";
+
+export declare const DECO_REWRITES: Array<{ source: string; destination: string }>;
+export declare function withDeco(nextConfig?: NextConfig): NextConfig;

package/src/config.test.ts

@@ -0,0 +1,47 @@
+import { describe, expect, it } from "vitest";
+import { DECO_REWRITES, withDeco } from "./config.cjs";
+
+// withDeco()'s declared return type is the standard (loosely typed) Next.js
+// NextConfig, whose `rewrites`/`transpilePackages` are optional and
+// union-typed. The runtime object always has them (withDeco always sets
+// them), so tests assert that with `!` / casts rather than loosening the
+// public declaration.
+describe("withDeco", () => {
+  it("adds rewrites and transpilePackages to a bare config", async () => {
+    const cfg = withDeco({});
+    expect(cfg.transpilePackages).toEqual(
+      expect.arrayContaining(["@decocms/blocks", "@decocms/blocks-admin", "@decocms/nextjs"]),
+    );
+    expect(await cfg.rewrites!()).toEqual(DECO_REWRITES);
+  });
+
+  it("prepends deco rewrites to a user's array-returning rewrites()", async () => {
+    const cfg = withDeco({
+      rewrites: async () => [{ source: "/a", destination: "/b" }],
+    });
+    const out = (await cfg.rewrites!()) as Array<{ source: string; destination: string }>;
+    expect(out.slice(0, DECO_REWRITES.length)).toEqual(DECO_REWRITES);
+    expect(out.at(-1)).toEqual({ source: "/a", destination: "/b" });
+  });
+
+  it("merges into a user's object-form rewrites via beforeFiles", async () => {
+    const cfg = withDeco({
+      rewrites: async () => ({
+        beforeFiles: [{ source: "/x", destination: "/y" }],
+        afterFiles: [],
+        fallback: [],
+      }),
+    });
+    const out = (await cfg.rewrites!()) as {
+      beforeFiles: Array<{ source: string; destination: string }>;
+    };
+    expect(out.beforeFiles.slice(0, DECO_REWRITES.length)).toEqual(DECO_REWRITES);
+    expect(out.beforeFiles.at(-1)).toEqual({ source: "/x", destination: "/y" });
+  });
+
+  it("dedupes transpilePackages", () => {
+    const cfg = withDeco({ transpilePackages: ["@decocms/blocks", "other"] });
+    expect(cfg.transpilePackages!.filter((p: string) => p === "@decocms/blocks")).toHaveLength(1);
+    expect(cfg.transpilePackages).toContain("other");
+  });
+});

package/src/routeHandlers.test.ts

@@ -1,6 +1,27 @@
-import { describe, expect, it } from "vitest";
+// @vitest-environment node
+//
+// Route Handlers run server-side with no DOM (same rationale as
+// setup.test.ts in this package). This matters concretely here: jsdom's
+// bundled Request polyfill does not reproduce Node/edge's Request-as-init
+// body-stream forwarding (`new Request(url, existingRequest)`) — under
+// jsdom the body-forwarding test below silently loses the body. Node's
+// native Request (used in this environment, and in the real Next.js
+// runtime) preserves it, which is what the previews-rebuild code path
+// relies on.
+import { beforeEach, describe, expect, it, vi } from "vitest";
+
+const mocks = vi.hoisted(() => ({
+  handleDecofileRead: vi.fn(async () => new Response("decofile")),
+  handleDecofileReload: vi.fn(async () => new Response("reloaded")),
+  handleInvoke: vi.fn(async () => new Response("invoked")),
+  handleMeta: vi.fn(() => new Response("meta")),
+  handleRender: vi.fn(async (req: Request) => new Response(new URL(req.url).pathname)),
+  setMetaData: vi.fn(),
+}));
+vi.mock("@decocms/blocks-admin", () => mocks);
+
 import { setMetaData } from "@decocms/blocks-admin";
-import { metaGET } from "./routeHandlers";
+import { createDecoRouteHandlers, metaGET } from "./routeHandlers";
 
 describe("routeHandlers (next)", () => {
   it("metaGET returns the schema response", async () => {
@@ -9,3 +30,124 @@ describe("routeHandlers (next)", () => {
     expect(response.status).toBe(200);
   });
 });
+
+describe("createDecoRouteHandlers", () => {
+  beforeEach(() => vi.clearAllMocks());
+
+  it("runs setup before dispatching and routes decofile GET/POST", async () => {
+    const order: string[] = [];
+    const setup = vi.fn(async () => {
+      order.push("setup");
+    });
+    const { GET, POST } = createDecoRouteHandlers({ setup });
+
+    await GET(new Request("http://x/deco/decofile"));
+    expect(setup).toHaveBeenCalled();
+    expect(mocks.handleDecofileRead).toHaveBeenCalled();
+
+    await POST(new Request("http://x/deco/decofile", { method: "POST" }));
+    expect(mocks.handleDecofileReload).toHaveBeenCalled();
+  });
+
+  it("routes meta, render, and invoke", async () => {
+    const { GET, POST } = createDecoRouteHandlers();
+    await GET(new Request("http://x/deco/meta"));
+    expect(mocks.handleMeta).toHaveBeenCalled();
+    await POST(new Request("http://x/deco/render", { method: "POST" }));
+    expect(mocks.handleRender).toHaveBeenCalled();
+    await POST(new Request("http://x/deco/invoke/site/actions/x", { method: "POST" }));
+    expect(mocks.handleInvoke).toHaveBeenCalled();
+  });
+
+  it("rebuilds /deco/previews/* URLs to the /live/previews/* prefix handleRender parses", async () => {
+    const { GET } = createDecoRouteHandlers();
+    const res = await GET(new Request("http://x/deco/previews/pages-Home-123?props=x"));
+    expect(await res.text()).toBe("/live/previews/pages-Home-123");
+    const calledUrl = new URL(mocks.handleRender.mock.calls[0][0].url);
+    expect(calledUrl.searchParams.get("props")).toBe("x");
+  });
+
+  it("forwards a POST body through the /deco/previews/* URL rebuild (Request-as-init carries the body stream)", async () => {
+    // Pins the `new Request(rebuilt, request)` semantics documented on the
+    // rebuild line: passing a Request as `init` clones the body stream
+    // without a `duplex` option. A refactor to a plain init object would
+    // throw "duplex option is required" for this POST body.
+    mocks.handleRender.mockImplementationOnce(async (req: Request) => {
+      const body = await req.json();
+      return new Response(JSON.stringify({ pathname: new URL(req.url).pathname, body }));
+    });
+    const { POST } = createDecoRouteHandlers();
+    const res = await POST(
+      new Request("http://x/deco/previews/pages-Home-123", {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({ hello: "world" }),
+      }),
+    );
+    const json = await res.json();
+    expect(json.pathname).toBe("/live/previews/pages-Home-123");
+    expect(json.body).toEqual({ hello: "world" });
+  });
+
+  it("404s unknown deco paths", async () => {
+    const { GET } = createDecoRouteHandlers();
+    const res = await GET(new Request("http://x/deco/nope"));
+    expect(res.status).toBe(404);
+  });
+
+  // Regression coverage for the rewrite-source paths, not just their
+  // /deco/* destinations: a Next.js App Router route handler reached via a
+  // next.config.js `rewrites()` entry sees `request.url` as the ORIGINAL,
+  // pre-rewrite path (verified empirically against a real `next build` +
+  // `next start`) — NOT the /deco/* destination the rewrite maps to. Every
+  // test above this one only ever constructs an already-/deco/*-shaped
+  // Request, so it would keep passing even if the dispatcher only matched
+  // that form and 404'd every real rewritten request — which is exactly
+  // the bug these tests catch.
+  it("routes the rewrite-source /.decofile path (not just its /deco/decofile destination)", async () => {
+    const { GET, POST } = createDecoRouteHandlers();
+    await GET(new Request("http://x/.decofile"));
+    expect(mocks.handleDecofileRead).toHaveBeenCalled();
+    await POST(new Request("http://x/.decofile", { method: "POST" }));
+    expect(mocks.handleDecofileReload).toHaveBeenCalled();
+  });
+
+  it("routes the rewrite-source /live/_meta path (not just its /deco/meta destination)", async () => {
+    const { GET } = createDecoRouteHandlers();
+    const res = await GET(new Request("http://x/live/_meta"));
+    expect(mocks.handleMeta).toHaveBeenCalled();
+    expect(res.status).not.toBe(404);
+  });
+
+  it("405s POST /live/_meta with Allow: GET (the PRE-rewrite URL form)", async () => {
+    const { POST } = createDecoRouteHandlers();
+    const res = await POST(new Request("http://x/live/_meta", { method: "POST" }));
+    expect(res.status).toBe(405);
+    expect(res.headers.get("Allow")).toBe("GET");
+    expect(mocks.handleMeta).not.toHaveBeenCalled();
+  });
+
+  it("routes the rewrite-source /live/previews/* path straight through to handleRender with the prefix intact", async () => {
+    const { GET } = createDecoRouteHandlers();
+    const res = await GET(new Request("http://x/live/previews/pages-Home-123?props=x"));
+    expect(await res.text()).toBe("/live/previews/pages-Home-123");
+    const calledUrl = new URL(mocks.handleRender.mock.calls[0][0].url);
+    expect(calledUrl.searchParams.get("props")).toBe("x");
+  });
+
+  it("405s GET /deco/invoke/* with Allow: POST (CSRF protection — see comment on the invoke branch)", async () => {
+    const { GET } = createDecoRouteHandlers();
+    const res = await GET(new Request("http://x/deco/invoke/site/actions/x"));
+    expect(res.status).toBe(405);
+    expect(res.headers.get("Allow")).toBe("POST");
+    expect(mocks.handleInvoke).not.toHaveBeenCalled();
+  });
+
+  it("405s POST /deco/meta with Allow: GET", async () => {
+    const { POST } = createDecoRouteHandlers();
+    const res = await POST(new Request("http://x/deco/meta", { method: "POST" }));
+    expect(res.status).toBe(405);
+    expect(res.headers.get("Allow")).toBe("GET");
+    expect(mocks.handleMeta).not.toHaveBeenCalled();
+  });
+});

package/src/routeHandlers.ts

@@ -52,3 +52,123 @@ export async function renderGET(request: Request): Promise<Response> {
 export async function renderPOST(request: Request): Promise<Response> {
   return handleRender(request);
 }
+
+export interface DecoRouteHandlersOptions {
+  /**
+   * Site bootstrap, awaited before every admin request — pass the
+   * ensureSetup returned by createNextSetup (@decocms/nextjs/setup).
+   */
+  setup?: () => Promise<void>;
+}
+
+/**
+ * Single catch-all dispatcher for the whole Studio admin protocol. Mount
+ * at `app/deco/[[...deco]]/route.ts` and wrap next.config with
+ * `withDeco()` (@decocms/nextjs/config), whose rewrites map the protocol
+ * URLs Next can't express as segments (`/.decofile`, `/live/_meta`,
+ * `/live/previews/*`) into `/deco/*`:
+ *
+ * ```ts
+ * import { createDecoRouteHandlers } from "@decocms/nextjs/routeHandlers";
+ * import { ensureSetup } from "../../../deco/setup";
+ * export const dynamic = "force-dynamic";
+ * export const { GET, POST } = createDecoRouteHandlers({ setup: ensureSetup });
+ * ```
+ *
+ * `resolveAction` accepts BOTH the rewrite's public source path (e.g.
+ * `/.decofile`, `/live/_meta`, `/live/previews/*`) AND the rewrite's own
+ * destination path (`/deco/*`) — not just the latter. This is load-bearing:
+ * verified empirically against a real `next build && next start` (both
+ * dev and production servers) that a Next.js App Router route handler
+ * reached via a `next.config.js`-level `rewrites()` entry sees
+ * `request.url` (and `NextRequest.nextUrl.pathname`) as the ORIGINAL,
+ * pre-rewrite path the client requested — rewrites are transparent to the
+ * client and, in this respect, to the handler too. Only a *direct* request
+ * to `/deco/*` (bypassing the rewrite, e.g. `/deco/invoke/*`, which has no
+ * public alias) arrives with a `/deco/`-prefixed pathname. Matching only
+ * the `/deco/*` form (as an earlier version of this dispatcher did) makes
+ * every rewritten protocol URL 404 — the dispatcher never sees a
+ * `/deco/decofile`-shaped path in that case, it sees `/.decofile` verbatim.
+ */
+function resolveAction(pathname: string): string {
+  if (pathname.startsWith("/deco/")) return pathname.slice("/deco/".length);
+  if (pathname === "/.decofile") return "decofile";
+  if (pathname === "/live/_meta") return "meta";
+  if (pathname === "/live/previews") return "previews";
+  if (pathname.startsWith("/live/previews/")) {
+    return `previews/${pathname.slice("/live/previews/".length)}`;
+  }
+  return pathname;
+}
+
+export function createDecoRouteHandlers(options: DecoRouteHandlersOptions = {}): {
+  GET(request: Request): Promise<Response>;
+  POST(request: Request): Promise<Response>;
+} {
+  async function dispatch(request: Request): Promise<Response> {
+    await options.setup?.();
+
+    const url = new URL(request.url);
+    const action = resolveAction(url.pathname);
+
+    if (action === "decofile") {
+      return request.method === "POST" ? handleDecofileReload(request) : handleDecofileRead();
+    }
+    if (action === "meta") {
+      // GET only: this is a read-only schema endpoint, no legitimate POST use.
+      if (request.method !== "GET") {
+        return new Response(JSON.stringify({ error: "Method not allowed: meta is GET-only" }), {
+          status: 405,
+          headers: { "Content-Type": "application/json", Allow: "GET" },
+        });
+      }
+      return handleMeta(request);
+    }
+    if (action === "render") return handleRender(request);
+    if (action.startsWith("invoke/")) {
+      // POST only: handleInvoke has no auth of its own and falls back to a
+      // `?props=<json>` query string for GET requests. A GET is a CORS
+      // "simple request" (no preflight), so an unauthenticated
+      // `<img src="https://site/deco/invoke/site/actions/...?props=...">`
+      // on a third-party page would be able to trigger mutating VTEX
+      // actions cross-site (CSRF). The per-route `invokePOST` export this
+      // dispatcher replaces was POST-only for exactly this reason — keep
+      // that restriction here.
+      if (request.method !== "POST") {
+        return new Response(
+          JSON.stringify({ error: "Method not allowed: invoke is POST-only (CSRF protection)" }),
+          {
+            status: 405,
+            headers: { "Content-Type": "application/json", Allow: "POST" },
+          },
+        );
+      }
+      return handleInvoke(request);
+    }
+    if (action === "previews" || action.startsWith("previews/")) {
+      // handleRender parses the literal "/live/previews/" prefix.
+      // `resolveAction` above already normalizes BOTH a direct
+      // `/deco/previews/*` hit and a rewritten `/live/previews/*` hit down
+      // to this same `action` shape, so rebuilding unconditionally here is
+      // a no-op in the rewrite case (rebuilt === original) and the
+      // necessary reconstruction in the direct-hit case.
+      const rest = action === "previews" ? "" : action.slice("previews/".length);
+      const rebuilt = new URL(url);
+      rebuilt.pathname = `/live/previews/${rest}`;
+      // `request` (a Request) is passed as the `init` argument here, not a
+      // plain object — the Request-as-init form clones headers/method/body
+      // (including the body *stream*) without needing an explicit `duplex`
+      // option. Rewriting this as `new Request(rebuilt, { ...request })` or
+      // any plain-object init would throw "duplex option is required" for
+      // POST bodies with a body stream — see the test below that posts a
+      // JSON body through this branch and asserts it still parses.
+      return handleRender(new Request(rebuilt, request));
+    }
+    return new Response(JSON.stringify({ error: `Unknown deco route: ${url.pathname}` }), {
+      status: 404,
+      headers: { "Content-Type": "application/json" },
+    });
+  }
+
+  return { GET: dispatch, POST: dispatch };
+}

package/src/setup.test.ts

@@ -0,0 +1,80 @@
+// @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 { beforeEach, describe, expect, it, vi } from "vitest";
+import { listRegisteredSections, loadBlocks, setBlocks } from "@decocms/blocks/cms";
+import { createNextSetup } from "./setup";
+
+describe("createNextSetup", () => {
+  beforeEach(() => {
+    setBlocks({});
+  });
+
+  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);
+  });
+});

package/src/setup.ts

@@ -0,0 +1,129 @@
+/**
+ * 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`
+ * ```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 { sectionImports, sectionMeta, syncComponents } from "deco/sections.gen";
+ *
+ * export const ensureSetup = createNextSetup({
+ *   sections: sectionImports,
+ *   conventions: { meta: sectionMeta, syncComponents },
+ *   meta: () => import("deco/meta.gen.json").then((m) => m.default),
+ * });
+ * ```
+ */
+import type { ApplySectionConventionsInput } from "@decocms/blocks/cms";
+import { applySectionConventions, loadBlocks } 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.
+   * Pass `false` to skip filesystem loading (blocks come from `blocks`).
+   * @default ".deco/blocks"
+   */
+  blocksDir?: string | false;
+
+  /** Extra/override blocks, merged OVER the directory's blocks. */
+  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.
+ */
+export function createNextSetup(options: NextSetupOptions): () => Promise<void> {
+  let setupPromise: Promise<void> | null = null;
+
+  return function ensureSetup(): Promise<void> {
+    setupPromise ??= (async () => {
+      const dirBlocks =
+        options.blocksDir === false
+          ? {}
+          : await loadDecofileDirectory(options.blocksDir ?? ".deco/blocks");
+      const blocks = { ...dirBlocks, ...options.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;
+  };
+}