Jetzt mit KI-gestütztem Page Building über den MCP-Server
Documentation
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.

Last updated: 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 eine CmssyNextConfig exportiert, 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 setzt du nur zwei Werte - apiUrl und editorOrigin haben automatische Defaults:

VariableBedeutungErforderlich
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

Eine typische Cmssy-Site sieht so aus:

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

Jeder Block liegt in einem eigenen Ordner unter blocks/ und wird in cmssy/blocks.ts registriert.

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
cmssy/config.ts
import type { CmssyNextConfig } from "@cmssy/next";

export const cmssy: CmssyNextConfig = {
  workspaceSlug: process.env.CMSSY_WORKSPACE_SLUG ?? "",
  draftSecret: process.env.CMSSY_DRAFT_SECRET ?? "",
  defaultLocale: "en",
  // apiUrl + editorOrigin default to cmssy cloud; set only for self-host/staging.
};
Kopiere deine .env aus Settings → Headless

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

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 @cmssy/react und @cmssy/next zusammen - @cmssy/next 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