Bausteinbibliothek: fertige Blöcke mit hcms add übernehmen
Fertige Blöcke, Seiten, Collections und ganze Module aus der Bausteinbibliothek von Scorebase mit hcms add ins eigene Projekt kopieren, suchen und die Theme-Tokens prüfen.
Worum es geht
Die Bausteinbibliothek (Component Library) ist eine Sammlung fertiger, getesteter Bausteine von Scorebase: Blöcke wie Hero-Varianten, Akkordeons, Preistabellen und Kundenstimmen, ganze Seiten wie Kontakt, Blog oder Impressum, Collections, Formulare und zusammengesetzte Module (z.B. Blog, Newsletter, Webshop, Buchung) sowie Presets. Statt Bausteine neu zu erfinden, kopieren Sie sie mit hcms add in Ihr Projekt – als Code und als Definition für Sites – und passen sie danach frei an.
Die Bibliothek ist in der Kommandozeile enthalten und funktioniert ohne Verbindung zu Sites. Sie ist die Standardquelle von hcms add, aber keine Vorlage für hcms init: Sie starten Ihr Projekt mit einer Vorlage (siehe Eigene Website anbinden) und holen Bausteine danach dazu.
Bausteine finden
hcms add --list # alles, nach Typ gruppiert
hcms library list --category hero # nur Hero-Bausteine
hcms library list --type block # nur Blöcke (auch: component, collection)
hcms library search testimonial # Volltextsuche in Name, Beschreibung, Tagslibrary list und library search geben mit --json maschinenlesbar aus – praktisch für Skripte und KI-Assistenten. Die Beschreibung der Bibliothek liegt im Projekt unter cms/LIBRARY.md und cms/library.json.
Bausteine hinzufügen
hcms add hero-centered accordion # zwei Blöcke
hcms add kontakt-page # eine Seite samt ihrer Blöcke und Collections
hcms add blog # ein ganzes Modul
hcms add pricing-table --overwrite --pushWas dabei entsteht:
| Art | Dateien im Projekt |
|---|---|
| Block | components/blocks/<datei>.tsx und cms/blocks/<slug>.json; der Eintrag in components/blocks/registry.tsx wird ergänzt |
| Component (reiner Helfer) | Nur Code-Dateien, kein Eintrag in der Registry |
| Seite, Collection, Formular | cms/…/<name>.json an der passenden Stelle |
| Modul, Preset | Alle enthaltenen Bausteine; Module ergänzen zusätzlich Menüeinträge |
hcms add löst Abhängigkeiten selbst auf: Eine Seite bringt ihre Blöcke und die abgefragten Collections mit, eine Collection ihre Beziehungsziele, ein Modul seine ganze Kette.
Die Grundbausteine (basisStapel, basisRaster, basisKarte, basisUeberschrift, basisText, basisKnopf und weitere, Kategorie basis) sind in Sites eingebaut. hcms add basisKnopf kopiert deshalb nur die Darstellung (components/blocks/basis-knopf.tsx samt Helfern) und ergänzt die Registry; eine Block-Definition unter cms/blocks entsteht nicht und wird auch nicht gebraucht. Der Frontend-Starter bringt die Grundbausteine schon mit.
Optionen
| Option | Wirkung |
|---|---|
--list |
Verfügbare Bausteine auflisten |
--dry-run |
Nur den Plan zeigen, nichts schreiben |
--overwrite |
Vorhandene Dateien ersetzen (sonst werden sie übersprungen und verglichen) |
--diff |
Bei abweichenden vorhandenen Dateien die Unterschiede zeigen |
--menus |
Auch bei einzelnen Seiten die Menüeinträge ergänzen |
--from <vorlage> |
Andere Quelle, z.B. --from restaurant-alpenblick |
--with-tokens |
Fehlende Theme-Tokens ergänzen (ohne Option nur melden) |
--no-block |
Nur den typisierten Export übernehmen |
--yes |
Rückfrage bei Modulen überspringen |
--push |
Danach alles Betroffene in der richtigen Reihenfolge in Sites übernehmen |
Mit --push gilt die Reihenfolge schema → blocks → layouts → theme → pages → menus → forms → content. Dafür braucht das Token die Berechtigung Verwaltung.
Theme-Tokens prüfen
Jeder Baustein nutzt Theme-Tokens (Farben, Abstände, Rundungen). Fehlen sie in Ihrem Theme, sieht der Baustein nicht aus wie gedacht.
hcms tokens checkDer Befehl prüft die installierten Komponenten (components/**) gegen die Theme-Dateien des Projekts (cms/schema/themes/*.json) und endet mit Fehlercode 1, wenn Tokens fehlen – geeignet als Prüfschritt vor jedem Deployment. Fehlende Tokens ergänzen Sie mit hcms add … --with-tokens oder in Sites im Token-Inventar des Themes (siehe Theme).
Webshop- und Buchungsbausteine
Die Bibliothek enthält auch Bausteine für Laden, Warenkorb, Kasse und Buchung. Sie lesen ihre Daten aus der E-Commerce- und der Termine-App. Wie Sie sie anbinden, steht in Webshop und Buchungen auf der Website.
Tipp:
hcms addersetzt nicht das Bauen eigener Blöcke. Für einen Block, den es in der Bibliothek nicht gibt, gehen Sie vor wie in Eigene Blöcke bauen.
Abgrenzung: Code-Bausteine und Bibliothek fertiger Komponenten
Diese Seite beschreibt die Bausteinbibliothek für Entwickler: Sie kopieren Code mit hcms add in ein Projekt und gestalten ihn dort. Daneben gibt es die Bibliothek fertiger Komponenten in Sites. Sie liefert Komponenten aus Bausteinen, die Sie unter Komponenten ansehen, im Theme Ihrer Umgebung übernehmen und im Komponenten-Builder anpassen, ganz ohne Code. Die fertigen Komponenten setzen sich aus Grundbausteinen zusammen, die Ihre Website bereits zeichnet; es kommt kein neuer Code ins Projekt. Wo Ihre Website einen eigenen Baustein braucht, bleibt hcms add der richtige Weg.
Bausteine mit Paketen
Einige Bausteine bauen auf übernommenem Code auf (Knöpfe, Karten, Eingabefelder, später Kalender und Diagramme). Ihr Eintrag nennt die Pakete, die sie brauchen, im Feld dependencies mit Versionsbereich. hcms add installiert diese Pakete mit. Erlaubt sind nur: radix-ui, lucide-react, class-variance-authority, clsx, tailwind-merge, react-day-picker, date-fns und recharts. Die Elemente liegen unter components/elemente/ und tragen eine Kopfzeile mit Herkunft und Lizenz, die Sie nicht entfernen. Mehr dazu unter Lizenzen der Bibliothek.
In der Vorschau anklicken
Die Bausteine der Bibliothek tragen Vorschau-Markierungen: Im Vorschaufenster wählt ein Klick (im Modus Bearbeiten) die Stelle, und der Editor springt zum passenden Feld. Ausserhalb der Vorschau ändern die Markierungen nichts.
Die Hülle um jeden Block, an der das Vorschaufenster den Block erkennt, legt Ihr Projekt selbst an, nicht der Baustein: die Block-Hülle in components/blocks/registry.tsx. Projekte aus dem aktuellen Frontend-Starter haben sie. Ein älteres Projekt übernimmt components/vorschau/block-huelle.tsx und die Hülle in der Registry aus dem aktuellen Starter; das Muster beschreibt auch die Integrationsanleitung (Kapitel 8, „Markierungen und Block-Hülle“).
Wenn etwas nicht klappt
| Symptom | Ursache | Lösung |
|---|---|---|
| „übersprungen“ bei einer Datei | Die Datei gibt es schon | Mit --diff vergleichen, mit --overwrite ersetzen |
| Der neue Block erscheint nicht im Seiten-Editor | Die Definition ist noch nicht in Sites | hcms blocks push oder hcms add … --push |
| Der Block sieht falsch aus | Theme-Tokens fehlen | hcms tokens check, dann Tokens ergänzen |
| Ein Name wird nicht gefunden | Tippfehler oder Baustein gibt es nicht | hcms library search <begriff> |
| Klick in der Vorschau springt nicht zum Feld | Dem Projekt fehlt die Block-Hülle (älterer Stand) | Hülle aus dem aktuellen Frontend-Starter übernehmen, siehe In der Vorschau anklicken |