Publicera ett blockregister på GitHub
När du har byggt några bra block vill du även ha dem i nästa projekt.
Att kopiera mappar manuellt mellan teman fungerar tills kopiorna skiljer sig åt och
ingen längre minns vilket tema som har den rättade versionen. Att paketera varje block i ett eget paket med en egen byggprocess innebär mycket omständligt arbete för en mapp som innehåller ett block.json och en mall.
Ett blockregister fyller mellanrummet. Det är en fil av typen registry.json och en uppsättning blockmappar som levereras via vanlig HTTP. Användarna kör ett CLI-kommando, blockkällan kopieras till deras tema och därefter ansvarar de själva för kopian. Ett GitHub-arkiv räcker för att stå värd för ett register, eftersom GitHub levererar alla filer i ett offentligt arkiv via en rå URL.
Den här guiden bygger ett register som heter acme med fyra block, publicerar det från arkivet acme/acme-blocks, installerar block därifrån i ett tema och låser en utgåva via en git-tagg.
Paketet blockstudio på npm har version 0.0.1. Den utgåvan är en platshållare: dess enda kommando, add, skriver ut Adding block: <name> och avslutas utan att hämta något. Kommandona och utdata i den här guiden kommer från registret CLI i arkivet Blockstudio (packages/registry), som är det register som beskrivs i dokumentationen CLIRegistry docs.
Så hänger delarna ihop
Det finns två filer att känna till:
registry.jsonpubliceras av blockförfattaren. Den listar blocken, filerna som varje block består av och enbaseUrlför att hämta dem.blocks.jsonfinns i användarens tema eller tillägg. Den anger vilka register som ska användas och vilken katalog block installeras i.
När du installerar ett block hämtar CLI varje register i blocks.json, hittar blocket, löser dess beroenden, laddar ned varje listad fil från {baseUrl}/{block}/{file} och skriver den till {directory}/{block}/{file}. Inget omvandlas, så filerna på disken är exakt desamma som i arkivet.
Steg 1: Strukturera arkivet
Skapa ett arkiv med en registry.json i roten och en mapp per block under 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
Mappnamnet är blockets namn i registret och blir mappnamnet i användarens tema. Se till att det stämmer exakt med den andra delen av blocknamnet i block.json (acme/hero finns i hero/), så blir den installerade mappen lätt att känna igen.
Steg 2: Skriv blocken
Varje mapp innehåller ett vanligt Blockstudio-block. Hero-blocket har ett fält:
{
"$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 följer samma mönster och lägger till en style.scss. tabs renderar <InnerBlocks allowedBlocks='["acme/tab-item"]' />, och tab-item deklarerar "parent": ["acme/tabs"], så tabs är inte användbart utan tab-item. Registret uttrycker sambandet i nästa steg.
Inget i dessa block är specifikt för ett register. CLI kopierar mappar, så block som byggts med @wordpress/create-block eller registrerats med vanlig PHP kan publiceras på samma sätt.
Steg 3: Skriv registry.json
registry.json listar alla block och filer som CLI ska hämta:
{
"$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"]
}
]
}
Det finns några regler som avgör om den här filen fungerar:
filesär en explicit lista. CLI laddar ner exakt dessa sökvägar och inget annat. Ingen globning används, så en ny resurs inkluderas först när du lägger till den här. Sökvägar kan innehålla underkataloger, som skapas vid installationen.baseUrlmåste vara en absolut URL. CLI validerar den som en URL och avvisar relativa värden. Blockfiler hämtas alltid frånbaseUrl, aldrig från en plats relativ till varregistry.jsonlästes in.dependencies-namn anger block i samma register. Om du lägger tilltabsinstallerastab-itemförst. Saknade och cirkulära beroenden avbryter installationen med ett fel.namekrävs men visas inte. Kommandon och utdata använder nyckeln som konsumenten anger för registret iblocks.json, och den behöver inte stämma överens.typeär informativ. Den godtarblockstudio,create-blockellerwordpressoch påverkar inte vad CLI gör.
CLI validerar hela filen vid varje hämtning och rapporterar varje fält med fel,
så ett stavfel upptäcks innan någon fil laddas ner. Raden $schema ger dig
samma kontroller i redigeraren.
Steg 4: Publicera via råa URL:er
Commit:a och skicka repot till GitHub. Därefter finns varje fil i ett offentligt repo tillgänglig på:
https://raw.githubusercontent.com/<owner>/<repo>/<ref>/<path>
<ref> är en branch, en tagg eller en commit-SHA. För det här registret är två
URL:er viktiga:
- Registrets URL som konsumenter konfigurerar:
https://raw.githubusercontent.com/acme/acme-blocks/main/registry.json baseUrliregistry.json:https://raw.githubusercontent.com/acme/acme-blocks/main/blocks
Med den baseUrl hämtas index.php för hero från
https://raw.githubusercontent.com/acme/acme-blocks/main/blocks/hero/index.php.
Den råa värdtjänsten returnerar filinnehållet i stället för sidan GitHub HTML,
vilket är vad CLI behöver. Fel ägare, repo eller ref märks som ett 404 vid det
första kommandot:
Registry returned 404 for https://raw.githubusercontent.com/acme/acme-blocks/main/registry.json
Steg 5: Installera block i ett tema
Skapa blocks.json i roten av temat som ska använda blocken:
npx blockstudio init --yes
Created .../acme-theme/blocks.json
init --yes skriver ett tomt registries-objekt. Lägg till registret under det
namnutrymme du vill skriva i kommandon:
{
"$schema": "https://blockstudio.dev/schema/blocks.json",
"directory": "blockstudio",
"registries": {
"acme": "https://raw.githubusercontent.com/acme/acme-blocks/main/registry.json"
}
}
Kör init utan --yes i en terminal om du i stället vill besvara samma frågor
interaktivt (blockkatalog, registernamn och URL:er).
Kontrollera att registret kan hittas:
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 matchar en delsträng utan hänsyn till versaler och gemener i namn, titlar och
beskrivningar:
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.
Förhandsgranska en installation med --dry-run. Beroendet listas först eftersom det
installeras först:
npx blockstudio add acme/tabs --dry-run
Would install:
tab-item (2 files)
tabs (3 files)
Installera sedan på riktigt:
npx blockstudio add acme/tabs
Downloading acme/tabs...
Installed tab-item (2 files)
Installed tabs (3 files)
Båda mapparna finns nu i temats katalog blockstudio, precis som de
ligger i repot:
blockstudio/tab-item/block.json
blockstudio/tab-item/index.php
blockstudio/tabs/block.json
blockstudio/tabs/index.php
blockstudio/tabs/style.scss
Du kan utelämna namnutrymmet när blocket bara finns i ett konfigurerat register och ange flera block på en gång:
npx blockstudio add hero card
Downloading acme/hero...
Installed hero (2 files)
Downloading acme/card...
Installed card (3 files)
Blockstudio hittar de nya mapparna precis som andra block i temat.
Uppdatera installerade block
De installerade filerna är kopior. Ingen versionsinformation sparas, och CLI uppdaterar aldrig ett block på egen hand. Lägg till blocket igen för att hämta en nyare version. Utan en terminal, eller i CI, avbryts kommandot om en befintlig mapp hittas:
npx blockstudio add tab-item
Block "tab-item" already exists at .../acme-theme/blockstudio/tab-item. Use --yes to overwrite.
I en terminal frågar CLI i stället innan den skriver över. --dry-run visar
mapparna som skulle ersättas, och --yes ersätter dem:
npx blockstudio add acme/tab-item --dry-run
Would overwrite tab-item
Would install:
tab-item (2 files)
Överskrivning ersätter de listade filerna med registrets version, så spara
lokala ändringar först och granska resultatet med git diff.
Avinstallera genom att ta bort mappen med dess namn:
npx blockstudio remove tabs --yes
Removed tabs
remove tar mappnamnet, inte namespace/block. Det tar inte bort
beroenden, så tab-item finns kvar efter att tabs har tagits bort.
Versionshantering med git-referenser
CLI har inget versionsfält och ingen versionsflagga. Vad det hämtar avgörs
helt av URL:erna, och på GitHub är ref:en i URL versionen. En konsument
som pekar på main får det som main innehåller vid installationstillfället.
Om du vill publicera en fast version måste registry.json vid taggen också
hämta från taggen. Ange taggen i baseUrl innan du taggar:
"baseUrl": "https://raw.githubusercontent.com/acme/acme-blocks/v1.0.0/blocks"
Commit:a, tagga och skicka sedan:
git commit -am 'Release v1.0.0'
git tag v1.0.0
git push origin main v1.0.0
Ändra sedan baseUrl tillbaka till main och gör en commit, så att branchen fortsätter
att leverera aktuella filer. Om du hoppar över det första steget får en konsument
som låst sig vid taggen blocklistan från taggen, men hämtar filerna från main.
Konsumenter låser versionen genom att använda taggen i registrets URL:
{
"$schema": "https://blockstudio.dev/schema/blocks.json",
"directory": "blockstudio",
"registries": {
"acme": "https://raw.githubusercontent.com/acme/acme-blocks/v1.0.0/registry.json"
}
}
I det här exemplet taggades v1.0.0 innan tabs och tab-item fanns, så
registret med låst version erbjuder bara de två ursprungliga blocken:
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".
En commit-SHA fungerar också i registrets URL, men en commit kan inte innehålla sin egen
SHA i baseUrl. Om du låser versionen med en SHA låses därför blocklistan, medan filerna
fortfarande hämtas från den ref som den commitens baseUrl anger. Använd därför taggar för
versioner.
Bra att känna till
- Varje register hämtas först.
addläser in alla register iblocks.jsoninnan det löser något, så ett oåtkomligt register gör att kommandot misslyckas även föracme/hero. Ta bort register som du inte längre använder. - Tvetydiga namn kräver ett namnutrymme. Om två register båda har
herofrågar en terminalsession vilket register som ska användas,--yesväljer det första iblocks.json-ordningen, och en icke-interaktiv körning avslutas medBlock "hero" found in multiple registries: acme, starter. Specify one: blockstudio add acme/hero. - Privata repon behöver headers. Använd objektformen för en registerpost
med
urlochheaders. Headervärden stöder platshållare för${VAR}, som läses från miljön, och CLI skickar header-fälten med registerhämtningen och varje filnedladdning. Se GitHub-värdtjänsten för information om tokenkonfigurationen.
Nästa steg
- Översikt över registret: vad registret är och hur CLI fungerar
- registry.json: manifestets alla fält
- blocks.json: konsumentkonfiguration, autentisering och konfigurationsidentifiering
- add: lösning av namnutrymmen, beroenden och överskrivningsbeteende
- GitHub-värdtjänst: GitHub Pages och privata repon
- Anpassad server: kör ett register på din egen infrastruktur