@cmssy/next

Next.js (App Router) bindings for a cmssy headless site. One catch-all route renders your published cmssy content with local block components, with live edit-mode preview built in. Pairs with @cmssy/react (blocks + data).

pnpm add @cmssy/next @cmssy/react

Render every page

// app/[[...path]]/page.tsx
import { createCmssyPage } from "@cmssy/next";
import { cmssy } from "@/cmssy/config";
import { blocks } from "@/cmssy/blocks";
import { CmssyEditor } from "@/cmssy/editor";

export default createCmssyPage(cmssy, blocks, { editor: CmssyEditor });

// cmssy/config.ts
import type { CmssyNextConfig } from "@cmssy/next";

export const cmssy: CmssyNextConfig = {
  apiUrl: process.env.CMSSY_API_URL ?? "", // public GraphQL delivery endpoint
  workspaceSlug: process.env.CMSSY_WORKSPACE_SLUG ?? "",
  draftSecret: process.env.CMSSY_DRAFT_SECRET ?? "", // edit-mode preview handshake
  editorOrigin: process.env.CMSSY_EDITOR_ORIGIN ?? "", // only needed in edit mode
  defaultLocale: "en",
};

createCmssyPage fetches the page for the request path and renders it. In edit mode (draft cookie or ?cmssyEdit=1) it renders your editor instead and frames the live-edit bridge. A published build does not require editorOrigin.

Draft preview

// app/api/draft/route.ts
import { createDraftRoute } from "@cmssy/next";
export const GET = createDraftRoute(cmssy);

Edit-mode CSP

import { cmssyCspHeaders, applyCmssyCsp } from "@cmssy/next";

Helpers to frame the page inside the cmssy editor only in edit mode.

Localized navigation (path prefix)

The active locale lives in the URL path prefix (/en/about; the default locale stays bare). createCmssyPage resolves it and exposes it via CmssyLocaleProvider. For the locale to survive navigation, internal links must carry the prefix - use CmssyLink instead of next/link / <a>:

// any block component
import { CmssyLink } from "@cmssy/next/client";

<CmssyLink href="/about">About</CmssyLink>; // → /en/about while EN is active

Add middleware so the root layout (which can't read the path) resolves the right locale via getCmssyLocale. On Next.js 16 the file is proxy.ts (the renamed middleware convention); on Next.js 15 use middleware.ts with the same body.

// proxy.ts (Next.js 16) — or middleware.ts on Next.js 15
import { createCmssyLocaleMiddleware } from "@cmssy/next";
import { cmssy } from "@/cmssy/config";

export const proxy = createCmssyLocaleMiddleware(cmssy);
export const config = { matcher: ["/((?!_next/|api/|.*\\..*).*)"] };

On Next.js 15, name the file middleware.ts and rename the export to middleware (export const middleware = createCmssyLocaleMiddleware(cmssy)).

Language switcher and raw markup helpers live in @cmssy/react: buildLocaleSwitchHref(target, pathname, locale), localizeHref(href, locale), localizeHtmlLinks(html, locale).

Exports

createCmssyPage, createDraftRoute, cmssyCspHeaders / applyCmssyCsp, isCmssyEditRequest / isCmssyEditMode, createCmssyLocaleMiddleware / resolveLocaleFromPathname, the CmssyNextConfig type, and from @cmssy/next/client: CmssyLink, CmssyLocaleProvider, useCmssyLocale.

License

MIT