Перейти к содержимому

blocks.json

blocks.json находится в корневом каталоге темы или плагина. В нем указано, куда CLI устанавливает блоки и в каких реестрах выполняет поиск.

Схема

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

Поля

$schema

Необязательно. Ссылка на схему JSON для автодополнения и проверки в редакторе.

directory

Обязательно. Относительный путь от blocks.json, по которому устанавливаются блоки.

Для каждого блока в этом каталоге создается отдельная вложенная папка. Если directory — blockstudio и добавить hero, файлы будут сохранены в blockstudio/hero/.

registries

Обязательно. Объект, сопоставляющий имена пространств имен со ссылками на реестры.

Ключ — это пространство имен, используемое в командах CLI (npx blockstudio add ui/hero). Значение — строка URL или объект с url и необязательным headers.

Строковый формат (общедоступные реестры):

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

Формат объекта (реестры с аутентификацией):

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

В одной конфигурации можно смешивать оба формата и настраивать любое количество реестров. Если добавить блок без пространства имен, CLI будет искать во всех реестрах.

Аутентификация

Для реестров, требующих аутентификации, используется формат объекта с headers. CLI отправляет эти заголовки при каждом запросе к реестру, включая запрос на получение registry.json и загрузку отдельных файлов.

Токен Bearer

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

Базовая аутентификация

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

Пользовательские заголовки

Можно добавить любой заголовок. Это подходит для ключей API, идентификаторов организации и любых других данных, которые ожидает сервер реестра:

JSON
{
  "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.

Пример: тема с двумя реестрами

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

Пример: плагин с пользовательским каталогом

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