hcms add und die Component Library
Fertige Blöcke, Pages und Module aus der offiziellen Component Library mit hcms add ins Projekt kopieren – inklusive Theme-Tokens und der library- und tokens-Befehle.
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/TagsMit --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(dieregistry.tsxwird idempotent ergänzt). - Components → reine Code-Datei(en) ohne Registry-Patch.
- Datei-Typen (Collections, Pages, Themes …) →
cms/<...>.jsonam 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
| Option | Wirkung |
|---|---|
--list |
Verfügbare Ressourcen (nach Typ gruppiert) auflisten |
--overwrite |
Vorhandene Dateien ersetzen (sonst überspringen + Checksum-Vergleich) |
--dry-run |
Kompletten Plan zeigen, ohne zu schreiben |
--diff |
Bei abweichenden vorhandenen Dateien einen Zeilen-Diff zeigen |
--menus |
Auch für Einzel-Pages die menuEntries mergen |
--from <template> |
Andere Quelle wählen (z.B. --from restaurant-alpenblick) |
--with-tokens |
Fehlende Theme-Tokens additiv ergänzen |
--push |
Danach die betroffenen Typen in korrekter Reihenfolge pushen |
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 checkprüft projektlokal (components/**gegen<schemaDir>/themes/*.json) und endet mit Exit-Code 1, wenn Tokens fehlen.tokens extractleitet aus den tatsächlich genutzten Tailwind-Utility-Klassen die CMS-Theme-Tokens ab (über die@theme-inline-Brücke inapp/globals.css) und trägt sie inregistry.jsonein. Mit--checkwird 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 addersetzt 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".