Eigene Website anbinden: Schnellstart mit hcms
Schritt für Schritt vom API-Token zur laufenden Website: Projekt mit der Kommandozeile hcms aus einer Vorlage erzeugen, Vorschau und Aktualisierung einrichten, live gehen.
Worum es geht
Inhalte liefert Ihre Inhalte über die Content API aus – die Website selbst ist ein eigenes Projekt. Mit der Kommandozeile hcms steht ein solches Projekt aus einer fertigen Vorlage in wenigen Minuten. Diese Anleitung richtet sich an Entwicklerinnen und Entwickler.
Voraussetzungen
- Node.js ab Version 20 und npm auf Ihrem Rechner.
- Zugang zu Sites mit dem Recht API-Tokens verwalten (für Schritt 1) und Einstellungen verwalten (für Vorschau und Webhook).
- Die Adresse Ihrer Organisation:
https://<ihre-organisation>.scorebase.ch/headless.
Schritt 1: API-Token erstellen
- Öffnen Sie in Sites API-Tokens und klicken Sie auf Token erstellen.
- Name z.B. „Website Entwicklung“. Unter Berechtigungen einschalten: Lesen und Vorschau. Wollen Sie Collections, Blöcke oder Seiten als Code pflegen, zusätzlich Verwaltung.
- Unter Umgebung die Umgebung wählen, gegen die Sie entwickeln.
- Erstellen und das Token sofort kopieren – es wird nur einmal angezeigt.
Details: API-Tokens und erlaubte Herkünfte.
Schritt 2: Projekt erzeugen
npx @kailua-packages/headless-cli init meine-website \
--url https://<ihre-organisation>.scorebase.ch/headless \
--token hcms_live_xxxxxxxx.xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx \
--template frontend-starterDas Paket stellt den Befehl hcms bereit. Fehlen --url oder --token, fragt der Befehl danach. Der Zielordner muss neu oder leer sein.
Verfügbare Vorlagen (--template):
| Vorlage | Inhalt |
|---|---|
frontend-starter |
Standard: schlankes Grundgerüst mit Seiten, Menüs, Theme, Vorschau und Formularen |
minimal |
Fast leer, nur Basis-Blöcke und ein Hauptmenü |
restaurant-alpenblick |
Vollständige Restaurant-Website |
shop-storefront |
Fertiger Webshop, Katalog und Kasse aus der E-Commerce-App |
club-nightlife |
Club-Website mit Ticketverkauf, Lounge-Plan und Buchungskalender |
veranstaltungshaus |
Veranstaltungshaus mit Programm, Tickets, Buchungskalender, Firmenanfrage, Preisen und Lounge-Bestellung |
init erledigt dabei:
- Vorlage in den Ordner kopieren.
.env.localschreiben mitHCMS_URL,HCMS_TOKENund zufällig erzeugten Werten fürREVALIDATE_SECRETundDRAFT_SECRET. Vorlagen mit Webshop, Buchung oder Gastro erhalten zusätzlich leere Platzhalter (EC_…,TERMINE_…,GASTRO_URL); Vorlagen mit Ticketverkauf den öffentlichen PräfixNEXT_PUBLIC_HCMS_SITE.hcms.config.jsonmit der Adresse schreiben.- Abhängigkeiten installieren (überspringen mit
--skip-install). - Die KI-Dokumentation Ihrer Organisation (
cms/llms-full.txt) und die TypeScript-Typen (cms/types.generated.ts) herunterladen.
Die Ausstattung holt init gleich mit
Mit einem Token mit Lesen (dem Website-Token) oder Verwaltung fragt init Ihre Organisation, welche Code-Blöcke ihr Abo erlaubt, und richtet das Projekt entsprechend ein:
- Code-Blöcke hinzufügen: die allgemeinen Blöcke immer, die Blöcke einer App (Shop, Buchung, Ticketing, Gastro) nur mit deren Abo. Am Schluss steht zum Beispiel „68 Code-Blöcke hinzugefügt (allgemein, Shop)“.
- Block-Definitionen in die Umgebung schreiben, aber nur die fehlenden. Vorhandene bleiben unberührt. Das geht nur mit einem Token mit Verwaltung.
- Komponenten der Umgebung nach
cms/komponenten/holen, wenn die Umgebung welche hat. Auch das braucht Verwaltung.
Das Projekt ist danach fertig verdrahtet: Tailwind und die Theme-Brücke sind im Frontend-Starter enthalten, und jeder Block steht in components/blocks/registry.tsx.
Option von init |
Bedeutung |
|---|---|
--env <key> |
Umgebung, in die geschrieben wird (sonst Auswahl bzw. Standard) |
--alle |
Alles holen, was das Abo erlaubt, nicht nur die Vorgabe |
--ohne-bloecke |
Nur das Gerüst, keine Code-Blöcke und keine Definitionen |
--yes |
Keine Rückfragen |
Hat das Token nur Lesen, holt init die Code-Blöcke nach Abo, schreibt aber keine Definitionen und holt keine Komponenten. Dafür nennt init einen Hinweis: einmalig ein Verwaltungs-Token mit --token übergeben (zuerst hcms blocks diff, denn hcms blocks push überschreibt vorhandene Definitionen). Dieses Token gehört nicht in .env.local. Ist der Server nicht erreichbar oder das Token ganz ohne Rechte, meldet init „Abo unbekannt: nur allgemeine Blöcke“ und holt nur diese. Blöcke einer App kommen nie ohne bekanntes Abo. Sie holen sie später mit hcms add --alle. Ist das Token an eine andere Umgebung gebunden als die gewählte, schreibt init nichts in eine fremde Umgebung.
Schritt 3: Lokal starten
cd meine-website
npm run devDie Website läuft unter http://localhost:3000 und zeigt die veröffentlichten Inhalte Ihrer Umgebung. Leer? Dann gibt es noch keine veröffentlichten Seiten. Beispielinhalte spielen Sie mit npx hcms seed --template blog ein (braucht die Berechtigung Verwaltung).
Schritt 4: Vorschau einrichten
Damit die Knöpfe Vorschau und Vorschau öffnen in Sites funktionieren:
- Öffnen Sie Umgebungen, klicken Sie bei der Umgebung auf das Stift-Symbol.
- Tragen Sie als Vorschau-URL ein:
https://<ihre-website>/api/draft?token={token}&path={path}(lokal:http://localhost:3000/api/draft?token={token}&path={path}). - Das Token der Website braucht die Berechtigung Vorschau.
Mehr ist mit frontend-starter nicht nötig: Live-Vorschau (Eingaben erscheinen vor dem Speichern) und Klick zum Feld (ein Klick im Vorschaufenster öffnet die Stelle im Editor) funktionieren ohne weiteres Zutun. Der Link, mit dem Sites das Vorschaufenster öffnet, gilt 120 Sekunden und nur einmal. Danach trägt ein Cookie die Vorschau-Sitzung, höchstens 4 Stunden lang. Vorschau beenden in der Leiste des Vorschaufensters schaltet die Vorschau ab.
Schritt 5: Sofortige Aktualisierung per Webhook
Die Vorlagen speichern Inhalte zwischen. Damit Änderungen sofort sichtbar werden:
- Öffnen Sie Webhooks und klicken Sie auf Webhook erstellen.
- Klicken Sie bei „Next.js Revalidate“ auf Vorlage nutzen. Die passenden Ereignisse werden gewählt.
- URL:
https://<ihre-website>/api/revalidate. - Secret: der Wert von
REVALIDATE_SECRETaus Ihrer.env.local. - Erstellen, danach mit Testen prüfen.
Details: Webhooks.
Schritt 6: Live gehen
- Erstellen Sie ein eigenes Token für die Produktion: nur Lesen (plus Vorschau, wenn die Vorschau auf der Live-Website laufen soll), gebunden an die Umgebung Produktion.
- Nutzt Ihre Website Formulare, die Scorebase-eigene Zählung oder den Ticketverkauf aus dem Browser, tragen Sie beim Token die Adresse Ihrer Website als erlaubte Herkunft ein.
- Setzen Sie bei Ihrem Hosting-Anbieter dieselben Umgebungsvariablen wie in
.env.local, mit dem Produktions-Token.DRAFT_SECRETlassen Sie dort leer. - Stellen Sie Vorschau-URL und Webhook-Adresse auf die Live-Adresse um.
- Prüfen Sie Seiten, Menüs, Formulare und Weiterleitungen auf der Live-Website.
Die Umgebungsvariablen der Website
| Variable | Zweck |
|---|---|
HCMS_URL |
Adresse inklusive /headless (auch …/headless/api/v1 wird akzeptiert) |
HCMS_TOKEN |
API-Token – nur auf dem Server, nie mit NEXT_PUBLIC_ beginnen lassen |
HCMS_ENVIRONMENT |
Optional: Umgebung für alle Anfragen (leer = Standard-Umgebung) |
REVALIDATE_SECRET |
Geheimnis für den Aktualisierungs-Webhook |
DRAFT_SECRET |
Geheimnis, um die Vorschau ohne Link aus Sites zu öffnen (/api/draft?secret=…). Nur lokal; in Produktion leer lassen |
NEXT_PUBLIC_HCMS_SITE |
Öffentlicher Präfix eines Tokens für Aufrufe aus dem Browser (Formulare, Zählung, Tickets) |
Für Webshop und Buchungen kommen EC_URL, EC_TOKEN, NEXT_PUBLIC_EC_KANAL, TERMINE_URL, TERMINE_TOKEN und NEXT_PUBLIC_TERMINE_STRECKE hinzu, siehe Webshop und Buchungen auf der Website.
hcms.config.json
Die Datei liegt im Projekt und darf ins Git-Repository, sie enthält keine Geheimnisse. hcms sucht sie vom aktuellen Ordner aus aufwärts.
{
"url": "https://<ihre-organisation>.scorebase.ch/headless",
"environment": "dev",
"schemaDir": "cms/schema",
"blocksDir": "cms/blocks",
"komponentenDir": "cms/komponenten",
"layoutsDir": "cms/layouts",
"menusDir": "cms/menus",
"pagesDir": "cms/pages",
"formsDir": "cms/forms",
"contentDir": "cms/content",
"typesOut": "cms/types.generated.ts",
"docsOut": "cms/llms-full.txt"
}Reihenfolge: --url vor HCMS_URL vor url in der Datei; --env vor environment. Das Token kommt nur aus --token oder HCMS_TOKEN – ein Feld token in der Datei wird ignoriert.
Die Befehle im Überblick
Im Projekt ist hcms bereits installiert; rufen Sie es mit npx hcms … oder über die npm-Skripte cms:types und cms:docs auf.
| Befehl | Zweck | Berechtigung des Tokens |
|---|---|---|
hcms init [ordner] |
Neues Projekt aus einer Vorlage | Lesen |
hcms types generate |
TypeScript-Typen aus Collections und Blöcken; --watch beobachtet Änderungen, --scaffold-blocks legt fehlende Block-Komponenten an |
Lesen |
hcms docs pull |
KI-Dokumentation llms-full.txt ins Projekt laden |
Lesen |
hcms schema, blocks, layouts, theme, pages, menus, forms mit pull, push, diff |
Struktur als Dateien pflegen, siehe Website als Code | Verwaltung |
hcms komponenten pull / push / diff [slug …] |
Komponenten als Dateien pflegen; Push speichert als Entwurf, --veroeffentlichen stellt live |
Verwaltung |
hcms pull |
Gegenstück zu push: holt alles in die üblichen Ordner (ohne Einträge) und zeigt je Bereich, was neu, geändert oder unverändert ist. Lokal geänderte Dateien werden nicht überschrieben, sondern genannt; --force überschreibt bewusst, --dry-run zeigt nur, --nur, --ohne |
Verwaltung |
hcms push / hcms diff |
Alles auf einmal in fester Reihenfolge (schema, theme, blocks, komponenten, layouts, menus, pages, forms); --nur, --ohne, --dry-run, --veroeffentlichen |
Verwaltung |
hcms content pull / push --collection <slug> |
Einträge als Datei ziehen und idempotent einspielen | Lesen bzw. Schreiben und Veröffentlichen |
hcms media upload / list |
Medien hochladen und auflisten | Verwaltung |
hcms env list, env clone, env status, hcms promote |
Umgebungen | Verwaltung |
hcms seed --template blog |
Beispiel-Collections, -Blöcke, -Layout und -Einträge einspielen | Verwaltung, Schreiben, Veröffentlichen |
hcms add …, hcms library …, hcms tokens check |
Bausteinbibliothek, siehe Bausteinbibliothek; add --alle und add --kategorie <zweck> holen mehrere Blöcke auf einmal |
teilweise ohne Token |
hcms pruefen [--lokal] |
Prüft, ob registry.tsx jeden verwendeten Block-Typ kennt; Ausgangscode 0, 1 oder 2 |
Lesen (mit --lokal keines) |
hcms analytics setup |
Token für die Scorebase-eigene Zählung erzeugen | Verwaltung |
hcms marketplace … |
Marketplace, siehe Marketplace | Verwaltung |
Erst ziehen, dann ändern: hcms pull
Wer Dateien ändert und pusht, kann neuere Änderungen aus der Oberfläche überschreiben. Beginnen Sie deshalb mit hcms pull: Der Befehl holt Schema, Theme, Blöcke, Komponenten, Layouts, Menüs, Seiten, Formulare, Weiterleitungen und die KI-Dokumentation und zeigt je Bereich, wie viele Dateien neu, geändert oder unverändert sind. Einträge gehören bewusst nicht dazu.
- Lokale Änderungen bleiben. Hat sich eine Datei seit dem letzten Pull lokal verändert, überschreibt der Pull sie nicht, sondern nennt sie. Pushen oder sichern Sie Ihre Änderung zuerst. Mit
--forceüberschreiben Sie bewusst. - Nur anzeigen:
hcms pull --dry-runschreibt nichts. - Auswählen:
--nur schema,formszieht nur diese Bereiche,--ohne docslässt einen weg. - Gemerkt wird der Stand in
.hcms/stand.jsonneben derhcms.config.json. Die Datei ist Ihr persönlicher Arbeitsstand und gehört nicht ins Git; die Vorlagen tragen sie in der.gitignoreein.
hcms forms push schickt die beim Pull gesehene Version mit. Wurde das Formular in der Oberfläche seither geändert, lehnt Scorebase den Push ab, bevor etwas geschrieben wird: „Im CMS geändert seit Ihrem letzten Pull“. Führen Sie hcms pull aus und gleichen Sie Ihre Datei ab, oder überschreiben Sie bewusst mit --force. Dateien, die nie gezogen wurden, verhalten sich wie bisher.
hcms --help zeigt alle Befehle und Optionen. Fast alle Struktur-Befehle kennen --dry-run (nur anzeigen, nichts schreiben) und --env <key>.
Blöcke später nachholen: hcms add
npx hcms add --alle --dry-run # Plan zeigen, nichts schreiben
npx hcms add --alle # alle Code-Blöcke, die das Abo erlaubt
npx hcms add --kategorie shop # nur eine Zweck-Gruppe
npx hcms add hero-split pricing-cards # einzelne Blöckeaddist idempotent: Vorhandenes wird übersprungen, ein zweiter Lauf ändert nichts. Eingebaute Blöcke des CMS (section,container,richtextund die Grundbausteine) bringen keine Datei mit.- Die Zweck-Gruppen heissen wie in der Palette des Seiten-Editors (siehe Eigene Blöcke): zum Beispiel
einstieg,preise,fragen,formulare,shop,buchung,ticketing,blog. - Ohne Verbindung (kein Token) gilt der eingebettete Katalog, und der enthält nur die allgemeinen Blöcke.
- Ältere Projekte: Weicht eine gemeinsame Hilfsdatei ab (
components/shared/coerce.ts,media-url.ts), meldetadd„weicht ab“ und überschreibt sie nicht. Vergleichen Sie mit--diff.coerce.tsersetzen Sie mithcms add coerce --overwrite. Hat Ihr Projekt eine Hilfsdatei um eigene Funktionen erweitert, lassen Sie sie stehen und ergänzen nur, was die Blöcke brauchen. - Fehlende Theme-Werte ergänzt
--with-tokens.--pushführt danach die passendenpush-Befehle aus.
Prüfen: kann die Website alles darstellen?
npx hcms pruefen # Seiten, Layouts und Komponenten der Umgebung
npx hcms pruefen --lokal # Dateien unter cms/pages, cms/layouts, cms/komponentenpruefen sammelt alle Block-Typen, die Ihre Inhalte verwenden, und vergleicht sie mit components/blocks/registry.tsx. Fehlt einer, nennt es die Fundstellen und die Behebung, zum Beispiel hcms add pricing-cards, oder bei einem eigenen Block den Hinweis, die Komponente zu ergänzen. Der Ausgangscode ist 0 (alles da), 1 (Lücken) oder 2 (Prüfung nicht möglich, etwa ohne Verbindung oder ohne registry.tsx), also brauchbar in der Pipeline.
Der Frontend-Starter bringt ein Beispiel-Layout mit dem Beispielblock testimonial samt Komponente mit. Ein frisches Projekt ist deshalb ohne Befund (Ausgangscode 0).
Aufbau eines Projekts
cms/
schema/collections/<slug>.json Collections
schema/components/<slug>.json Wiederverwendbare Feldgruppen
schema/themes/<name>.json Theme
blocks/<slug>.json Block-Definitionen
komponenten/<slug>.json Komponenten
layouts/<slug>.json Layouts
pages/<pfad>.<sprache>.json Seiten
menus/<key>.json Menüs
forms/<key>.json Formulare
content/<slug>.json Einträge einer Collection
types.generated.ts erzeugte Typen (nicht von Hand ändern)
llms-full.txt KI-Dokumentation
client.ts Zugriff auf die Content API
components/blocks/
registry.tsx Block-Slug → Komponente
<slug>.tsx eine Komponente je Block
app/api/draft, app/api/revalidate Vorschau und Aktualisierung
Layouts und Seiten als Datei
Jede Datei unter cms/layouts trägt kind: frame ist ein Layout, der Rahmen um Ihre Seiten (Kopf, Inhaltsbereich, Fuss), mit den Seiten verbunden; template ist eine Seitenvorlage, deren Blöcke beim Anlegen einer Seite kopiert werden. Ein Layout kann zusätzlich "isDefault": true tragen und ist dann der Standard der Umgebung. Die Art lässt sich nach dem Anlegen nicht mehr ändern.
Eine Seitendatei unter cms/pages wählt ihr Layout mit layoutSlug (der Slug eines Layouts; null heisst Standard der Umgebung) oder mit "noLayout": true bewusst keines: dann zeichnet Ihre Website den Rahmen selbst. Fehlt layoutSlug, bleibt beim Ändern die bisherige Wahl, beim Anlegen gilt der Standard. Ein unbekannter Slug wird abgelehnt. hcms push spielt Layouts vor den Seiten ein.
Wenn etwas nicht klappt
| Symptom | Ursache | Lösung |
|---|---|---|
npx hcms findet den Befehl nicht |
Ausserhalb eines Projekts ist hcms nicht installiert |
npx @kailua-packages/headless-cli … verwenden oder im Projektordner arbeiten |
| „Zielordner ist nicht leer“ | init schreibt nur in neue oder leere Ordner |
Anderen Namen wählen |
Fehler 401 UNAUTHORIZED |
Token unvollständig kopiert oder widerrufen | Neues Token erstellen |
Fehler 403 FORBIDDEN |
Dem Token fehlt die Berechtigung (z.B. Verwaltung für schema push) |
Token mit passender Berechtigung erstellen |
| Meldung „Grenze der Verwaltungs-Schnittstelle erreicht (60 Anfragen pro Minute) – warte 15 s …“ | Pro Token sind 60 Anfragen pro Minute erlaubt; hcms pull, push und diff mit vielen Seiten kommen darüber |
Nichts tun: die CLI wartet und versucht es selbst erneut (bis zu rund zwei Minuten). Erst danach bricht sie mit Fehler 429 RATE_LIMIT_EXCEEDED ab; dann eine Minute warten und den Befehl wiederholen |
| Die Website zeigt keine Inhalte | Nichts veröffentlicht, oder Token an eine andere Umgebung gebunden | Veröffentlichen; Umgebung des Tokens prüfen |
Warnung „types generate fehlgeschlagen“ nach init |
Keine Verbindung oder Token ohne Lesen | Später npx hcms types generate ausführen |
init meldet „Abo unbekannt“ |
Token ohne Lesen und Verwaltung, Server nicht erreichbar oder zu viele Anfragen | Website-Token (Lesen) verwenden bzw. später erneut versuchen, danach hcms add --alle |
pruefen meldet einen fehlenden Block-Typ |
Die Seite verwendet einen Block, den registry.tsx nicht kennt |
Die genannte Behebung ausführen (hcms add <block>) oder die eigene Komponente eintragen |
| Der Build bricht mit „Module not found“ in einem Block ab | Eine gemeinsame Hilfsdatei fehlt oder ist in einem älteren Projekt veraltet | hcms add <block> ausführen, bei „weicht ab“ mit --diff vergleichen und gezielt überschreiben |