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

Публикация реестра блоков в GitHub

Создав несколько хороших блоков, вы захотите использовать их и в следующем проекте. Копировать папки между темами вручную можно, пока их копии не начинают расходиться и никто уже не помнит, в какой теме находится исправленная версия. Упаковывать каждый блок в отдельный пакет со своей сборкой — слишком много лишних действий для папки, в которой лежат block.json и шаблон.

Между ними находится реестр блоков. Это файл registry.json и набор папок блоков, доступные по обычному HTTP. Пользователи запускают команду CLI, исходный код блока копируется в их тему, и с этого момента они владеют этой копией. Для размещения реестра достаточно репозитория GitHub, поскольку GitHub предоставляет каждый файл из публичного репозитория по прямому адресу URL.

В этом руководстве мы создадим реестр acme с четырьмя блоками, опубликуем его из репозитория acme/acme-blocks, установим блоки в тему и зафиксируем выпуск с помощью тега git.

Пакет blockstudio в npm имеет версию 0.0.1. Этот выпуск — заглушка: его единственная команда, add, выводит Adding block: <name> и завершается, ничего не загружая. Команды и вывод в этом руководстве относятся к CLI реестра из репозитория Blockstudio (packages/registry). Именно этот CLI описывает документация реестра.

Как связаны компоненты

Нужно знать два файла:

  • registry.json публикует автор блоков. В нем перечислены блоки, файлы каждого блока и baseUrl для их загрузки.
  • blocks.json находится в теме или плагине пользователя. В нем указаны реестры, которые следует использовать, и каталог для установки блоков.

При установке блока CLI загружает каждый реестр из blocks.json, находит блок, разрешает его зависимости, загружает каждый указанный файл из {baseUrl}/{block}/{file} и записывает его в {directory}/{block}/{file}. Преобразований не выполняется, поэтому файлы на диске полностью совпадают с файлами в репозитории.

Шаг 1. Организуйте репозиторий

Создайте репозиторий с файлом registry.json в корневом каталоге и отдельной папкой для каждого блока в blocks/:

Код
acme-blocks/
  registry.json
  blocks/
    hero/
      block.json
      index.php
    card/
      block.json
      index.php
      style.scss
    tabs/
      block.json
      index.php
      style.scss
    tab-item/
      block.json
      index.php

Имя папки — это имя блока в реестре, которое станет именем папки в теме пользователя. Оно должно совпадать со второй частью имени блока в block.json (acme/hero находится в hero/), чтобы установленную папку было легко найти.

Шаг 2. Создайте блоки

Каждая папка содержит обычный блок Blockstudio. В блоке главного баннера есть одно поле:

JSON
{
  "$schema": "https://blockstudio.dev/schema/block",
  "apiVersion": 3,
  "name": "acme/hero",
  "title": "Hero",
  "category": "design",
  "blockstudio": {
    "attributes": [
      {
        "id": "heading",
        "type": "text",
        "label": "Heading",
        "default": "Build faster"
      }
    ]
  }
}
PHP
<section useBlockProps class="acme-hero">
  <h1><?php echo esc_html( $a['heading'] ); ?></h1>
</section>

card устроен так же, но содержит style.scss. tabs отображает <InnerBlocks allowedBlocks='["acme/tab-item"]' />, а tab-item объявляет "parent": ["acme/tabs"], поэтому tabs бесполезен без tab-item. На следующем шаге эта связь задается в реестре.

Особых требований реестра к этим блокам нет. CLI копирует папки, поэтому блок, созданный с помощью @wordpress/create-block или зарегистрированный через обычный PHP, можно публиковать тем же способом.

Шаг 3. Создайте registry.json

В registry.json перечислены все блоки и все файлы, которые должен скачать CLI:

JSON
{
  "$schema": "https://blockstudio.dev/schema/registry.json",
  "name": "acme",
  "description": "Acme block library.",
  "baseUrl": "https://raw.githubusercontent.com/acme/acme-blocks/main/blocks",
  "blocks": [
    {
      "name": "hero",
      "title": "Hero",
      "description": "Full-width hero section with a heading.",
      "category": "layout",
      "type": "blockstudio",
      "files": ["block.json", "index.php"]
    },
    {
      "name": "card",
      "title": "Card",
      "description": "Content card with a title.",
      "category": "components",
      "type": "blockstudio",
      "files": ["block.json", "index.php", "style.scss"]
    },
    {
      "name": "tabs",
      "title": "Tabs",
      "description": "Tabbed content with keyboard navigation.",
      "category": "layout",
      "type": "blockstudio",
      "dependencies": ["tab-item"],
      "files": ["block.json", "index.php", "style.scss"]
    },
    {
      "name": "tab-item",
      "title": "Tab Item",
      "description": "Single tab panel used inside Tabs.",
      "category": "layout",
      "type": "blockstudio",
      "files": ["block.json", "index.php"]
    }
  ]
}

