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.jsonzveřejňuje autor bloku. Obsahuje seznam bloků, soubory tvořící každý blok abaseUrlpro jejich stažení.blocks.jsonse 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:
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:
{
"$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 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:
{
"$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:
filesje 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ří.baseUrlmusí být absolutní URL. CLI ho ověřuje jako URL a relativní hodnoty odmítá. Soubory bloků se vždy načítají zbaseUrl, nikdy z místa relativního k tomu, odkud bylo načtenoregistry.json.dependenciespojmenovávají bloky ve stejném registru. Přidánímtabsse nejprve nainstalujetab-item. Chybějící a cyklické závislosti instalaci zastaví chybou.nameje povinné, ale nezobrazuje se. Příkazy a výstup používají klíč, který uživatel registru zadá vblocks.json; nemusí se shodovat.typemá pouze informativní význam. Přijímáblockstudio,create-blocknebowordpressa 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:
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 baseUrlvregistry.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:
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:
npx blockstudio init --yes
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:
{
"$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:
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 hledá v názvech, titulcích a popisech podřetězec bez ohledu na velikost
písmen:
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.
Náhled instalace zobrazíte pomocí --dry-run. Závislost je uvedena jako první,
protože se instaluje jako první:
npx blockstudio add acme/tabs --dry-run
Would install:
tab-item (2 files)
tabs (3 files)
Pak proveďte instalaci:
npx blockstudio add acme/tabs
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:
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:
npx blockstudio add hero card
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:
npx blockstudio add tab-item
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í:
npx blockstudio add acme/tab-item --dry-run
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:
npx blockstudio remove tabs --yes
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:
"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:
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:
{
"$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:
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 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.
addnačte všechny registry vblocks.jsonještě před vyhledáváním, takže příkaz selže, pokud je některý registr nedostupný, a to i proacme/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,--yespoužije první v pořadíblocks.jsona neinteraktivní spuštění skončí s kódemBlock "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
urlaheaders. 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
- Přehled registru: co je registr a jak funguje CLI
- registry.json: všechna pole manifestu
- blocks.json: konfigurace uživatele, ověřování a vyhledání konfigurace
- add: řešení jmenných prostorů, závislosti a chování při přepisování
- hostování GitHub: GitHub Pages a soukromé repozitáře
- Vlastní server: poskytování registru z vlastní infrastruktury