Now with AI-powered page building via MCP Server
Start from a working example

Prefer a runnable starting point? Clone the open-source starter cmssy-io/cmssy-next-starter - a Next.js app with three example blocks (hero, prose, blog-index) - or deploy it to Vercel in one click. To see it render real content immediately, use the public demo workspace slug cmssy-demo.

Installation

Get up and running with Cmssy in under 5 minutes.

Last updated: June 29, 2026

Prerequisites

A Cmssy site is a standard Next.js (App Router) project that renders your published content with the Cmssy SDK. You'll need:

  • Node.js 20+ - we recommend nvm
  • pnpm - our recommended package manager (npm and yarn also work)
  • A Next.js App Router app - new or existing
  • A Cmssy workspace - for the workspace slug and draft/editor settings

Install the SDK

Add the two SDK packages to your Next.js project:

Create a Next.js app

Starting fresh? Scaffold an App Router project, then add the SDK. (Or skip this and use your existing app.)

Configure

Create cmssy.config.ts that calls defineCmssyConfig, then add the keys below to your .env. Copy the values from your workspace's Settings → Headless page in the Cmssy dashboard. On cmssy cloud apiUrl and editorOrigin default automatically:

VariableWhat it isRequired
CMSSY_ORG_SLUGYour organization slugYes
CMSSY_WORKSPACE_SLUGYour workspace slug (resolves the workspace id)Yes
CMSSY_DRAFT_SECRETSecret that unlocks draft / preview modeYes
CMSSY_REVALIDATE_SECRETSecret for the on-publish ISR revalidation webhookYes
CMSSY_API_URLGraphQL delivery endpoint. Defaults to https://api.cmssy.io/graphqlSelf-host / staging only
CMSSY_EDITOR_ORIGINAdmin origin that frames your site. Defaults to https://www.cmssy.ioSelf-host only

Keep these secret - never commit .env to version control. In production, set the same variables in your hosting provider (e.g. your Vercel project settings).

Project structure

Every cmssy app has the same four pieces, whatever the framework:

your-app/
├── page entry     # renders cmssy blocks into your components (catch-all route)
├── blocks         # your block components + the blocks registry array
├── config         # workspace slug, draft secret and delivery API
└── edit route     # mounts the visual editor for live preview

The concrete files differ per framework - Next.js, Astro and Remix each lay these out their own way. See Rendering for the per-framework setup.

Start development

Run the Next.js dev server:

Open http://localhost:3000 - your site renders published Cmssy content.

Editor preview

To edit content visually with live preview, the Cmssy editor frames your deployed (or local) site in an iframe. For your project to show up in the editor, you need:

  • Your workspace Preview URL (Settings → Headless) set to your site - e.g. https://your-site.com, or http://localhost:3000 while developing.
  • The draft route app/api/draft/route.ts = createDraftRoute(cmssy) so the editor can enter preview / draft mode.
  • proxy.ts applying the CSP via applyCmssyCsp in edit mode.

On cmssy cloud the editor origin is configured for you. If you self-host the admin, set CMSSY_EDITOR_ORIGIN to your admin origin - the SDK uses it for the postMessage bridge and the CSP frame-ancestors that lets the admin frame your site. Then open the page editor in the admin - your site loads in the canvas and edits appear instantly.

Deploy

Deploy like any Next.js app (e.g. Vercel). Set the same environment variables in your hosting provider, then point your workspace's Preview URL at the deployed site so the editor can frame it.

Updating the SDK

Bump both packages together to pick up SDK fixes, then redeploy:

Troubleshooting

Common issues

  • "Preview didn't connect" - check the workspace Preview URL points at your site. If you self-host the admin, CMSSY_EDITOR_ORIGIN must be your admin origin.
  • Blank page - check CMSSY_WORKSPACE_SLUG matches your workspace (and, if self-hosting, that CMSSY_API_URL is the full GraphQL endpoint).
  • "Port 3000 already in use" - stop other dev servers or run next dev -p 3001.
  • Node.js version error - upgrade to Node.js 20+ using nvm install 20.

Next Steps

Now that you're set up, explore the following guides:

Terminal
pnpm add @cmssy/next @cmssy/react

# or with npm
npm install @cmssy/next @cmssy/react
Fastest start

The quickest path: run pnpm add @cmssy/next @cmssy/react, add cmssy.config.ts with your workspace slug and draft secret, a catch-all app/[[...path]]/page.tsx using createCmssyPage, and the draft route - then pnpm dev. The steps below walk through each file.

Terminal
pnpm create next-app@latest my-site
# App Router: Yes

cd my-site
pnpm add @cmssy/next @cmssy/react
import { defineCmssyConfig } from "@cmssy/next";

// Pass process.env raw: defineCmssyConfig validates at startup and names any
// variable you are missing. A `?? ""` fallback would hide that, and the error
// would surface later, somewhere unrelated.
//
// This module reads server env. Never import a VALUE from it (or from a module
// that imports it) in a "use client" component - types are erased, values drag
// process.env into the browser bundle.
export const cmssy = defineCmssyConfig({
  org: process.env.CMSSY_ORG_SLUG,
  workspaceSlug: process.env.CMSSY_WORKSPACE_SLUG,
  draftSecret: process.env.CMSSY_DRAFT_SECRET,
});
Copy your .env from Settings → Headless

Open Settings → Headless in the Cmssy dashboard and copy each value into your project's .env:

CMSSY_ORG_SLUG=your-org
CMSSY_WORKSPACE_SLUG=your-workspace
CMSSY_DRAFT_SECRET=your-draft-secret
CMSSY_REVALIDATE_SECRET=your-revalidate-secret

apiUrl and editorOrigin default to cmssy cloud, so you don't set them - add CMSSY_API_URL / CMSSY_EDITOR_ORIGIN only for local dev or self-hosting. Keep secrets out of version control; in production set the same vars in your host (e.g. Vercel project settings).

Terminal
pnpm dev

# Next.js dev server -> http://localhost:3000
Terminal
# Deploy to Vercel
vercel

# or just push to your connected Git repo
git push
SDK versioning

Bump your @cmssy/* packages together - your framework package (@cmssy/next, @cmssy/astro or @cmssy/remix) peer-depends on a matching @cmssy/react. After bumping, run pnpm install and redeploy.

Terminal
pnpm up @cmssy/next @cmssy/react

# check the installed version
pnpm why @cmssy/react