blocks.json
blocks.json staat in de hoofdmap van je thema of plug-in. Hierin staat waar de CLI blokken moet installeren en welke registers deze moet doorzoeken.
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"
}
}
Velden
$schema
Optioneel. Verwijst naar het JSON-schema voor automatisch aanvullen en validatie in de editor.
directory
Vereist. Relatief pad vanaf blocks.json waar blokken worden geïnstalleerd.
Elke blok krijgt een eigen submap in deze map. Als directory blockstudio is en je hero toevoegt, komen de bestanden in blockstudio/hero/ terecht.
registries
Vereist. Een object dat namen van naamruimten aan registerverwijzingen koppelt.
De sleutel is de naamruimte die in opdrachten van CLI wordt gebruikt (npx blockstudio add ui/hero).
De waarde is een tekenreeks in URL-formaat of een object met url en optioneel headers.
Tekenreeksformaat (openbare registers):
{
"registries": {
"ui": "https://example.com/registry.json"
}
}
Objectformaat (registers met verificatie):
{
"registries": {
"private": {
"url": "https://private.example.com/registry.json",
"headers": {
"Authorization": "Bearer ${REGISTRY_TOKEN}"
}
}
}
}
Beide formaten kunnen in dezelfde configuratie worden gecombineerd. Je kunt zoveel registers configureren als je wilt. Als je een blok zonder naamruimte toevoegt, doorzoekt de CLI ze allemaal.
Verificatie
Registers waarvoor verificatie vereist is, gebruiken het objectformaat met headers.
De CLI stuurt deze headers bij elk verzoek naar dat register mee, zowel bij het ophalen van registry.json als bij het downloaden van afzonderlijke bestanden.
Bearer-token
{
"registries": {
"private": {
"url": "https://api.example.com/registry.json",
"headers": {
"Authorization": "Bearer ${REGISTRY_TOKEN}"
}
}
}
}
Basisverificatie
{
"registries": {
"private": {
"url": "https://api.example.com/registry.json",
"headers": {
"Authorization": "Basic ${REGISTRY_CREDENTIALS}"
}
}
}
}
Aangepaste headers
Je kunt elke header toevoegen. Dit werkt voor API-sleutels, organisatie-ID’s en alles wat je registerserver verwacht:
{
"registries": {
"internal": {
"url": "https://blocks.internal.company.com/registry.json",
"headers": {
"X-API-Key": "${BLOCKS_API_KEY}",
"X-Org-ID": "acme"
}
}
}
}
Omgevingsvariabelen
Headerwaarden ondersteunen de syntaxis ${VAR_NAME} voor het uitlezen van omgevingsvariabelen.
Zo blijven tokens buiten versiebeheer.
De CLI leest omgevingsvariabelen tijdens runtime uit. Als een gebruikte variabele niet is ingesteld, wordt de CLI afgesloten met een foutmelding waarin de ontbrekende variabele en de header worden genoemd waarin deze werd gebruikt.
Stel de variabele in je shell- of CI-omgeving in. De CLI leest alleen de procesomgeving en laadt zelf geen .env-bestanden:
export REGISTRY_TOKEN=ghp_abc123
npx blockstudio add private/hero
Statische headerv waarden (zonder ${...}) worden ongewijzigd doorgegeven.
Configuratie zoeken
De CLI zoekt vanuit de huidige werkmap omhoog naar blocks.json.
Je kunt opdrachten dus vanuit elke submap van je project uitvoeren.
my-theme/
blocks.json <- found here
blockstudio/
hero/
templates/
page.php <- running `npx blockstudio add` here still works
Als blocks.json niet wordt gevonden, vraagt de CLI je om npx blockstudio init uit te voeren.
Voorbeeld: thema met twee registers
{
"$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"
}
}
Voorbeeld: plug-in met aangepaste map
{
"$schema": "https://blockstudio.dev/schema/blocks.json",
"directory": "src/blocks",
"registries": {
"starter": "https://raw.githubusercontent.com/acme/blocks/main/registry.json"
}
}