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}"
}
}
}
}
Базовая аутентификация
{
"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"
}
}