Preskočiť na obsah

blocks.json

blocks.json sa nachádza v koreňovom adresári témy alebo pluginu. Určuje, kam má CLI inštalovať bloky a v ktorých registroch má vyhľadávať.

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

Polia

$schema

Voliteľné. Odkazuje na schému JSON na účely automatického dopĺňania a overovania v editore.

directory

Povinné. Relatívna cesta od blocks.json, kam sa inštalujú bloky.

Každý blok má v tomto adresári vlastný podpriečinok. Ak je directory nastavené na blockstudio a pridáte hero, súbory sa uložia do blockstudio/hero/.

registries

Povinné. Objekt mapujúci názvy menných priestorov na odkazy na registre.

Kľúč je menný priestor používaný v príkazoch CLI (npx blockstudio add ui/hero). Hodnota je buď reťazec typu URL, alebo objekt s url a voliteľným headers.

Formát reťazca (verejné registre):

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

Formát objektu (registre s overovaním):

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

Oba formáty možno kombinovať v rovnakej konfigurácii. Môžete nastaviť ľubovoľný počet registrov. Pri pridaní bloku bez menného priestoru ich CLI prehľadá všetky.

Overovanie

Registre vyžadujúce overovanie používajú formát objektu s headers. CLI odosiela tieto hlavičky pri každej požiadavke do daného registra vrátane načítania registry.json aj sťahovania jednotlivých súborov.

Token Bearer

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

Základné overovanie

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

Vlastné hlavičky

Môžete pridať ľubovoľnú hlavičku. Funguje to pre kľúče API, identifikátory organizácií alebo čokoľvek, čo očakáva váš server registra:

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

Premenné prostredia

Hodnoty hlavičiek podporujú syntax ${VAR_NAME} na čítanie premenných prostredia. Vďaka tomu zostanú tokeny mimo systému správy verzií.

CLI vyhodnocuje premenné prostredia za behu. Ak odkazovaná premenná nie je nastavená, CLI skončí s chybou, ktorá uvedie názov chýbajúcej premennej a hlavičku, v ktorej sa použila.

Nastavte premennú v prostredí shellu alebo CI. CLI číta iba premenné prostredia procesu; súbory .env sám nenačítava:

Shell
export REGISTRY_TOKEN=ghp_abc123
npx blockstudio add private/hero

Statické hodnoty hlavičiek (bez ${...}) sa odovzdávajú bez zmeny.

Vyhľadávanie konfigurácie

CLI postupuje nahor od aktuálneho pracovného adresára a hľadá blocks.json. Príkazy tak môžete spúšťať z ľubovoľného podadresára projektu.

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

Ak sa nenájde blocks.json, CLI vás vyzve, aby ste spustili npx blockstudio init.

Príklad: téma s dvoma registrami

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

Príklad: plugin s vlastným adresárom

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