blocks.json
blocks.json befindet sich im Stammverzeichnis deines Themes oder Plugins. Hier legst du fest, wo CLI Blöcke installieren und welche Registrys durchsuchen soll.
Schema
{
"$schema": "https://blockstudio.dev/schema/blocks.json",
"directory": "blockstudio",
"registries": {
"ui": "https://blocks.example.com/registry.json",
"starter": "https://raw.githubusercontent.com/acme/blocks/main/registry.json"
}
}
Felder
$schema
Optional. Verweist auf das JSON-Schema für die automatische Vervollständigung und Validierung im Editor.
directory
Erforderlich. Relativer Pfad ab blocks.json, in dem Blöcke installiert werden.
Jeder Block erhält einen eigenen Unterordner in diesem Verzeichnis. Wenn directory auf blockstudio gesetzt ist und du hero hinzufügst, werden die Dateien unter blockstudio/hero/ abgelegt.
registries
Erforderlich. Ein Objekt, das Namensräume ihren Registry-Verweisen zuordnet.
Der Schlüssel ist der in CLI-Befehlen verwendete Namensraum (npx blockstudio add ui/hero). Der Wert ist entweder eine Zeichenfolge im Format URL oder ein Objekt mit url und optionalem headers.
Zeichenfolgenformat (öffentliche Registrys):
{
"registries": {
"ui": "https://example.com/registry.json"
}
}
Objektformat (authentifizierte Registrys):
{
"registries": {
"private": {
"url": "https://private.example.com/registry.json",
"headers": {
"Authorization": "Bearer ${REGISTRY_TOKEN}"
}
}
}
}
Du kannst beide Formate in derselben Konfiguration mischen und beliebig viele Registrys einrichten. Wenn du einen Block ohne Namensraum hinzufügst, durchsucht CLI alle davon.
Authentifizierung
Für Registrys, die eine Authentifizierung erfordern, wird das Objektformat mit headers verwendet. CLI sendet diese Header bei jeder Anfrage an die Registry, sowohl beim Abruf von registry.json als auch beim Herunterladen einzelner Dateien.
Bearer-Token
{
"registries": {
"private": {
"url": "https://api.example.com/registry.json",
"headers": {
"Authorization": "Bearer ${REGISTRY_TOKEN}"
}
}
}
}
Basisauthentifizierung
{
"registries": {
"private": {
"url": "https://api.example.com/registry.json",
"headers": {
"Authorization": "Basic ${REGISTRY_CREDENTIALS}"
}
}
}
}
Benutzerdefinierte Header
Du kannst beliebige Header hinzufügen. Das eignet sich für API-Schlüssel, Organisationskennungen oder andere Werte, die dein Registry-Server erwartet:
{
"registries": {
"internal": {
"url": "https://blocks.internal.company.com/registry.json",
"headers": {
"X-API-Key": "${BLOCKS_API_KEY}",
"X-Org-ID": "acme"
}
}
}
}
Umgebungsvariablen
Headerwerte unterstützen die Syntax ${VAR_NAME} zum Auslesen von Umgebungsvariablen. So bleiben Tokens aus der Versionsverwaltung heraus.
CLI löst Umgebungsvariablen zur Laufzeit auf. Ist eine referenzierte Variable nicht gesetzt, wird CLI mit einer Fehlermeldung abgebrochen, die den Namen der fehlenden Variable und den verwendeten Header nennt.
Setze die Variable in deiner Shell- oder CI-Umgebung. CLI liest nur die Prozessumgebung und lädt selbst keine .env-Dateien:
export REGISTRY_TOKEN=ghp_abc123
npx blockstudio add private/hero
Statische Headerwerte (ohne ${...}) werden unverändert weitergegeben.
Konfiguration finden
CLI geht vom aktuellen Arbeitsverzeichnis aus die Verzeichnisse nach oben durch und sucht nach blocks.json. So kannst du Befehle aus jedem Unterverzeichnis deines Projekts ausführen.
my-theme/
blocks.json <- found here
blockstudio/
hero/
templates/
page.php <- running `npx blockstudio add` here still works
Wird keine blocks.json gefunden, fordert dich CLI auf, npx blockstudio init auszuführen.
Beispiel: Theme mit zwei Registrys
{
"$schema": "https://blockstudio.dev/schema/blocks.json",
"directory": "blockstudio",
"registries": {
"ui": "https://blocks.mycompany.com/ui/registry.json",
"internal": "https://blocks.mycompany.com/internal/registry.json"
}
}
Beispiel: Plugin mit benutzerdefiniertem Verzeichnis
{
"$schema": "https://blockstudio.dev/schema/blocks.json",
"directory": "src/blocks",
"registries": {
"starter": "https://raw.githubusercontent.com/acme/blocks/main/registry.json"
}
}