Přejít k obsahu

Publikování registru bloků na GitHub

Jakmile vytvoříte několik kvalitních bloků, budete je chtít použít i v dalším projektu. Ruční kopírování složek mezi šablonami funguje jen do chvíle, než se jejich kopie začnou lišit a nikdo si nepamatuje, ve které šabloně je opravená verze. Zabalit každý blok do balíčku s vlastním sestavením je na složku obsahující block.json a šablonu zbytečně složité.

Řešením je registr bloků. Tvoří ho soubor registry.json a sada složek s bloky, které se poskytují přes běžné HTTP. Uživatel spustí příkaz CLI, zdrojové soubory bloku se zkopírují do jeho šablony a od té chvíle spravuje svou kopii sám. K hostování registru stačí repozitář GitHub, protože GitHub zpřístupňuje každý soubor ve veřejném repozitáři na nezpracované adrese URL.

Tento průvodce vytvoří registr s názvem acme se čtyřmi bloky, zveřejní ho v repozitáři acme/acme-blocks, nainstaluje z něj bloky do šablony a připne vydání pomocí značky git.

Balíček blockstudio na npm má verzi 0.0.1. Toto vydání je zástupné: jeho jediný příkaz, add, vypíše Adding block: <name> a skončí, aniž by cokoli stáhl. Příkazy a výstup v tomto průvodci pocházejí z registru CLI v repozitáři Blockstudio (packages/registry), který představuje CLI popisovaný v dokumentaci registru.

Jak do sebe jednotlivé části zapadají

Je třeba znát dva soubory:

  • registry.json zveřejňuje autor bloku. Obsahuje seznam bloků, soubory tvořící každý blok a baseUrl pro jejich stažení.
  • blocks.json se nachází v šabloně nebo pluginu uživatele. Určuje, které registry použít a do kterého adresáře bloky instalovat.

Při instalaci bloku CLI načte všechny registry uvedené v blocks.json, najde blok, vyřeší jeho závislosti, stáhne všechny uvedené soubory z {baseUrl}/{block}/{file} a uloží je do {directory}/{block}/{file}. Neprovádí žádné transformace, takže soubory na disku jsou přesně stejné jako v repozitáři.

Krok 1: Uspořádání repozitáře

Vytvořte repozitář, v jehož kořenovém adresáři bude registry.json a pod cestou blocks/ samostatná složka pro každý blok:

Kód
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

Název složky je název bloku v registru a stane se názvem složky v šabloně uživatele. Ponechte jej totožný s druhou částí názvu bloku v block.json (acme/hero se nachází v hero/), aby nainstalovanou složku bylo snadné rozpoznat.

Krok 2: Vytvoření bloků

Každá složka je běžný blok Blockstudio. Blok úvodní sekce má 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 se řídí stejným vzorem a přidává style.scss. tabs vykresluje <InnerBlocks allowedBlocks='["acme/tab-item"]' /> a tab-item deklaruje "parent": ["acme/tabs"], takže tabs není užitečný bez tab-item. Registr tento vztah popisuje v dalším kroku.

Tyto bloky nijak nezávisí na registru. CLI pouze kopíruje složky, takže stejným způsobem lze publikovat blok vytvořený pomocí @wordpress/create-block nebo zaregistrovaný běžným PHP.

Krok 3: Vytvoření registry.json

registry.json obsahuje seznam všech bloků a všech souborů, které má CLI stáhnout:

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

Funkčnost tohoto souboru určují následující pravidla:

  • files je explicitní seznam. CLI stahuje přesně tyto cesty a nic jiného. Nepoužívá se žádné vyhledávání podle vzoru, takže se nový prostředek začne dodávat až poté, co ho sem přidáte. Cesty mohou obsahovat podadresáře, které se při instalaci vytvoří.
  • baseUrl musí být absolutní URL. CLI ho ověřuje jako URL a relativní hodnoty odmítá. Soubory bloků se vždy načítají z baseUrl, nikdy z místa relativního k tomu, odkud bylo načteno registry.json.
  • dependencies pojmenovávají bloky ve stejném registru. Přidáním tabs se nejprve nainstaluje tab-item. Chybějící a cyklické závislosti instalaci zastaví chybou.
  • name je povinné, ale nezobrazuje se. Příkazy a výstup používají klíč, který uživatel registru zadá v blocks.json; nemusí se shodovat.
  • type má pouze informativní význam. Přijímá blockstudio, create-block nebo wordpress a nemění to, co CLI dělá.

CLI při každém načtení ověří celý soubor a nahlásí každé pole s chybou, takže překlep odhalíte ještě před stažením jakéhokoli souboru. Řádek $schema nabízí stejné kontroly v editoru.

Krok 4: Publikování přes přímé adresy URL

Potvrďte změny a odešlete repozitář do GitHub. Každý soubor ve veřejném repozitáři pak bude dostupný na adrese:

Kód
https://raw.githubusercontent.com/<owner>/<repo>/<ref>/<path>

<ref> je větev, značka nebo SHA commitu. Pro tento registr jsou důležité dvě adresy URL:

  • Uživatelé registru URL nastavují: https://raw.githubusercontent.com/acme/acme-blocks/main/registry.json
  • baseUrl v registry.json: https://raw.githubusercontent.com/acme/acme-blocks/main/blocks

S tímto baseUrl se index.php pro hero načte z https://raw.githubusercontent.com/acme/acme-blocks/main/blocks/hero/index.php. Zdrojový hostitel vrací obsah souboru místo stránky GitHub HTML, kterou CLI potřebuje. Chybný vlastník, repozitář nebo ref se projeví jako 404 při prvním příkazu:

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

Krok 5: Instalace bloků do šablony