Работу этого файла определяют несколько правил:

  • files — это явный список. CLI скачивает именно эти пути и ничего больше. Подстановки по маскам нет, поэтому новый ресурс попадет в поставку, только если добавить его сюда. Пути могут содержать подкаталоги, которые создаются при установке.
  • baseUrl должен быть абсолютным URL. CLI проверяет его как URL и отклоняет относительные значения. Файлы блоков всегда загружаются из baseUrl, а не из места, относительного к тому, откуда был загружен registry.json.
  • dependencies указывают блоки из того же реестра. При добавлении tabs сначала устанавливается tab-item. Отсутствующие и циклические зависимости приводят к остановке установки с ошибкой.
  • name обязателен, но не отображается. В командах и выводе используется ключ, который потребитель задает реестру в blocks.json; он не обязан совпадать с ним.
  • type носит справочный характер. Он принимает blockstudio, create-block или wordpress и не меняет поведение CLI.

CLI проверяет весь файл при каждой загрузке и сообщает о каждом поле с ошибкой, поэтому опечатка обнаруживается до скачивания файлов. Строка $schema выполняет те же проверки в редакторе.

Шаг 4: Публикация через raw URL

Зафиксируйте изменения в репозитории и отправьте его в GitHub. После этого каждый файл в публичном репозитории будет доступен по адресу:

Код
https://raw.githubusercontent.com/<owner>/<repo>/<ref>/<path>

<ref> — это ветка, тег или SHA коммита. Для этого реестра важны два URL:

  • URL реестра URL, который настраивают потребители: https://raw.githubusercontent.com/acme/acme-blocks/main/registry.json
  • URL baseUrl в registry.json: https://raw.githubusercontent.com/acme/acme-blocks/main/blocks

С этим baseUrl значение index.php для hero извлекается из https://raw.githubusercontent.com/acme/acme-blocks/main/blocks/hero/index.php. Исходный хост возвращает содержимое файла вместо страницы GitHub HTML, которая нужна CLI. Неверный владелец, репозиторий или ref приведет к 404 при первой команде:

Код
Registry returned 404 for https://raw.githubusercontent.com/acme/acme-blocks/main/registry.json

Шаг 5: Установка блоков в тему

В корне темы, в которую устанавливаются блоки, создайте blocks.json:

Командная оболочка
npx blockstudio init --yes
Код
Created .../acme-theme/blocks.json

init --yes создает пустой объект registries. Добавьте реестр под пространством имен, которое хотите указывать в командах:

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

Запустите init без --yes в терминале, чтобы вместо этого интерактивно ответить на те же вопросы (каталог блоков, имена и URL реестров).

Проверьте, что реестр доступен:

Командная оболочка
npx blockstudio list
Код
acme (4 blocks)

  Name      Title     Category      Type
  hero      Hero      layout        blockstudio
  card      Card      components    blockstudio
  tabs      Tabs      layout        blockstudio
  tab-item  Tab Item  layout        blockstudio

search ищет подстроку без учета регистра среди имен, заголовков и описаний:

Командная оболочка
npx blockstudio search tab
Код
Results for "tab"

  acme/tabs - Tabs
    Tabbed content with keyboard navigation.
  acme/tab-item - Tab Item
    Single tab panel used inside Tabs.

Предварительно просмотрите установку с помощью --dry-run. Зависимость указана первой, поскольку она устанавливается первой:

Командная оболочка
npx blockstudio add acme/tabs --dry-run
Код
Would install:
  tab-item (2 files)
  tabs (3 files)

Теперь выполните установку:

Командная оболочка
npx blockstudio add acme/tabs
Код
Downloading acme/tabs...
Installed tab-item (2 files)
Installed tabs (3 files)

Теперь обе папки находятся в каталоге blockstudio темы, в точности как в репозитории:

Код
blockstudio/tab-item/block.json
blockstudio/tab-item/index.php
blockstudio/tabs/block.json
blockstudio/tabs/index.php
blockstudio/tabs/style.scss

Если только в одном настроенном реестре есть нужный блок, пространство имен можно не указывать. За один раз можно передать несколько блоков:

Командная оболочка
npx blockstudio add hero card
Код
Downloading acme/hero...
Installed hero (2 files)
Downloading acme/card...
Installed card (3 files)

