Ga naar de inhoud

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

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

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

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

Objectformaat (registers met verificatie):

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

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

Basisverificatie

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

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

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

Code
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

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

Voorbeeld: plug-in met aangepaste map

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