Zum Inhalt springen

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

JSON
{
  "$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):

JSON
{
  "registries": {
    "ui": "https://example.com/registry.json"
  }
}

Objektformat (authentifizierte Registrys):

JSON
{
  "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

JSON
{
  "registries": {
    "private": {
      "url": "https://api.example.com/registry.json",
      "headers": {
        "Authorization": "Bearer ${REGISTRY_TOKEN}"
      }
    }
  }
}

Basisauthentifizierung

JSON
{
  "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:

JSON
{
  "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:

Shell
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.

Code
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

JSON
{
  "$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

JSON
{
  "$schema": "https://blockstudio.dev/schema/blocks.json",
  "directory": "src/blocks",
  "registries": {
    "starter": "https://raw.githubusercontent.com/acme/blocks/main/registry.json"
  }
}