blocks.json
blocks.json finns i roten av ditt tema eller tillägg. Den talar om för CLI var block ska installeras och vilka register som ska genomsökas.
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"
}
}
Fält
$schema
Valfritt. Anger sökvägen till JSON-schemat för komplettering och validering i redigeraren.
directory
Obligatoriskt. Relativ sökväg från blocks.json där block installeras.
Varje block får en egen undermapp i den här katalogen. Om directory är blockstudio och du lägger till hero hamnar filerna i blockstudio/hero/.
registries
Obligatoriskt. Ett objekt som mappar namn på namnrymder till registerreferenser.
Nyckeln är namnrymden som används i kommandon för CLI (npx blockstudio add ui/hero).
Värdet är antingen en sträng i formatet URL eller ett objekt med url och valfritt headers.
Strängformat (offentliga register):
{
"registries": {
"ui": "https://example.com/registry.json"
}
}
Objektformat (autentiserade register):
{
"registries": {
"private": {
"url": "https://private.example.com/registry.json",
"headers": {
"Authorization": "Bearer ${REGISTRY_TOKEN}"
}
}
}
}
Båda formaten kan blandas i samma konfiguration. Du kan konfigurera hur många register du vill. När du lägger till ett block utan namnrymd söker CLI i dem alla.
Autentisering
Register som kräver autentisering använder objektformatet med headers.
CLI skickar dessa headers i varje begäran till registret, inklusive både hämtningen av registry.json och enskilda filhämtningar.
Bearer-token
{
"registries": {
"private": {
"url": "https://api.example.com/registry.json",
"headers": {
"Authorization": "Bearer ${REGISTRY_TOKEN}"
}
}
}
}
Grundläggande autentisering
{
"registries": {
"private": {
"url": "https://api.example.com/registry.json",
"headers": {
"Authorization": "Basic ${REGISTRY_CREDENTIALS}"
}
}
}
}
Anpassade headers
Du kan lägga till valfri header. Det fungerar för API-nycklar, organisationsidentifierare eller det som registerservern förväntar sig:
{
"registries": {
"internal": {
"url": "https://blocks.internal.company.com/registry.json",
"headers": {
"X-API-Key": "${BLOCKS_API_KEY}",
"X-Org-ID": "acme"
}
}
}
}
Miljövariabler
Header-värden stöder syntaxen ${VAR_NAME} för att läsa miljövariabler.
Det håller token utanför versionshanteringen.
CLI läser miljövariabler vid körning. Om en variabel som refereras inte är inställd avslutas CLI med ett fel som anger den saknade variabeln och headern där den användes.
Ställ in variabeln i ditt skal eller i CI-miljön. CLI läser endast processmiljön; det läser inte in .env-filer på egen hand:
export REGISTRY_TOKEN=ghp_abc123
npx blockstudio add private/hero
Statiska headervärden (utan ${...}) skickas vidare som de är.
Identifiering av konfigurationsfil
CLI går uppåt från den aktuella arbetskatalogen och letar efter blocks.json.
Det innebär att du kan köra kommandon från vilken underkatalog som helst i projektet.
my-theme/
blocks.json <- found here
blockstudio/
hero/
templates/
page.php <- running `npx blockstudio add` here still works
Om blocks.json inte hittas uppmanar CLI dig att köra npx blockstudio init.
Exempel: tema med två register
{
"$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"
}
}
Exempel: tillägg med anpassad katalog
{
"$schema": "https://blockstudio.dev/schema/blocks.json",
"directory": "src/blocks",
"registries": {
"starter": "https://raw.githubusercontent.com/acme/blocks/main/registry.json"
}
}