Eine Blockregistrierung auf GitHub veröffentlichen
Wenn du ein paar gute Blöcke erstellt hast, möchtest du sie auch im nächsten Projekt verwenden.
Ordner von Hand zwischen Themes zu kopieren funktioniert, bis die Kopien auseinanderlaufen und
niemand mehr weiß, welches Theme die korrigierte Version enthält. Jeden Block in ein
Paket mit eigenem Build-Prozess zu packen, ist viel Aufwand für einen Ordner mit einem
block.json und einem Template.
Eine Blockregistrierung schließt die Lücke. Sie besteht aus einer registry.json-Datei und mehreren
Blockordnern, die über einfaches HTTP bereitgestellt werden. Nutzer führen einen CLI-Befehl aus,
der Blockquelltext wird in ihr Theme kopiert und gehört von da an ihnen. Ein
GitHub-Repository genügt als Host, denn GitHub stellt jede Datei eines
öffentlichen Repositorys unter einer Raw-URL bereit.
In dieser Anleitung erstellst du eine Registry namens acme mit vier Blöcken, veröffentlichst sie aus dem Repository acme/acme-blocks, installierst daraus Blöcke in ein Theme und fixierst ein Release über einen git-Tag.
Das Paket blockstudio auf npm hat die Version 0.0.1. Diese Veröffentlichung ist ein
Platzhalter: Ihr einziger Befehl, add, gibt Adding block: <name> aus und wird beendet,
ohne etwas abzurufen. Die Befehle und Ausgaben in dieser Anleitung stammen aus der
Registrierung CLI im Blockstudio-Repository (packages/registry). Sie entspricht der
CLI, die in der Registrierungsdokumentation beschrieben wird.
Wie die Teile zusammenpassen
Es gibt zwei wichtige Dateien:
registry.jsonwird vom Blockautor veröffentlicht. Die Datei führt die Blöcke, ihre jeweiligen Dateien und einebaseUrlauf, über die sie heruntergeladen werden.blocks.jsonliegt im Theme oder Plugin des Nutzers. Sie gibt die zu verwendenden Registrierungen und das Verzeichnis für die installierten Blöcke an.
Bei der Installation eines Blocks ruft CLI alle Registrierungen aus blocks.json ab,
sucht den Block, löst seine Abhängigkeiten auf, lädt jede aufgeführte Datei von
{baseUrl}/{block}/{file} herunter und speichert sie unter {directory}/{block}/{file}. Die Dateien werden nicht umgewandelt;
auf dem Datenträger entsprechen sie daher exakt den Dateien im Repository.
Schritt 1: Repository strukturieren
Erstelle ein Repository mit einer registry.json im Stammverzeichnis und je einem Ordner pro Block
unter blocks/:
acme-blocks/
registry.json
blocks/
hero/
block.json
index.php
card/
block.json
index.php
style.scss
tabs/
block.json
index.php
style.scss
tab-item/
block.json
index.php
Der Ordnername ist der Name des Blocks in der Registrierung und wird zum Ordnernamen
im Theme des Nutzers. Er muss mit der zweiten Hälfte des Blocknamens in block.json übereinstimmen
(acme/hero liegt in hero/), damit der installierte Ordner leicht zu erkennen ist.
Schritt 2: Blöcke erstellen
Jeder Ordner enthält einen gewöhnlichen Blockstudio-Block. Der Hero-Block hat ein Feld:
{
"$schema": "https://blockstudio.dev/schema/block",
"apiVersion": 3,
"name": "acme/hero",
"title": "Hero",
"category": "design",
"blockstudio": {
"attributes": [
{
"id": "heading",
"type": "text",
"label": "Heading",
"default": "Build faster"
}
]
}
}
<section useBlockProps class="acme-hero">
<h1><?php echo esc_html( $a['heading'] ); ?></h1>
</section>
card folgt demselben Muster und fügt ein style.scss hinzu. tabs gibt
<InnerBlocks allowedBlocks='["acme/tab-item"]' /> aus und tab-item deklariert
"parent": ["acme/tabs"]. Daher ist tabs ohne tab-item nicht sinnvoll. Die
Registrierung bildet diese Abhängigkeit im nächsten Schritt ab.
An diesen Blöcken ist nichts registrierungsspezifisch. Das CLI kopiert Ordner, daher
kannst du Blöcke mit @wordpress/create-block oder mit einfachem PHP auf dieselbe Weise veröffentlichen.
Schritt 3: registry.json erstellen
registry.json führt alle Blöcke und Dateien auf, die das CLI herunterladen soll:
{
"$schema": "https://blockstudio.dev/schema/registry.json",
"name": "acme",
"description": "Acme block library.",
"baseUrl": "https://raw.githubusercontent.com/acme/acme-blocks/main/blocks",
"blocks": [
{
"name": "hero",
"title": "Hero",
"description": "Full-width hero section with a heading.",
"category": "layout",
"type": "blockstudio",
"files": ["block.json", "index.php"]
},
{
"name": "card",
"title": "Card",
"description": "Content card with a title.",
"category": "components",
"type": "blockstudio",
"files": ["block.json", "index.php", "style.scss"]
},
{
"name": "tabs",
"title": "Tabs",
"description": "Tabbed content with keyboard navigation.",
"category": "layout",
"type": "blockstudio",
"dependencies": ["tab-item"],
"files": ["block.json", "index.php", "style.scss"]
},
{
"name": "tab-item",
"title": "Tab Item",
"description": "Single tab panel used inside Tabs.",
"category": "layout",
"type": "blockstudio",
"files": ["block.json", "index.php"]
}
]
}
Für den Erfolg der Datei gelten einige Regeln:
filesist eine ausdrückliche Liste. Das CLI lädt genau diese Pfade herunter und nichts anderes. Es gibt keine Glob-Muster. Neue Assets werden daher erst mitgeliefert, wenn du sie hier hinzufügst. Pfade dürfen Unterverzeichnisse enthalten, die bei der Installation erstellt werden.baseUrlmuss eine absolute URL sein. Das CLI validiert sie als URL und lehnt relative Werte ab. Blockdateien werden immer vonbaseUrlabgerufen, niemals von einem Pfad relativ zum Speicherort, von demregistry.jsongeladen wurde.dependenciesbenennt Blöcke in derselben Registrierung. Mittabswird zuersttab-iteminstalliert. Fehlende oder zyklische Abhängigkeiten brechen die Installation mit einem Fehler ab.nameist erforderlich, wird aber nicht angezeigt. Befehle und Ausgaben verwenden den Schlüssel, den der Nutzer der Registrierung inblocks.jsonzuweist. Er muss nicht übereinstimmen.typedient nur zur Information. Akzeptiert werdenblockstudio,create-blockoderwordpress. Die Funktionsweise des CLI wird dadurch nicht verändert.
Das CLI überprüft bei jedem Abruf die gesamte Datei und meldet jedes Feld mit einem Fehler.
Ein Tippfehler fällt so auf, bevor Dateien heruntergeladen werden. Die Zeile $schema bietet dir
dieselben Prüfungen im Editor.
Schritt 4: Über Raw-URLs veröffentlichen
Übertrage das Repository per Commit und Push zu GitHub. Danach ist jede Datei in einem öffentlichen Repository hier verfügbar:
https://raw.githubusercontent.com/<owner>/<repo>/<ref>/<path>
<ref> steht für einen Branch, ein Tag oder eine Commit-SHA. Für diese Registrierung sind zwei URLs wichtig:
- Die Registrierungs-URL, die Nutzer konfigurieren:
https://raw.githubusercontent.com/acme/acme-blocks/main/registry.json - Das
baseUrlinregistry.json:https://raw.githubusercontent.com/acme/acme-blocks/main/blocks
Mit dieser baseUrl wird das index.php von hero unter
https://raw.githubusercontent.com/acme/acme-blocks/main/blocks/hero/index.php abgerufen.
Der Raw-Host gibt den Dateiinhalt zurück statt der GitHub-Seite mit HTML-Oberfläche,
die das CLI benötigt. Ein falscher Besitzer, ein falsches Repository oder eine falsche Referenz führt beim ersten Befehl zu einem 404-Fehler:
Registry returned 404 for https://raw.githubusercontent.com/acme/acme-blocks/main/registry.json
Schritt 5: Blöcke in einem Theme installieren
Erstelle im Stammverzeichnis des Themes, in dem die Blöcke verwendet werden, die Datei blocks.json:
npx blockstudio init --yes
Created .../acme-theme/blocks.json
init --yes erstellt ein leeres registries-Objekt. Füge die Registrierung unter dem Namespace hinzu, den du in Befehlen eingeben möchtest:
{
"$schema": "https://blockstudio.dev/schema/blocks.json",
"directory": "blockstudio",
"registries": {
"acme": "https://raw.githubusercontent.com/acme/acme-blocks/main/registry.json"
}
}
Führe init in einem Terminal ohne --yes aus, um dieselben Fragen (Blockverzeichnis, Registrierungsnamen und URLs) interaktiv zu beantworten.
Prüfe, ob die Registrierung aufgelöst wird:
npx blockstudio list
acme (4 blocks)
Name Title Category Type
hero Hero layout blockstudio
card Card components blockstudio
tabs Tabs layout blockstudio
tab-item Tab Item layout blockstudio
search sucht in Namen, Titeln und Beschreibungen nach einer Teilzeichenfolge, wobei Groß- und Kleinschreibung ignoriert werden:
npx blockstudio search tab
Results for "tab"
acme/tabs - Tabs
Tabbed content with keyboard navigation.
acme/tab-item - Tab Item
Single tab panel used inside Tabs.
Mit --dry-run kannst du eine Installation vorab ansehen. Die Abhängigkeit wird zuerst aufgeführt, da sie zuerst installiert wird:
npx blockstudio add acme/tabs --dry-run
Would install:
tab-item (2 files)
tabs (3 files)
Installiere die Blöcke anschließend:
npx blockstudio add acme/tabs
Downloading acme/tabs...
Installed tab-item (2 files)
Installed tabs (3 files)
Beide Ordner liegen jetzt im Verzeichnis blockstudio des Themes und entsprechen exakt ihrer Struktur im Repository:
blockstudio/tab-item/block.json
blockstudio/tab-item/index.php
blockstudio/tabs/block.json
blockstudio/tabs/index.php
blockstudio/tabs/style.scss
Wenn nur eine konfigurierte Registrierung den Block enthält, kannst du den Namespace weglassen. Außerdem kannst du mehrere Blöcke auf einmal übergeben:
npx blockstudio add hero card
Downloading acme/hero...
Installed hero (2 files)
Downloading acme/card...
Installed card (3 files)
Blockstudio erkennt die neuen Ordner wie jeden anderen Block im Theme.
Installierte Blöcke aktualisieren
Die installierten Dateien sind Kopien. Es wird nicht erfasst, welche Version du installiert hast, und CLI aktualisiert Blöcke nie selbstständig. Um eine neuere Version abzurufen, füge den Block erneut hinzu. Ohne Terminal oder in CI bricht der Befehl ab, wenn ein Ordner bereits existiert:
npx blockstudio add tab-item
Block "tab-item" already exists at .../acme-theme/blockstudio/tab-item. Use --yes to overwrite.
Im Terminal fragt CLI stattdessen vor dem Überschreiben nach. --dry-run zeigt die Ordner an, die ersetzt würden, und --yes ersetzt sie:
npx blockstudio add acme/tab-item --dry-run
Would overwrite tab-item
Would install:
tab-item (2 files)
Beim Überschreiben werden die aufgeführten Dateien durch die Version aus der Registry ersetzt. Sichere daher zuerst lokale Änderungen per Commit und prüfe das Ergebnis mit git diff.
Zum Deinstallieren entfernst du den Ordner anhand seines Namens:
npx blockstudio remove tabs --yes
Removed tabs
remove erwartet den Ordnernamen, nicht namespace/block. Abhängigkeiten werden nicht entfernt, daher bleibt tab-item installiert, nachdem du tabs entfernt hast.
Versionierung mit git-Refs
CLI hat weder ein Versionsfeld noch eine Versionsoption. Was abgerufen wird, hängt vollständig von den URLs ab. Bei GitHub ist der Ref in URL die Version. Wer auf main verweist, erhält bei der Installation den Inhalt, den main zu diesem Zeitpunkt enthält.
Damit ein Release unveränderlich bleibt, muss registry.json beim Tag ebenfalls vom Tag herunterladen. Setze baseUrl vor dem Taggen auf den Tag:
"baseUrl": "https://raw.githubusercontent.com/acme/acme-blocks/v1.0.0/blocks"
Dann committen, taggen und pushen:
git commit -am 'Release v1.0.0'
git tag v1.0.0
git push origin main v1.0.0
Danach setzt du baseUrl zurück auf main und committest, damit der Branch weiterhin aktuelle Dateien bereitstellt. Wenn du den ersten Schritt überspringst, erhält jemand, der den Tag fest eingestellt hat, zwar die getaggte Blockliste, lädt die Dateien aber von main herunter.
Um eine Version festzulegen, verwenden Nutzer den Tag in ihrer Registry URL:
{
"$schema": "https://blockstudio.dev/schema/blocks.json",
"directory": "blockstudio",
"registries": {
"acme": "https://raw.githubusercontent.com/acme/acme-blocks/v1.0.0/registry.json"
}
}
In diesem Beispiel wurde v1.0.0 getaggt, bevor tabs und tab-item existierten. Die festgelegte Registry bietet daher nur die beiden ursprünglichen Blöcke an:
npx blockstudio list
acme (2 blocks)
Name Title Category Type
hero Hero layout blockstudio
card Card components blockstudio
npx blockstudio add acme/tabs
Block "tabs" not found in registry "acme".
Auch eine Commit-SHA funktioniert in der Registry URL, aber ein Commit kann seine eigene SHA nicht in baseUrl enthalten. Eine Festlegung per SHA fixiert daher die Blockliste, während die Dateien weiterhin von dem Ref stammen, den das baseUrl dieses Commits benennt. Verwende für Releases daher besser Tags.
Das solltest du beachten
- Jede Registry wird zuerst abgerufen.
addlädt alle Registries inblocks.json, bevor irgendetwas aufgelöst wird. Ist eine Registry nicht erreichbar, schlägt der Befehl selbst füracme/herofehl. Entferne nicht mehr verwendete Registries. - Mehrdeutige Namen benötigen einen Namespace. Wenn zwei Registries beide
heroenthalten, fragt das Terminal, welche verwendet werden soll.--yesnimmt die erste in der Reihenfolgeblocks.json, und ein nicht interaktiver Lauf wird mitBlock "hero" found in multiple registries: acme, starter. Specify one: blockstudio add acme/herobeendet. - Für private Repositories sind Header erforderlich. Verwende für einen Registry-Eintrag die Objektform mit
urlundheaders. Header-Werte unterstützen${VAR}-Platzhalter, die aus der Umgebung gelesen werden. CLI sendet die Header mit dem Abruf der Registry und jedem Dateidownload. Informationen zur Einrichtung des Tokens findest du beim GitHub-Hosting.
Nächste Schritte
- Registry-Übersicht: Was die Registry ist und wie CLI funktioniert
- registry.json: alle Felder des Manifests
- blocks.json: Consumer-Konfiguration, Authentifizierung und Erkennung der Konfiguration
- Hinzufügen: Namespace-Auflösung, Abhängigkeiten und Verhalten beim Überschreiben
- GitHub-Hosting: GitHub Pages und private Repositories
- Benutzerdefinierter Server: Eine Registry auf deiner eigenen Infrastruktur bereitstellen