Přejít k obsahu

blocks.json

blocks.json se nachází v kořenovém adresáři šablony nebo pluginu. Určuje CLI, kam instalovat bloky a ve kterých registrech hledat.

Schéma

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

Pole

$schema

Nepovinné. Odkazuje na schéma JSON pro automatické doplňování a ověřování v editoru.

directory

Povinné. Relativní cesta od blocks.json, kam se bloky instalují.

Každý blok má v tomto adresáři vlastní podsložku. Pokud je directory nastaven na blockstudio a přidáte hero, soubory se uloží do blockstudio/hero/.

registries

Povinné. Objekt mapující názvy jmenných prostorů na odkazy na registry.

Klíč je jmenný prostor používaný v příkazech CLI (npx blockstudio add ui/hero). Hodnotou je buď řetězec URL, nebo objekt s url a nepovinným headers.

Formát řetězce (veřejné registry):

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

Formát objektu (registry s ověřováním):

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

V jedné konfiguraci lze kombinovat oba formáty a nastavit libovolný počet registrů. Při přidání bloku bez jmenného prostoru je CLI prohledá všechny.

Ověřování

Registry vyžadující ověření používají formát objektu s headers. CLI při každém požadavku do daného registru odesílá tyto hlavičky, a to při načítání registry.json i při stahování jednotlivých souborů.

Nosný token

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

Základní ověření

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

Vlastní hlavičky

Lze přidat libovolnou hlavičku. Hodí se to pro klíče API, identifikátory organizace nebo jiné údaje, které server registru vyžaduje:

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

Proměnné prostředí

Hodnoty hlaviček podporují syntaxi ${VAR_NAME} pro načtení proměnných prostředí. Díky tomu zůstanou tokeny mimo správu verzí.

CLI načítá proměnné prostředí za běhu. Pokud odkazovaná proměnná není nastavena, CLI skončí chybou, která uvede název chybějící proměnné a hlavičku, ve které byla použita.

Nastavte proměnnou ve svém shellu nebo prostředí CI. CLI čte pouze prostředí procesu; soubory .env samo nenačítá:

Shell
export REGISTRY_TOKEN=ghp_abc123
npx blockstudio add private/hero

Statické hodnoty hlaviček (bez ${...}) se předávají beze změny.

Vyhledání konfigurace

CLI postupuje od aktuálního pracovního adresáře směrem nahoru a hledá blocks.json. Příkazy tak můžete spouštět z libovolné podsložky projektu.

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

Pokud se soubor blocks.json nenajde, CLI vám doporučí spustit npx blockstudio init.

Příklad: šablona se dvěma registry

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

Příklad: plugin s vlastním adresářem

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