Przejdź do treści

Publikowanie rejestru bloków w GitHub

Gdy masz już kilka dobrych bloków, chcesz użyć ich również w następnym projekcie. Ręczne kopiowanie folderów między motywami sprawdza się do czasu, gdy kopie się rozchodzą i nikt nie pamięta, w którym motywie znajduje się poprawiona wersja. Opakowanie każdego bloku w pakiet z własnym procesem budowania to sporo zachodu jak na folder zawierający block.json i szablon.

Rejestr bloków stanowi rozwiązanie pośrednie. To plik registry.json i zestaw folderów bloków udostępnianych przez zwykłe HTTP. Użytkownicy uruchamiają polecenie CLI, źródła bloków są kopiowane do ich motywu i od tej pory to oni zarządzają kopiami. Do hostowania rejestru wystarczy repozytorium GitHub, ponieważ GitHub udostępnia każdy plik z publicznego repozytorium pod surowym adresem URL.

W tym przewodniku utworzymy rejestr o nazwie acme zawierający cztery bloki, opublikujemy go z repozytorium acme/acme-blocks, zainstalujemy z niego bloki w motywie i przypniemy wydanie za pomocą tagu git.

Pakiet blockstudio w npm jest w wersji 0.0.1. To wydanie zastępcze: jedyne polecenie, add, wyświetla Adding block: <name> i kończy działanie bez pobierania czegokolwiek. Polecenia i wyniki w tym przewodniku pochodzą z rejestru CLI w repozytorium Blockstudio (packages/registry), które jest CLI opisywanym w Dokumentacji rejestru.

Jak współdziałają poszczególne elementy

Warto znać dwa pliki:

  • registry.json jest publikowany przez autora bloku. Zawiera listę bloków, plików, z których składa się każdy z nich, oraz baseUrl, z którego można je pobrać.
  • blocks.json znajduje się w motywie lub wtyczce użytkownika. Określa, których rejestrów używać i do którego katalogu instalować bloki.

Podczas instalowania bloku CLI pobiera każdy rejestr wymieniony w blocks.json, wyszukuje blok, rozwiązuje jego zależności, pobiera każdy wymieniony plik z {baseUrl}/{block}/{file} i zapisuje go w {directory}/{block}/{file}. Niczego nie przekształca, dlatego pliki na dysku są dokładnie takie same jak w repozytorium.

Krok 1: uporządkuj repozytorium

Utwórz repozytorium z plikiem registry.json w katalogu głównym i osobnym folderem dla każdego bloku w blocks/:

Kod
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

Nazwa folderu jest nazwą bloku w rejestrze i staje się nazwą folderu w motywie użytkownika. Powinna być identyczna jak druga część nazwy bloku w block.json (acme/hero znajduje się w hero/), aby łatwo rozpoznać zainstalowany folder.

Krok 2: napisz bloki

Każdy folder zawiera zwykły blok Blockstudio. Blok sekcji głównej ma jedno pole:

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 ma taką samą strukturę i dodaje style.scss. tabs renderuje <InnerBlocks allowedBlocks='["acme/tab-item"]' />, a tab-item deklaruje "parent": ["acme/tabs"], dlatego tabs nie jest przydatne bez tab-item. W następnym kroku opiszemy tę zależność w rejestrze.

Bloki te nie mają nic specyficznego dla rejestru. CLI kopiuje foldery, więc bloki utworzone za pomocą @wordpress/create-block lub zarejestrowane zwykłym PHP można opublikować w ten sam sposób.

Krok 3: napisz registry.json

registry.json zawiera listę każdego bloku i każdego pliku, który CLI ma pobrać:

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

O tym, czy ten plik zadziała, decyduje kilka zasad:

  • files to jawna lista. CLI pobiera dokładnie te ścieżki i nic więcej. Nie używa wzorców glob, więc nowy zasób zostanie dołączony dopiero po dodaniu go tutaj. Ścieżki mogą zawierać podkatalogi, które są tworzone podczas instalacji.
  • baseUrl musi być bezwzględnym URL. CLI sprawdza, czy jest to URL, i odrzuca wartości względne. Pliki bloków są zawsze pobierane z baseUrl, nigdy ze ścieżki względnej względem miejsca, z którego wczytano registry.json.
  • dependencies wskazuje bloki z tego samego rejestru. Dodanie tabs instaluje najpierw tab-item. Brakujące i cykliczne zależności przerywają instalację z błędem.
  • name jest wymagane, ale nie jest wyświetlane. Polecenia i dane wyjściowe używają klucza, który użytkownik przekazuje rejestrowi w blocks.json; nie musi on być taki sam.
  • type ma charakter informacyjny. Przyjmuje blockstudio, create-block lub wordpress i nie zmienia działania CLI.

