registry.json
registry.json is een JSON-bestand dat op een URL wordt gehost. Het vermeldt alle beschikbare blokken in een register, met hun metagegevens, afhankelijkheden en bestandsmanifesten.
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"
]
}
]
}
Velden op hoofdniveau
name
Vereist. De register-ID. De CLI valideert deze, maar toont hem niet: opdrachten en uitvoer gebruiken de sleutel die de gebruiker voor het register heeft gekozen in blocks.json.
description
Optioneel. Een korte beschrijving van de inhoud van dit register.
baseUrl
Vereist. De basis-URL voor het downloaden van blokbestanden. Dit moet een geldige URL zijn.
Bestanden worden opgehaald door de basis-URL, de bloknaam en het bestandspad te combineren: {baseUrl}/{block.name}/{file}.
Als baseUrl bijvoorbeeld is ingesteld op
https://raw.githubusercontent.com/acme/blocks/main/blocks en een blok de naam tabs heeft met bestand index.php, haalt de CLI het volgende op:
https://raw.githubusercontent.com/acme/blocks/main/blocks/tabs/index.php
Blokvelden
name
Vereist. De mapnaam van het blok. Dit is de identificatie die in CLI-opdrachten wordt gebruikt en de mapnaam op schijf wordt.
title
Optioneel. Een leesbare naam die wordt getoond in de uitvoer van list en search.
description
Optioneel. Een beschrijving van één regel die in de resultaten van search wordt getoond.
category
Optioneel. Een categorielabel voor de uitvoer van list.
type
Optioneel. Een van blockstudio, create-block of wordpress.
Dit is alleen ter informatie. Het gedrag van de CLI verandert niet op basis van het bloktype. Deze downloadt en kopieert altijd de bestanden die in files staan.
dependencies
Optioneel. Een lijst met andere bloknamen in hetzelfde register die samen met dit blok moeten worden geïnstalleerd.
Wanneer een gebruiker een blok met afhankelijkheden toevoegt, zoekt de CLI de volledige afhankelijkheidsboom op en installeert alles in de juiste volgorde. Circulaire afhankelijkheden worden gedetecteerd en afgewezen.
Afhankelijkheden moeten in hetzelfde register staan. Afhankelijkheden tussen registers worden niet ondersteund.
files
Vereist. Een lijst met bestandspaden relatief ten opzichte van de blokmap. Er is minstens één bestand vereist.
Dit zijn de exacte bestanden die de CLI downloadt en naar schijf schrijft. De paden kunnen submappen bevatten:
{
"files": [
"block.json",
"index.php",
"style.scss",
"src/components/tabs.tsx",
"src/styles/tabs.css"
]
}
Bestanden opzoeken
Voor elk bestand in het manifest van een blok maakt de CLI een download-URL aan:
{baseUrl}/{block.name}/{file}
En schrijft deze naar:
{directory}/{block.name}/{file}
De mapstructuur in de blokmap blijft behouden. Als een bestandspad submappen bevat, worden deze automatisch aangemaakt.
Bestanden worden altijd opgehaald van de baseUrl binnen registry.json, niet vanaf een locatie relatief ten opzichte van het register-URL in blocks.json.
Validatie
De CLI valideert registry.json bij elke keer ophalen aan de hand van een Zod-schema.
Ongeldige registers geven duidelijke foutmeldingen met de velden die niet aan de validatie voldoen.
Ontbrekende verplichte velden, lege blocks– of files-lijsten, ongeldige URL’s en onbekende waarden voor type worden allemaal opgespoord voordat bestanden worden gedownload.