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
{
"$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):
{
"registries": {
"ui": "https://example.com/registry.json"
}
}
Formát objektu (registre s overovaním):
{
"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
{
"registries": {
"private": {
"url": "https://api.example.com/registry.json",
"headers": {
"Authorization": "Bearer ${REGISTRY_TOKEN}"
}
}
}
}
Základné overovanie
{
"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:
{
"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:
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.
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
{
"$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
{
"$schema": "https://blockstudio.dev/schema/blocks.json",
"directory": "src/blocks",
"registries": {
"starter": "https://raw.githubusercontent.com/acme/blocks/main/registry.json"
}
}