CLI sprawdza cały plik przy każdym pobraniu i zgłasza każde pole z błędem, więc literówka zostaje wykryta, zanim zostanie pobrany jakikolwiek plik. Wiersz $schema zapewnia te same kontrole w edytorze.

Krok 4: Publikowanie przez surowe adresy URL

Zatwierdź zmiany w repozytorium i wypchnij je do GitHub. Każdy plik w publicznym repozytorium będzie wtedy dostępny pod adresem:

Kod
https://raw.githubusercontent.com/<owner>/<repo>/<ref>/<path>

<ref> to gałąź, tag lub SHA zatwierdzenia. W tym rejestrze istotne są dwa adresy URL:

  • Rejestr URL, który konfigurują użytkownicy: https://raw.githubusercontent.com/acme/acme-blocks/main/registry.json
  • baseUrl w registry.json: https://raw.githubusercontent.com/acme/acme-blocks/main/blocks

Dzięki temu baseUrl pobierana jest index.php hero z https://raw.githubusercontent.com/acme/acme-blocks/main/blocks/hero/index.php. Surowy host zwraca zawartość pliku zamiast strony GitHub HTML, której potrzebuje CLI. Nieprawidłowy właściciel, repozytorium lub ref ujawnia się jako 404 przy pierwszym poleceniu:

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

Krok 5: Instalowanie bloków w motywie

W katalogu głównym używanego motywu utwórz blocks.json:

Powłoka
npx blockstudio init --yes
Kod
Created .../acme-theme/blocks.json

init --yes zapisuje pusty obiekt registries. Dodaj rejestr pod przestrzenią nazw, której chcesz używać w poleceniach:

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

Uruchom w terminalu init bez --yes, aby zamiast tego odpowiedzieć na te same pytania interaktywnie (katalog bloku, nazwy rejestrów i adresy URL).

Sprawdź, czy rejestr jest rozpoznawany:

Powłoka
npx blockstudio list
Kod
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 wyszukuje fragment tekstu bez uwzględniania wielkości liter w nazwach, tytułach i opisach:

Powłoka
npx blockstudio search tab
Kod
Results for "tab"

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

Wyświetl podgląd instalacji za pomocą --dry-run. Zależność jest wymieniona jako pierwsza, ponieważ to ona jest instalowana najpierw:

Powłoka
npx blockstudio add acme/tabs --dry-run
Kod
Would install:
  tab-item (2 files)
  tabs (3 files)

Teraz zainstaluj na stałe:

Powłoka
npx blockstudio add acme/tabs
Kod
Downloading acme/tabs...
Installed tab-item (2 files)
Installed tabs (3 files)

Oba foldery znajdują się teraz w katalogu blockstudio motywu, dokładnie tak jak w repozytorium:

Kod
blockstudio/tab-item/block.json
blockstudio/tab-item/index.php
blockstudio/tabs/block.json
blockstudio/tabs/index.php
blockstudio/tabs/style.scss

Możesz pominąć przestrzeń nazw, gdy tylko jeden skonfigurowany rejestr zawiera dany blok, i przekazać kilka bloków naraz:

Powłoka
npx blockstudio add hero card
Kod
Downloading acme/hero...
Installed hero (2 files)
Downloading acme/card...
Installed card (3 files)

Blockstudio wykrywa nowe foldery tak samo jak każdy inny blok w motywie.

Aktualizowanie zainstalowanych bloków

Zainstalowane pliki są kopią. Nie jest zapisywana informacja o zainstalowanej wersji, a CLI nigdy samodzielnie nie aktualizuje bloku. Aby pobrać nowszą wersję, dodaj blok ponownie. Bez terminala lub w CI istniejący folder zatrzymuje polecenie:

Powłoka
npx blockstudio add tab-item
Kod
Block "tab-item" already exists at .../acme-theme/blockstudio/tab-item. Use --yes to overwrite.

