Hoppa till innehåll

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

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"
  }
}

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):

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

Objektformat (autentiserade register):

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

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

Grundläggande autentisering

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

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

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

Kod
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

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"
  }
}

Exempel: tillägg med anpassad katalog

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