hcms add und die Component Library

Was ist die Component Library?

Die Component Library ist die offizielle Baustein-Bibliothek von Scorebase: eine kuratierte Sammlung aus Blöcken, Components (reine Helfer), Layouts, Pages, Collections, Themes, Menüs, Shops, Formularen und Buchungen sowie zusammengesetzten Modulen und Presets. Statt jeden Baustein neu zu erfinden, kopieren Sie fertige, getippte Ressourcen mit hcms add in Ihr Projekt.

Die Bibliothek liegt als Vorlage component-library vor und ist die Standard-Quelle von hcms add. Sie ist kein hcms init-Ziel – Sie starten Ihr Projekt mit einer der Vorlagen (frontend-starter, shop-storefront …) und ziehen anschliessend Bausteine aus der Bibliothek nach.

Bausteine finden

Vor dem Hinzufügen suchen Sie den passenden Baustein – offline, ohne CMS-Zugriff:

hcms add --list                       # alle Ressourcen, nach Typ gruppiert
hcms library list --category hero     # nur Hero-Bausteine
hcms library list --type block        # nur Blöcke
hcms library search testimonial       # Volltextsuche über Name/Beschreibung/Tags

Mit --json liefern library list und library search maschinenlesbare Ausgaben (Skripting/KI-Agenten). Die Bibliotheks-Metadaten stammen aus cms/library.json bzw. cms/LIBRARY.md.

Bausteine hinzufügen

hcms add <name...> kopiert die Ressource als Code-/CMS-Dateien ins Projekt und ergänzt bei Blöcken die Registry idempotent:

hcms add hero-centered accordion    # zwei Blöcke kopieren
hcms add shop-page                  # Page + genutzte Blöcke + Collections
hcms add pricing-table --overwrite --push

• Blöcke → components/blocks/<file>.tsx + cms/blocks/<slug>.json (die registry.tsx wird idempotent ergänzt).
• Components → reine Code-Datei(en) ohne Registry-Patch.
• Datei-Typen (Collections, Pages, Themes …) → cms/<...>.json am gleichen relativen Pfad.
• Module/Presets → nur Abhängigkeiten; Module mergen zusätzlich Menü-Einträge.

hcms add löst Abhängigkeiten transitiv auf: Eine Page zieht ihre Blöcke und die abgefragten Collections mit, eine Collection ihre Relations-Ziele, ein Modul seine ganze Ressourcen-Kette.

Wichtige Optionen

Mit --push läuft direkt der Deploy in der richtigen Abhängigkeitsreihenfolge: schema → blocks → layouts → theme → pages → menus → forms → content.

Theme-Tokens abgleichen

Jeder Baustein trägt die Theme-Tokens, die er über die genutzten Utility-Klassen braucht. Zwei Befehle halten Tokens und Komponenten konsistent:

hcms tokens check                                  # fehlen installierten Komponenten Tokens?
hcms tokens extract --template component-library   # themeTokens aus genutzten Klassen ableiten
hcms tokens extract --template component-library --check   # nur Drift melden (CI-Gate)

• tokens check prüft projektlokal (components/** gegen <schemaDir>/themes/*.json) und endet mit Exit-Code 1, wenn Tokens fehlen.
• tokens extract leitet aus den tatsächlich genutzten Tailwind-Utility-Klassen die CMS-Theme-Tokens ab (über die @theme-inline-Brücke in app/globals.css) und trägt sie in registry.json ein. Mit --check wird nichts geschrieben – nur Drift gemeldet (Exit-Code 1).

KI-Dokumentation der Bibliothek

hcms library docs erzeugt aus registry.json + Block-Definitionen eine LLM-optimierte Baukasten-Referenz (cms/LIBRARY.md + cms/library.json) mit Index, Grundkonzepten, Feld-/Slot-Tabellen, Usage-Snippets und Theme-Tokens:

hcms library docs                 # LIBRARY.md + library.json generieren
hcms library docs --check         # nur Drift gegen die eingecheckten Dateien prüfen (CI-Gate)

Tipp: hcms add ersetzt nicht das Bauen eigener Blöcke – für einen brandneuen, nicht vorhandenen Block-Typ nutzen Sie weiter den Weg aus dem Artikel „Eigene Blöcke bauen und registrieren".