registry.json
registry.json ist eine JSON-Datei, die auf einem URL gehostet wird. Sie listet alle in einer Registry verfügbaren Blöcke, ihre Metadaten und Abhängigkeiten sowie Dateimanifeste auf.
Schema
{
"$schema": "https://blockstudio.dev/schema/registry.json",
"name": "ui",
"description": "Core UI blocks for Blockstudio projects.",
"baseUrl": "https://raw.githubusercontent.com/acme/blocks/main/blocks",
"blocks": [
{
"name": "tabs",
"title": "Tabs",
"description": "Tabbed content with accessible keyboard navigation.",
"category": "layout",
"type": "blockstudio",
"dependencies": ["tab-item"],
"files": [
"block.json",
"index.php",
"style.scss"
]
}
]
}
Felder der obersten Ebene
name
Erforderlich. Die Kennung der Registry. CLI validiert sie, zeigt sie aber nicht an: Befehle und Ausgaben verwenden den Schlüssel, den die nutzende Person in blocks.json für die Registry gewählt hat.
description
Optional. Eine kurze Beschreibung des Inhalts dieser Registry.
baseUrl
Erforderlich. Die Basis-URL zum Herunterladen von Blockdateien. Muss eine gültige URL sein.
Dateien werden durch Kombination der Basis-URL mit dem Blocknamen und dem Dateipfad abgerufen: {baseUrl}/{block.name}/{file}.
Wenn baseUrl auf https://raw.githubusercontent.com/acme/blocks/main/blocks gesetzt ist und ein Block namens tabs die Datei index.php enthält, ruft CLI zum Beispiel Folgendes ab:
https://raw.githubusercontent.com/acme/blocks/main/blocks/tabs/index.php
Blockfelder
name
Erforderlich. Der Ordnername des Blocks. Dieser Bezeichner wird in CLI-Befehlen verwendet und zum Ordnernamen auf der Festplatte.
title
Optional. Menschenlesbarer Name, der in list– und search-Ausgaben angezeigt wird.
description
Optional. Einzeilige Beschreibung, die in search-Ergebnissen angezeigt wird.
category
Optional. Gruppierungsbezeichnung für list-Ausgaben.
type
Optional. Einer der Werte blockstudio, create-block oder wordpress.
Dieser Wert dient nur zur Information. CLI ändert sein Verhalten nicht abhängig vom Blocktyp. Es lädt immer die in files aufgeführten Dateien herunter und kopiert sie.
dependencies
Optional. Ein Array weiterer Blocknamen aus derselben Registry, die zusammen mit diesem Block installiert werden müssen.
Wenn jemand einen Block mit Abhängigkeiten hinzufügt, löst CLI den gesamten Abhängigkeitsbaum auf und installiert alles in der richtigen Reihenfolge. Zirkuläre Abhängigkeiten werden erkannt und abgelehnt.
Abhängigkeiten müssen in derselben Registry vorhanden sein. Abhängigkeiten über mehrere Registrys hinweg werden nicht unterstützt.
files
Erforderlich. Ein Array von Dateipfaden relativ zum Blockordner. Mindestens eine Datei ist erforderlich.
Dies sind die genauen Dateien, die CLI herunterlädt und auf die Festplatte schreibt. Die Pfade können Unterverzeichnisse enthalten:
{
"files": [
"block.json",
"index.php",
"style.scss",
"src/components/tabs.tsx",
"src/styles/tabs.css"
]
}
Dateien auflösen
Für jede Datei im Manifest eines Blocks erstellt CLI eine Download-URL:
{baseUrl}/{block.name}/{file}
Und schreibt sie hierhin:
{directory}/{block.name}/{file}
Die Verzeichnisstruktur innerhalb des Blockordners bleibt erhalten. Enthält ein Dateipfad Unterverzeichnisse, werden diese automatisch erstellt.
Dateien werden immer von baseUrl innerhalb von registry.json abgerufen, nicht von einem Pfad relativ zur Registry-URL in blocks.json.
Validierung
CLI validiert registry.json bei jedem Abruf anhand eines Zod-Schemas. Ungültige Registrys führen zu verständlichen Fehlermeldungen, die genau angeben, welche Felder die Validierung nicht bestanden haben.
Fehlende Pflichtfelder, leere blocks– oder files-Arrays, ungültige URLs und unbekannte Werte für type werden abgefangen, bevor Dateien heruntergeladen werden.