blocks.json
blocks.json се намира в основната директория на темата или разширението ви. Файлът указва на CLI къде да инсталира блокове и в кои регистри да търси.
Схема
{
"$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"
}
}
Полета
$schema
По избор. Указва схемата JSON за автоматично довършване и проверка в редактора.
directory
Задължително. Относителен път от blocks.json, където се инсталират блоковете.
Всеки блок получава собствена подпапка в тази директория. Ако directory е blockstudio и добавите hero, файловете ще бъдат записани в blockstudio/hero/.
registries
Задължително. Обект, който съпоставя имената на пространствата от имена с препратки към регистри.
Ключът е пространството от имена, използвано в командите CLI (npx blockstudio add ui/hero).
Стойността е или низ във формат URL, или обект с url и незадължително headers.
Формат с низ (публични регистри):
{
"registries": {
"ui": "https://example.com/registry.json"
}
}
Обектен формат (регистри с удостоверяване):
{
"registries": {
"private": {
"url": "https://private.example.com/registry.json",
"headers": {
"Authorization": "Bearer ${REGISTRY_TOKEN}"
}
}
}
}
Можете да комбинирате двата формата в една конфигурация и да зададете произволен брой регистри. Когато добавя блок без пространство от имена, CLI търси във всички тях.
Удостоверяване
За регистрите, които изискват удостоверяване, използвайте обектния формат с headers.
CLI изпраща тези заглавки при всяка заявка към регистъра, включително при извличането на registry.json и изтеглянето на отделни файлове.
Bearer токен
{
"registries": {
"private": {
"url": "https://api.example.com/registry.json",
"headers": {
"Authorization": "Bearer ${REGISTRY_TOKEN}"
}
}
}
}
Basic удостоверяване
{
"registries": {
"private": {
"url": "https://api.example.com/registry.json",
"headers": {
"Authorization": "Basic ${REGISTRY_CREDENTIALS}"
}
}
}
}
Персонализирани заглавки
Може да се добави всяка заглавка. Това работи за ключове API, идентификатори на организации и всякакви други стойности, които сървърът на регистъра изисква:
{
"registries": {
"internal": {
"url": "https://blocks.internal.company.com/registry.json",
"headers": {
"X-API-Key": "${BLOCKS_API_KEY}",
"X-Org-ID": "acme"
}
}
}
}
Променливи на средата
Стойностите на заглавките поддържат синтаксиса ${VAR_NAME} за четене на променливи на средата. Така токените не попадат в системата за контрол на версиите.
CLI разрешава променливите на средата по време на изпълнение. Ако посочена променлива не е зададена, CLI прекратява командата с грешка, в която са посочени липсващата променлива и заглавката, в която е използвана.
Задайте променливата в обвивката или средата за CI. CLI чете само средата на процеса; самостоятелно не зарежда файлове .env:
export REGISTRY_TOKEN=ghp_abc123
npx blockstudio add private/hero
Статичните стойности на заглавките (без ${...}) се предават без промяна.
Откриване на конфигурацията
CLI се изкачва от текущата работна директория, докато намери blocks.json. Така можете да изпълнявате команди от всяка поддиректория на проекта си.
my-theme/
blocks.json <- found here
blockstudio/
hero/
templates/
page.php <- running `npx blockstudio add` here still works
Ако не бъде намерен blocks.json, CLI ви казва да изпълните npx blockstudio init.
Пример: тема с два регистъра
{
"$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"
}
}
Пример: разширение с персонализирана директория
{
"$schema": "https://blockstudio.dev/schema/blocks.json",
"directory": "src/blocks",
"registries": {
"starter": "https://raw.githubusercontent.com/acme/blocks/main/registry.json"
}
}