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