Перейти до вмісту

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