Projekt per CLI aufsetzen (hcms)

Die hcms-CLI

Die Kommandozeile für Website und Inhalte ist das Paket @kailua-packages/headless-cli mit dem Befehl hcms. Es benötigt Node ab Version 20.

npx hcms --help

In einem Projekt wird die CLI meist über npm-Skripte in der package.json aufgerufen:

{
  "scripts": {
    "cms:types": "hcms types generate",
    "cms:docs": "hcms docs pull"
  }
}

Projekt initialisieren

hcms init legt ein komplettes Frontend-Projekt an:

npx hcms init my-site \
  --url https://acme.scorebase.ch/headless \
  --token hcms_live_xxx \
  --template frontend-starter

Der Befehl scaffoldet die Vorlage, schreibt .env.local und hcms.config.json, installiert Abhängigkeiten und führt danach docs pull sowie types generate aus. Fehlen --url oder --token, wird interaktiv nachgefragt. Mit --skip-install überspringen Sie die Installation.

hcms.config.json

Diese Datei liegt im Projekt (sie darf committet werden, sie enthält keine Secrets) und wird von der Arbeitsordner-Position aus nach oben gesucht. Sie definiert die URL, das Standard-Environment und die Verzeichnisse:

{
  "url": "https://acme.scorebase.ch/headless",
  "environment": "dev",
  "schemaDir": "cms/schema",
  "blocksDir": "cms/blocks",
  "layoutsDir": "cms/layouts",
  "menusDir": "cms/menus",
  "pagesDir": "cms/pages",
  "contentDir": "cms/content",
  "typesOut": "cms/types.generated.ts",
  "docsOut": "cms/llms-full.txt"
}

Auflösungs-Reihenfolge: --url (Flag) vor HCMS_URL (Env) vor url in der Config. Für das Environment: --env vor environment in der Config. Das Token stammt nur aus --token oder HCMS_TOKEN.

Wichtigste Befehle im Überblick

Fast alle Struktur-Befehle unterstützen --dry-run (nichts schreiben, nur Diff) und --env <key> (Ziel-Environment).

Aufbau eines Projektverzeichnisses

Nach hcms init finden Sie unter cms/ die code-first Ressourcen sowie im Frontend die Block-Komponenten:

cms/
  schema/collections/<slug>.json   # Sammlungen
  schema/components/<slug>.json     # Wiederverwendbare Feldgruppen
  schema/themes/<name>.json         # Theme-Tokens
  blocks/<slug>.json                # Block-Definitionen
  layouts/<slug>.json               # Layouts
  pages/<path>.<locale>.json        # Seiten
  menus/<key>.json                  # Menüs
  content/<slug>.json               # Einträge einer Sammlung
  types.generated.ts                # generierte Typen (nicht von Hand bearbeiten)
  llms-full.txt                     # KI-Dokumentation
components/blocks/
  registry.tsx                      # Block-Slug -> React-Komponente
  <slug>.tsx                        # eine Komponente pro Block

Tipp: Halten Sie die generierten Dateien types.generated.ts und llms-full.txt aktuell, indem Sie nach jeder Struktur-Änderung hcms types generate bzw. hcms docs pull ausführen.