Gå til indhold

blocks.json

blocks.json ligger i roden af dit tema eller plugin. Den fortæller CLI, hvor blokke skal installeres, og hvilke registre der skal søges i.

Skema

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

Felter

$schema

Valgfrit. Henviser til skemaet for JSON til editorens autofuldførelse og validering.

directory

Påkrævet. Relativ sti fra blocks.json, hvor blokke installeres.

Hver blok får sin egen undermappe i denne mappe. Hvis directory er blockstudio, og du tilføjer hero, placeres filerne i blockstudio/hero/.

registries

Påkrævet. Et objekt, der knytter navne på navneområder til registerreferencer.

Nøglen er navneområdet, der bruges i CLI-kommandoer (npx blockstudio add ui/hero). Værdien er enten en streng i formatet URL eller et objekt med url og valgfri headers.

Strengformat (offentlige registre):

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

Objektformat (registre med godkendelse):

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

Begge formater kan blandes i samme konfiguration. Du kan konfigurere så mange registre, du vil. Når du tilføjer en blok uden navneområde, søger CLI i dem alle.

Godkendelse

Registre, der kræver godkendelse, bruger objektformatet med headers. CLI sender disse headere med hver anmodning til det pågældende register, inklusive både hentning af registry.json og download af individuelle filer.

Bearer-token

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

Grundlæggende godkendelse

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

Brugerdefinerede headere

Du kan tilføje enhver header. Det fungerer til API-nøgler, organisationsidentifikatorer eller hvad end din registerserver kræver:

JSON
{
  "registries": {
    "internal": {
      "url": "https://blocks.internal.company.com/registry.json",
      "headers": {
        "X-API-Key": "${BLOCKS_API_KEY}",
        "X-Org-ID": "acme"
      }
    }
  }
}

Miljøvariabler

Headerværdier understøtter syntaksen ${VAR_NAME} til at læse miljøvariabler. Det holder tokens ude af versionsstyring.

CLI fortolker miljøvariabler ved kørsel. Hvis en variabel, der henvises til, ikke er angivet, afsluttes CLI med en fejl, der angiver den manglende variabel og den header, den blev brugt i.

Angiv variablen i din shell- eller CI-omgivelse. CLI læser kun procesmiljøet; den indlæser ikke selv .env-filer:

Shell
export REGISTRY_TOKEN=ghp_abc123
npx blockstudio add private/hero

Statiske headerværdier (uden ${...}) sendes videre, som de er.

Konfigurationssøgning

CLI går op fra den aktuelle arbejdsmappe og leder efter blocks.json. Det betyder, at du kan køre kommandoer fra enhver undermappe i projektet.

Kode
my-theme/
  blocks.json        <- found here
  blockstudio/
    hero/
  templates/
    page.php          <- running `npx blockstudio add` here still works

Hvis der ikke findes nogen blocks.json, fortæller CLI dig, at du skal køre npx blockstudio init.

Eksempel: tema med to registre

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

Eksempel: plugin med brugerdefineret mappe

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