Jetzt mit KI-gestütztem Page Building über den MCP-Server
Starte mit einem funktionierenden Beispiel

Du möchtest lieber einen lauffähigen Ausgangspunkt? Klone den Open-Source-Starter cmssy-io/cmssy-next-starter - eine Next.js-App mit drei Beispiel-Blöcken (hero, prose, blog-index) - oder deploye ihn mit einem Klick auf Vercel. Um sofort echte Inhalte zu sehen, nutze den öffentlichen Demo-Workspace-Slug cmssy-demo.

Installation

Starte mit Cmssy in unter 5 Minuten.

29. Juni 2026

Voraussetzungen

Eine Cmssy-Site ist ein normales Next.js (App Router)-Projekt, das deine veröffentlichten Inhalte mit dem Cmssy SDK rendert. Du brauchst:

  • Node.js 20+ - wir empfehlen nvm
  • pnpm - unser empfohlener Paketmanager (npm und yarn funktionieren auch)
  • Eine Next.js App Router App - neu oder bestehend
  • Einen Cmssy-Workspace - für den Workspace-Slug und die Draft-/Editor-Einstellungen

SDK installieren

Füge die beiden SDK-Pakete zu deinem Next.js-Projekt hinzu:

Eine Next.js-App erstellen

Du startest bei null? Erstelle ein App-Router-Projekt und füge dann das SDK hinzu. (Oder überspringe diesen Schritt und nutze deine bestehende App.)

Konfigurieren

Erstelle cmssy.config.ts, das defineCmssyConfig aufruft, und füge dann die folgenden Schlüssel zu deiner .env hinzu. Kopiere die Werte von der Seite Settings → Headless deines Workspace im Cmssy-Dashboard. In der cmssy cloud apiUrl und editorOrigin haben automatische Defaults:

VariableBedeutungErforderlich
CMSSY_ORG_SLUGDein Organisations-SlugJa
CMSSY_WORKSPACE_SLUGDein Workspace-Slug (löst die Workspace-ID auf)Ja
CMSSY_DRAFT_SECRETSecret, das den Draft-/Preview-Modus freischaltetJa
CMSSY_REVALIDATE_SECRETSecret für den ISR-Revalidierungs-Webhook beim PublishJa
CMSSY_API_URLGraphQL-Delivery-Endpoint. Standard: https://api.cmssy.io/graphqlNur Self-Host / Staging
CMSSY_EDITOR_ORIGINAdmin-Origin, der deine Site einbettet. Standard: https://www.cmssy.ioNur Self-Host

Halte diese Werte geheim - committe .env nie in die Versionskontrolle. Setze in Produktion dieselben Variablen bei deinem Hosting-Anbieter (z. B. in den Vercel-Projekteinstellungen).

Projektstruktur

Jede cmssy-App hat dieselben vier Teile, egal welches Framework:

your-app/
├── page entry     # rendert cmssy-Blöcke in deine Komponenten (Catch-all-Route)
├── blocks         # deine Block-Komponenten + das blocks-Registry-Array
├── config         # Workspace-Slug, Draft-Secret und Delivery-API
└── edit route     # bindet den visuellen Editor für die Live-Vorschau ein

Die konkreten Dateien unterscheiden sich je nach Framework - Next.js, Astro und Remix ordnen sie jeweils anders an. Siehe Rendering für das Setup pro Framework.

Entwicklung starten

Starte den Next.js-Dev-Server:

Öffne http://localhost:3000 - deine Site rendert veröffentlichte Cmssy-Inhalte.

Editor-Vorschau

Um Inhalte visuell mit Live-Vorschau zu bearbeiten, bettet der Cmssy-Editor deine deployte (oder lokale) Site in ein iframe ein. Damit dein Projekt im Editor erscheint, brauchst du:

  • Die Preview URL deines Workspace (Settings → Headless), gesetzt auf deine Site - z. B. https://your-site.com oder http://localhost:3000 während der Entwicklung.
  • Die Draft-Route app/api/draft/route.ts = createDraftRoute(cmssy), damit der Editor in den Preview-/Draft-Modus wechseln kann.
  • proxy.ts, das im Edit-Modus die CSP über applyCmssyCsp anwendet.

In der cmssy cloud ist der Editor-Origin bereits für dich konfiguriert. Wenn du den Admin selbst hostest, setze CMSSY_EDITOR_ORIGIN auf deinen Admin-Origin - das SDK nutzt ihn für die postMessage-Bridge und die CSP frame-ancestors, die dem Admin erlaubt, deine Site einzubetten. Öffne dann den Seiteneditor im Admin - deine Site lädt im Canvas und Änderungen erscheinen sofort.

Deployen

Deploye wie jede Next.js-App (z. B. auf Vercel). Setze dieselben Umgebungsvariablen bei deinem Hosting-Anbieter und richte dann die Preview URL deines Workspace auf die deployte Site, damit der Editor sie einbetten kann.

SDK aktualisieren

Aktualisiere beide Pakete zusammen, um SDK-Fixes zu erhalten, und deploye dann neu:

Fehlerbehebung

Häufige Probleme

  • "Preview didn't connect" - prüfe, ob die Preview URL des Workspace auf deine Site zeigt. Wenn du den Admin selbst hostest, muss CMSSY_EDITOR_ORIGIN dein Admin-Origin sein.
  • Leere Seite - prüfe, ob CMSSY_WORKSPACE_SLUG zu deinem Workspace passt (und beim Self-Hosting, dass CMSSY_API_URL der vollständige GraphQL-Endpoint ist).
  • "Port 3000 already in use" - stoppe andere Dev-Server oder starte mit next dev -p 3001.
  • Node.js-Versionsfehler - aktualisiere mit nvm install 20 auf Node.js 20+.

Nächste Schritte

Jetzt, wo alles eingerichtet ist, sieh dir diese Guides an:

Terminal
pnpm add @cmssy/next @cmssy/react

# or with npm
npm install @cmssy/next @cmssy/react
Schnellster Einstieg

Der schnellste Weg: führe pnpm add @cmssy/next @cmssy/react aus, füge cmssy.config.ts mit deinem Workspace-Slug und Draft-Secret hinzu, eine Catch-all-Route app/[[...path]]/page.tsx mit createCmssyPage sowie die Draft-Route - dann pnpm dev. Die Schritte unten gehen jede Datei durch.

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,
});
Kopiere deine .env aus Settings → Headless

Öffne Settings → Headless im Cmssy-Dashboard und kopiere jeden Wert in die .env deines Projekts:

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

apiUrl und editorOrigin haben cmssy cloud als Default, du setzt sie also nicht - füge CMSSY_API_URL / CMSSY_EDITOR_ORIGIN nur für lokale Entwicklung oder Self-Hosting hinzu. Halte Secrets aus der Versionskontrolle heraus; setze in Produktion dieselben Variablen bei deinem Host (z. B. Vercel-Projekteinstellungen).

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-Versionierung

Aktualisiere deine @cmssy/*-Pakete zusammen - dein Framework-Paket (@cmssy/next, @cmssy/astro oder @cmssy/remix) hat eine Peer-Dependency auf ein passendes @cmssy/react. Führe nach dem Update pnpm install aus und deploye neu.

Terminal
pnpm up @cmssy/next @cmssy/react

# check the installed version
pnpm why @cmssy/react