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

Публікація реєстру блоків на 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, який налаштовують споживачі: https://raw.githubusercontent.com/acme/acme-blocks/main/registry.json
  • 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. Raw-хост повертає вміст файлу замість сторінки GitHub HTML — саме це потрібно CLI. Неправильний власник, репозиторій або посилання спричинить помилку 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.

Керування версіями за допомогою посилань git

У CLI немає поля версії чи прапорця версії. Що саме буде завантажено, повністю визначають URL-адреси, а на GitHub версією є посилання в 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 реєстру:

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

SHA коміту також працює в URL реєстру, але коміт не може містити власний SHA в baseUrl. Тому закріплення за SHA фіксує список блоків, тоді як файли надходять із посилання, названого в 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 і приватні репозиторії
  • Власний сервер: розміщення реєстру на власній інфраструктурі