W terminalu CLI najpierw pyta o zgodę na nadpisanie. --dry-run wyświetla foldery, które zostałyby zastąpione, a --yes je zastępuje:

Powłoka
npx blockstudio add acme/tab-item --dry-run
Kod
Would overwrite tab-item
Would install:
  tab-item (2 files)

Nadpisanie zastępuje wymienione pliki wersją z rejestru, więc najpierw zatwierdź lokalne zmiany, a następnie sprawdź wynik za pomocą git diff.

Aby odinstalować, usuń folder, podając jego nazwę:

Powłoka
npx blockstudio remove tabs --yes
Kod
Removed tabs

remove przyjmuje nazwę folderu, a nie namespace/block. Nie usuwa zależności, więc tab-item pozostaje zainstalowany po usunięciu tabs.

Wersjonowanie za pomocą refów git

CLI nie ma pola wersji ani flagi wersji. O tym, co zostanie pobrane, decydują wyłącznie adresy URL, a w GitHub ref w URL jest wersją. Użytkownik, który wskaże main, otrzyma to, co main zawiera w chwili instalacji.

Aby opublikować niezmienne wydanie, registry.json pod tagiem również musi pobierać pliki z tego tagu. Przed utworzeniem tagu ustaw baseUrl na ten tag:

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

Następnie zatwierdź zmiany, utwórz tag i wypchnij je:

Powłoka
git commit -am 'Release v1.0.0'
git tag v1.0.0
git push origin main v1.0.0

Następnie ustaw baseUrl z powrotem na main i zatwierdź zmiany, aby gałąź nadal udostępniała aktualne pliki. Jeśli pominiesz pierwszy krok, użytkownik przypięty do tagu otrzyma listę bloków z tego tagu, ale pliki pobierze z main.

Użytkownicy przypinają wersję, używając tagu w rejestrze 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"
  }
}

W tym przykładzie v1.0.0 został oznaczony tagiem przed utworzeniem tabs i tab-item, więc przypięty rejestr udostępnia tylko dwa pierwotne bloki:

Powłoka
npx blockstudio list
Kod
acme (2 blocks)

  Name  Title  Category      Type
  hero  Hero   layout        blockstudio
  card  Card   components    blockstudio
Powłoka
npx blockstudio add acme/tabs
Kod
Block "tabs" not found in registry "acme".

SHA zatwierdzenia działa również w rejestrze URL, ale zatwierdzenie nie może zawierać własnego SHA w baseUrl. Przypięcie po SHA ustala więc listę bloków, ale pliki nadal pochodzą z refu wskazanego przez baseUrl tego zatwierdzenia. Dlatego do wydań lepiej używać tagów.

Warto pamiętać

  • Najpierw pobierany jest każdy rejestr. add wczytuje wszystkie rejestry w blocks.json, zanim cokolwiek wyszuka, więc niedostępność jednego z nich powoduje niepowodzenie polecenia, nawet dla acme/hero. Usuń rejestry, których już nie używasz.
  • Niejednoznaczne nazwy wymagają przestrzeni nazw. Jeśli oba rejestry zawierają hero, w terminalu pojawi się pytanie, którego użyć; --yes wybiera pierwszą pozycję w kolejności blocks.json, a nieinteraktywne uruchomienie kończy się kodem Block "hero" found in multiple registries: acme, starter. Specify one: blockstudio add acme/hero.
  • Prywatne repozytoria wymagają nagłówków. Użyj obiektowej postaci wpisu rejestru z url i headers. Wartości nagłówków obsługują znaczniki ${VAR}, których wartości są pobierane ze środowiska, a CLI wysyła nagłówki przy pobieraniu rejestru i każdego pliku. Informacje o konfiguracji tokenu znajdziesz na stronie hostinguGitHub.

Następne kroki

  • Przegląd rejestru: czym jest rejestr i jak działa CLI
  • registry.json: wszystkie pola manifestu
  • blocks.json: konfiguracja użytkownika, uwierzytelnianie i wykrywanie konfiguracji
  • add: rozpoznawanie przestrzeni nazw, zależności i działanie nadpisywania
  • GitHub hosting: GitHub Pages i prywatne repozytoria
  • Własny serwer: udostępnianie rejestru z własnej infrastruktury