Installation

Voraussetzungen

• Node.js 20+ - wir empfehlen nvm
• pnpm - npm, yarn und bun funktionieren ebenfalls; die CLI gibt den Installationsbefehl aus, der zu deinem Lockfile passt
• Ein cmssy-Workspace und ein API-Token - das Token legst du unter Settings → API Tokens an; es verbindet die App mit dem Workspace
• Eine Next.js-App (App Router), neu oder bestehend. Die CLI verdrahtet auch Astro- und React-Router-7-Apps - die Dateien unterscheiden sich, die Schritte unten nicht.

App anlegen und cmssy verdrahten

Erzeuge eine Next.js-App (oder wechsle per cd in deine bestehende) und lass die CLI sie verdrahten. cmssy init erkennt das Framework, kopiert die Verdrahtungsdateien in dein Repo, trägt @cmssy/next, @cmssy/react und @cmssy/core in die package.json ein und listet jede geschriebene Datei mit einer Zeile dazu, wofür sie da ist.

npx create-next-app@latest my-site   # App Router: yes
cd my-site
npx @cmssy/cli@latest init
pnpm install

Was init schreibt

Jede Datei ist gewöhnlicher Code in deinem Repository - öffnen, ändern, dahinter steckt keine versteckte Laufzeit:

Bereits vorhandene Dateien werden übersprungen und aufgelistet; --force überschreibt sie. Unter src/, wenn die App eines nutzt. Wenn die App lintet und keine eigene Konfiguration hat, legt init zusätzlich eine eslint.config.mjs mit dem cmssy-Plugin an. Die vollständige Beschreibung jeder Datei steht auf der Seite CLI.

App mit dem Workspace verbinden

cmssy link schreibt CMSSY_ORG_SLUG, CMSSY_WORKSPACE_SLUG und CMSSY_DRAFT_SECRET in .env.local und prüft sie gegen die API - ein Tippfehler fällt hier auf und nicht beim ersten Rendern.

npx @cmssy/cli@latest link --token cs_...

Ohne --token liest die CLI CMSSY_API_TOKEN. Bei einem Token eines Nutzers mit mehreren Workspaces fragt sie, welcher gemeint ist; --workspace <slug> überspringt die Frage.

Die Umgebung an einem Ort

cmssy.config.ts reicht sie unverändert an defineCmssyConfig weiter. Die Validierung beim Start nennt jede fehlende Variable beim Namen - ein ?? ""-Fallback würde das verstecken, und der Fehler tauchte später an einer unbeteiligten Stelle auf.

import { defineCmssyConfig } from "@cmssy/next";

export const cmssy = defineCmssyConfig({
  org: process.env.CMSSY_ORG_SLUG,
  workspaceSlug: process.env.CMSSY_WORKSPACE_SLUG,
  draftSecret: process.env.CMSSY_DRAFT_SECRET,
});

Halte .env.local aus der Versionskontrolle heraus. In Produktion setzt du dieselben Variablen bei deinem Hoster (z. B. in den Vercel-Projekteinstellungen).

Entwicklung starten

pnpm dev   # http://localhost:3000

Öffne http://localhost:3000 - die App rendert die veröffentlichten Seiten deines Workspace mit den Blöcken aus cmssy/blocks.ts.

Editor-Vorschau

Der Editor bettet deine Site in ein iframe ein und bearbeitet sie live. Die Draft-Route und die CSP in proxy.ts sind seit init vorhanden; auf deine Site zeigt genau eine Einstellung:

• Während der Entwicklung aktivierst du im Editor den Dev host mit http://localhost:3000. Dieses Ziel gehört nur dir und berührt nichts Gemeinsames.
• Für die deployte Site setzt du die Preview URL des Workspace (Settings → Headless) - z. B. https://deine-site.com.

In der cmssy-Cloud ist der Editor-Origin für dich konfiguriert. Hostest du den Admin selbst, setze CMSSY_EDITOR_ORIGIN auf dessen Origin - das SDK nutzt ihn für die postMessage-Bridge und für die CSP frame-ancestors, die dem Admin das Einbetten erlaubt.

Deployment

Deploye wie jede Next.js-App. Setze beim Hoster dieselben Umgebungsvariablen, inklusive CMSSY_WEBHOOK_SECRET, richte den content.changed-Webhook auf https://deine-site.com/api/revalidate, damit eine Veröffentlichung ohne Redeploy sichtbar wird, und setze die Preview URL des Workspace auf die deployte Site.

vercel        # oder Push ins Git-Repo, das dein Hoster beobachtet

SDK aktualisieren

Hebe die @cmssy/*-Pakete gemeinsam an - @cmssy/next hat Peer-Dependencies auf passende @cmssy/react und @cmssy/core. Die CLI wird nicht installiert; npx @cmssy/cli@latest führt immer die aktuelle aus.

pnpm up @cmssy/next @cmssy/react @cmssy/core
pnpm why @cmssy/react   # installierte Version prüfen

Von Hand verdrahten

init ist ein Dateikopierer, nicht mehr. Wenn du die Dateien lieber selbst anlegst oder erst lesen willst, was jede tut, bevor du ihr vertraust: Der Aufbau pro Framework steht unter Rendering, und die Seite CLI listet jede Datei, die init schreibt - für Next.js, Astro und React Router.

Fehlerbehebung

• init meldet: Datei existiert, übersprungen - die App hatte sie schon (meist proxy.ts oder ein Root-Layout). init überschreibt nie ohne --force; vergleiche deine Datei mit der, die init schreiben würde, und führe sie von Hand zusammen.
• link: "no API token given" - übergib --token cs_... oder setze CMSSY_API_TOKEN. Das Token kommt aus Settings → API Tokens.
• "Preview didn't connect" - Dev host oder die Preview URL des Workspace muss auf die laufende Site zeigen. Beim selbst gehosteten Admin muss CMSSY_EDITOR_ORIGIN dessen Origin sein.
• Leere Seite - CMSSY_WORKSPACE_SLUG muss zu deinem Workspace passen (und beim Self-Hosting muss CMSSY_API_URL der vollständige GraphQL-Endpunkt sein).
• "Port 3000 already in use" - stoppe andere Dev-Server oder starte next dev -p 3001 und richte den Dev host auf diesen Port.
• Node.js-Versionsfehler - aktualisiere mit nvm install 20 auf Node.js 20+.

Nächste Schritte

• Dein erster Block, live - von diesem Setup zu einem Block, den du geschrieben, im Editor bearbeitet und veröffentlicht hast
• Block-Entwicklung - Aufbau eines Blocks, Schemas und Feldtypen
• Page Builder - Inhalte im visuellen Editor bearbeiten