Публикация реестра блоков в 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. В блоке главного баннера есть одно поле:
{
"$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"
}
]
}
}
<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:
{
"$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. Добавьте реестр под пространством имен, которое хотите указывать в командах:
{
"$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 значение тега:
"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:
{
"$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 и закрытые репозитории
- Собственный сервер: размещение реестра на собственной инфраструктуре