V kořenovém adresáři šablony, která bloky používá, vytvořte blocks.json:

Shell
npx blockstudio init --yes
Kód
Created .../acme-theme/blocks.json

init --yes vytvoří prázdný objekt registries. Přidejte registr pod jmenný prostor, který chcete zadávat v příkazech:

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

Spusťte init v terminálu bez --yes a na stejné otázky odpovídejte interaktivně (adresář bloků, názvy registrů a adresy URL).

Ověřte, že registr lze najít:

Shell
npx blockstudio list
Kód
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 hledá v názvech, titulcích a popisech podřetězec bez ohledu na velikost písmen:

Shell
npx blockstudio search tab
Kód
Results for "tab"

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

Náhled instalace zobrazíte pomocí --dry-run. Závislost je uvedena jako první, protože se instaluje jako první:

Shell
npx blockstudio add acme/tabs --dry-run
Kód
Would install:
  tab-item (2 files)
  tabs (3 files)

Pak proveďte instalaci:

Shell
npx blockstudio add acme/tabs
Kód
Downloading acme/tabs...
Installed tab-item (2 files)
Installed tabs (3 files)

Obě složky nyní leží v adresáři blockstudio šablony přesně ve stejné struktuře jako v repozitáři:

Kód
blockstudio/tab-item/block.json
blockstudio/tab-item/index.php
blockstudio/tabs/block.json
blockstudio/tabs/index.php
blockstudio/tabs/style.scss

Pokud má blok jen jeden nakonfigurovaný registr, můžete jmenný prostor vynechat a předat několik bloků najednou:

Shell
npx blockstudio add hero card
Kód
Downloading acme/hero...
Installed hero (2 files)
Downloading acme/card...
Installed card (3 files)

Blockstudio najde nové složky jako jakýkoli jiný blok v šabloně.

Aktualizace nainstalovaných bloků

Nainstalované soubory jsou kopií. Nesleduje se, kterou verzi jste nainstalovali, a CLI bloky samo nikdy neaktualizuje. Chcete-li stáhnout novější verzi, přidejte blok znovu. Bez terminálu nebo v CI zastaví příkaz existující složka:

Shell
npx blockstudio add tab-item
Kód
Block "tab-item" already exists at .../acme-theme/blockstudio/tab-item. Use --yes to overwrite.

V terminálu se vás CLI nejprve zeptá, zda chcete soubory přepsat. --dry-run vypíše složky, které by nahradil, a --yes je nahradí:

Shell
npx blockstudio add acme/tab-item --dry-run
Kód
Would overwrite tab-item
Would install:
  tab-item (2 files)

Přepsáním se uvedené soubory nahradí verzí z registru. Nejprve proto potvrďte místní změny a výsledek zkontrolujte pomocí git diff.

Chcete-li blok odinstalovat, odstraňte složku podle názvu:

Shell
npx blockstudio remove tabs --yes
Kód
Removed tabs

remove přijímá název složky, nikoli namespace/block. Závislosti neodstraňuje, takže tab-item zůstane nainstalovaný i po odebrání tabs.

Správa verzí pomocí odkazů git

CLI nemá pole pro verzi ani přepínač verze. To, co stáhne, určují výhradně adresy URL; na GitHub je ref v URL verzí. Uživatel, který nastaví main, získá při instalaci aktuální obsah main.

Chcete-li vydat neměnnou verzi, musí registry.json na značce stahovat soubory také z této značky. Před vytvořením značky nastavte baseUrl na její hodnotu:

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

Poté potvrďte změny, vytvořte značku a odešlete je:

Shell
git commit -am 'Release v1.0.0'
git tag v1.0.0
git push origin main v1.0.0

Poté nastavte baseUrl zpět na main a potvrďte změnu, aby větev dál poskytovala aktuální soubory. Pokud první krok přeskočíte, uživatel připnutý ke značce získá seznam bloků z této značky, ale soubory stáhne z main.

Uživatelé připnou verzi zadáním značky v adrese URL svého registru 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"
  }
}

V tomto příkladu byla značka v1.0.0 vytvořena ještě před vznikem tabs a tab-item, takže připnutý registr nabízí pouze dva původní bloky:

Shell
npx blockstudio list
Kód
acme (2 blocks)

  Name  Title  Category      Type
  hero  Hero   layout        blockstudio
  card  Card   components    blockstudio
Shell
npx blockstudio add acme/tabs
Kód
Block "tabs" not found in registry "acme".

SHA commitu lze použít také v adrese URL registru URL, ale commit nemůže obsahovat své vlastní SHA v baseUrl. Připnutí podle SHA proto zafixuje seznam bloků, zatímco soubory se stále načítají z refu, který pojmenovává baseUrl daného commitu. Pro vydání verzí proto upřednostněte značky.

Co je třeba mít na paměti

  • Nejprve se načte každý registr. add načte všechny registry v blocks.json ještě před vyhledáváním, takže příkaz selže, pokud je některý registr nedostupný, a to i pro acme/hero. Registry, které už nepoužíváte, odstraňte.
  • Nejednoznačné názvy vyžadují jmenný prostor. Pokud mají dva registry stejný název hero, terminál se zeptá, který použít, --yes použije první v pořadí blocks.json a neinteraktivní spuštění skončí s kódem Block "hero" found in multiple registries: acme, starter. Specify one: blockstudio add acme/hero.
  • Soukromé repozitáře vyžadují hlavičky. Použijte objektovou podobu položky registru s url a headers. Hodnoty hlaviček podporují zástupné symboly ${VAR}, které se načítají z prostředí. CLI odesílá hlavičky při načítání registru i při stahování každého souboru. Nastavení tokenu najdete v části hostování GitHub.

Další kroky