Installation

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 18+ - 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 API URL, 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 exporting a CmssyNextConfig built from environment variables, then add those keys to your .env. Copy the values from your workspace's Settings → Headless page in the cmssy dashboard:

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

A typical cmssy site looks like this (see the open-source cmssy-web reference repo):

my-site/
├── app/
│   ├── layout.tsx            # CmssyServerLayout (header/footer)
│   ├── [[...path]]/page.tsx  # createCmssyPage - the catch-all page
│   └── api/draft/route.ts    # createDraftRoute - editor preview
├── blocks/
│   └── hero/
│       ├── block.ts          # defineBlock(...) + fields
│       └── src/index.tsx     # the React component
├── cmssy/
│   ├── config.ts             # CmssyNextConfig + resolveLocale
│   └── blocks.ts             # registry: exports the `blocks` array
└── proxy.ts                  # locale + edit-mode + CSP

Each block lives in its own folder under blocks/ and is registered in cmssy/blocks.ts.

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.
• CMSSY_EDITOR_ORIGIN set to the admin origin (https://www.cmssy.io) - the SDK uses it for the postMessage bridge and the CSP frame-ancestors that lets the admin frame your site.
• 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.

Then open the page editor in the admin - your site loads in the canvas and edits appear instantly. If you see “preview didn't connect”, double-check the Preview URL and CMSSY_EDITOR_ORIGIN.

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" - CMSSY_EDITOR_ORIGIN must be your admin origin (https://www.cmssy.io), and the workspace Preview URL must point at your site.
• Blank page - check CMSSY_API_URL is the full GraphQL endpoint and CMSSY_WORKSPACE_SLUG matches your workspace.
• "Port 3000 already in use" - stop other dev servers or run next dev -p 3001.
• Node.js version error - upgrade to Node.js 18+ using nvm install 18.

Next Steps

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

• Quickstart - build your first block end-to-end
• Block Development - block anatomy, schemas and field types
• Page Builder - editing content in the visual editor