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