Blockstudio обнаруживает новые папки так же, как любые другие блоки темы.

Обновление установленных блоков

Установленные файлы — это копия. Система не отслеживает установленную версию, а CLI никогда не обновляет блоки автоматически. Чтобы получить новую версию, добавьте блок еще раз. Если терминал недоступен или команда запускается в CI, существующая папка останавливает ее выполнение:

Командная оболочка
npx blockstudio add tab-item
Код
Block "tab-item" already exists at .../acme-theme/blockstudio/tab-item. Use --yes to overwrite.

В терминале CLI вместо этого запросит подтверждение перед перезаписью. --dry-run перечисляет папки, которые будут заменены, а --yes выполняет замену:

Командная оболочка
npx blockstudio add acme/tab-item --dry-run
Код
Would overwrite tab-item
Would install:
  tab-item (2 files)

При перезаписи перечисленные файлы заменяются версией из реестра. Поэтому сначала зафиксируйте локальные изменения, а результат проверьте с помощью git diff.

Чтобы удалить блок, удалите папку с его именем:

Командная оболочка
npx blockstudio remove tabs --yes
Код
Removed tabs

remove принимает имя папки, а не namespace/block. Зависимости не удаляются, поэтому tab-item останется установленным после удаления tabs.

Управление версиями с помощью refs git

У CLI нет поля или флага версии. Загружаемое содержимое полностью определяется URL, а для GitHub версию задает ref в URL. Потребитель, указавший main, получит содержимое main на момент установки.

Чтобы опубликовать фиксированный релиз, registry.json в теге также должен загружать файлы из этого тега. Перед созданием тега задайте baseUrl значение тега:

JSON
"baseUrl": "https://raw.githubusercontent.com/acme/acme-blocks/v1.0.0/blocks"

Затем зафиксируйте изменения, создайте тег и отправьте их:

Командная оболочка
git commit -am 'Release v1.0.0'
git tag v1.0.0
git push origin main v1.0.0

После этого верните baseUrl значение main и зафиксируйте изменение, чтобы ветка продолжала отдавать актуальные файлы. Если пропустить первый шаг, потребитель, закрепленный за тегом, получит список блоков из тега, но скачает файлы из main.

Потребители закрепляют версию, указывая тег в URL реестра URL:

JSON
{
  "$schema": "https://blockstudio.dev/schema/blocks.json",
  "directory": "blockstudio",
  "registries": {
    "acme": "https://raw.githubusercontent.com/acme/acme-blocks/v1.0.0/registry.json"
  }
}

В этом примере тег v1.0.0 создан до появления tabs и tab-item, поэтому в закрепленном реестре доступны только два исходных блока:

Командная оболочка
npx blockstudio list
Код
acme (2 blocks)

  Name  Title  Category      Type
  hero  Hero   layout        blockstudio
  card  Card   components    blockstudio
Командная оболочка
npx blockstudio add acme/tabs
Код
Block "tabs" not found in registry "acme".

В URL реестра URL можно также указать SHA коммита, но коммит не может содержать собственный SHA в baseUrl. Поэтому закрепление по SHA фиксирует список блоков, а файлы по-прежнему загружаются из ref, указанного в baseUrl этого коммита. Для релизов предпочтительнее использовать теги.

Что следует учитывать

  • Сначала загружаются все реестры. add загружает все реестры из blocks.json до начала разрешения имён, поэтому недоступность одного реестра приводит к ошибке команды даже для acme/hero. Удаляйте реестры, которыми больше не пользуетесь.
  • Для неоднозначных имён нужно пространство имён. Если два реестра содержат hero, интерактивный терминал спрашивает, какой использовать; --yes выбирает первый в порядке blocks.json, а неинтерактивный запуск завершается с сообщением Block "hero" found in multiple registries: acme, starter. Specify one: blockstudio add acme/hero.
  • Для приватных репозиториев нужны заголовки. Используйте объектную форму записи реестра с url и headers. Значения заголовков поддерживают подстановки ${VAR}, читаемые из окружения; CLI отправляет эти заголовки и при загрузке реестра, и при скачивании каждого файла. Настройка токена описана в разделе Хостинг на GitHub.

Следующие шаги

  • Обзор реестра: что такое реестр и как работает CLI
  • registry.json: все поля манифеста
  • blocks.json: конфигурация потребителя, аутентификация и обнаружение конфигурации
  • добавление: разрешение пространств имен, зависимости и поведение при перезаписи
  • GitHub хостинг: GitHub Pages и закрытые репозитории
  • Собственный сервер: размещение реестра на собственной инфраструктуре