Een blokregister publiceren op GitHub
Als u eenmaal een paar goede blokken hebt gebouwd, wilt u die ook in uw volgende project gebruiken. Mappen handmatig tussen thema’s kopiëren werkt totdat de kopieën uiteenlopen en niemand meer weet in welk thema de gerepareerde versie staat. Elk blok in een pakket met een eigen build onderbrengen is veel omslachtig gedoe voor een map met een block.json en een template.
Een blokregister biedt uitkomst. Het bestaat uit een bestand registry.json en een set blokmappen die via gewone HTTP worden aangeboden. Gebruikers voeren een opdracht van CLI uit, de blokbroncode wordt naar hun thema gekopieerd en vanaf dat moment beheren ze die kopie zelf. Een repository van GitHub volstaat om er een te hosten, omdat GitHub elk bestand in een openbare repository aanbiedt via een raw URL.
Deze gids bouwt een register met de naam acme met vier blokken, publiceert het vanuit repository acme/acme-blocks, installeert er blokken uit in een thema en legt een release vast met een git-tag.
Het pakket blockstudio op npm heeft versie 0.0.1. Die release is een tijdelijke aanduiding: de enige opdracht, add, toont Adding block: <name> en stopt zonder iets op te halen. De opdrachten en uitvoer in deze gids komen uit register CLI in repository Blockstudio (packages/registry), de CLI die wordt beschreven in de Registerdocumentatie.
Hoe de onderdelen samenwerken
Er zijn twee bestanden die u moet kennen:
registry.jsonwordt gepubliceerd door de auteur van het blok. Het vermeldt de blokken, de bestanden waaruit elk blok bestaat en eenbaseUrlom ze te downloaden.blocks.jsonstaat in het thema of de plugin van de gebruiker. Het geeft aan welke registers u wilt gebruiken en in welke map blokken worden geïnstalleerd.
Wanneer u een blok installeert, haalt CLI elk register op in blocks.json, zoekt het blok, lost de afhankelijkheden op, downloadt elk vermeld bestand van {baseUrl}/{block}/{file} en schrijft het naar {directory}/{block}/{file}. Er wordt niets getransformeerd, dus de bestanden op schijf zijn precies dezelfde als in de repository.
Stap 1: structureer de repository
Maak een repository met een registry.json in de hoofdmap en één map per blok onder 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
De mapnaam is de naam van het blok in het register en wordt ook de mapnaam in het thema van de gebruiker. Houd die gelijk aan het tweede deel van de bloknaam in block.json (acme/hero staat in hero/), zodat de geïnstalleerde map makkelijk herkenbaar is.
Stap 2: schrijf de blokken
Elke map is een gewoon Blockstudio-blok. Het hero-blok heeft één veld:
{
"$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 volgt hetzelfde patroon en voegt een style.scss toe. tabs rendert <InnerBlocks allowedBlocks='["acme/tab-item"]' /> en tab-item declareert "parent": ["acme/tabs"], dus tabs is niet nuttig zonder tab-item. Het register legt die relatie in de volgende stap vast.
Niets aan deze blokken is specifiek voor een register. De CLI kopieert mappen, dus een blok dat met @wordpress/create-block is gebouwd of met gewone PHP is geregistreerd, kan op dezelfde manier worden gepubliceerd.
Stap 3: schrijf registry.json
registry.json vermeldt elk blok en elk bestand dat CLI moet downloaden:
{
"$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"]
}
]
}
Een paar regels bepalen of dit bestand werkt:
filesis een expliciete lijst. De CLI downloadt precies deze paden en niets anders. Er wordt niet met jokertekens gewerkt, dus een nieuw onderdeel wordt pas meegeleverd als je het hier toevoegt. Paden kunnen submappen bevatten; die worden tijdens de installatie aangemaakt.baseUrlmoet een absolute URL zijn. De CLI valideert deze als URL en weigert relatieve waarden. Blockbestanden worden altijd opgehaald vanbaseUrl, nooit vanaf een locatie relatief aan waarregistry.jsonis geladen.dependenciesbenoemt blocks in hetzelfde register. Doortabstoe te voegen, wordt eersttab-itemgeïnstalleerd. Ontbrekende en circulaire afhankelijkheden breken de installatie af met een foutmelding.nameis vereist, maar wordt niet weergegeven. Commando’s en uitvoer gebruiken de sleutel die de gebruiker aan het register geeft inblocks.json; die hoeft niet overeen te komen.typeis informatief. Deze accepteertblockstudio,create-blockofwordpressen verandert niets aan wat CLI doet.
De CLI valideert het volledige bestand bij elke ophaalactie en meldt elk veld met een fout, zodat een typefout aan het licht komt voordat er bestanden worden gedownload. De regel $schema voert dezelfde controles uit in je editor.
Stap 4: Publiceren via raw-URL’s
Commit en push de repository naar GitHub. Elk bestand in een openbare repository is daarna beschikbaar op:
https://raw.githubusercontent.com/<owner>/<repo>/<ref>/<path>
<ref> is een branch, tag of commit-SHA. Voor dit register zijn er twee relevante URL’s:
- De register-URL die consumenten configureren:
https://raw.githubusercontent.com/acme/acme-blocks/main/registry.json - De
baseUrlinregistry.json:https://raw.githubusercontent.com/acme/acme-blocks/main/blocks
Met die baseUrl wordt de index.php van hero opgehaald van https://raw.githubusercontent.com/acme/acme-blocks/main/blocks/hero/index.php.
De raw-host retourneert de bestandsinhoud in plaats van de GitHub-pagina van HTML, wat CLI nodig heeft. Een onjuiste eigenaar, repository of ref leidt bij het eerste commando tot een 404:
Registry returned 404 for https://raw.githubusercontent.com/acme/acme-blocks/main/registry.json
Stap 5: Blocks installeren in een theme
Maak blocks.json aan in de hoofdmap van het theme dat het register gebruikt:
npx blockstudio init --yes
Created .../acme-theme/blocks.json
init --yes schrijft een leeg registries-object. Voeg het register toe onder de namespace die je in commando’s wilt typen:
{
"$schema": "https://blockstudio.dev/schema/blocks.json",
"directory": "blockstudio",
"registries": {
"acme": "https://raw.githubusercontent.com/acme/acme-blocks/main/registry.json"
}
}
Voer init zonder --yes uit in een terminal om dezelfde vragen interactief te beantwoorden (blockmap, registernamen en URL’s).
Controleer of het register wordt gevonden:
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 vergelijkt namen, titels en beschrijvingen met een hoofdletterongevoelig deel van de zoektekst:
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.
Bekijk een installatievoorbeeld met --dry-run. De afhankelijkheid staat vooraan, omdat deze als eerste wordt geïnstalleerd:
npx blockstudio add acme/tabs --dry-run
Would install:
tab-item (2 files)
tabs (3 files)
Installeer het vervolgens echt:
npx blockstudio add acme/tabs
Downloading acme/tabs...
Installed tab-item (2 files)
Installed tabs (3 files)
Beide mappen staan nu in de map blockstudio van het theme, precies zoals in de repository:
blockstudio/tab-item/block.json
blockstudio/tab-item/index.php
blockstudio/tabs/block.json
blockstudio/tabs/index.php
blockstudio/tabs/style.scss
Je kunt de namespace weglaten als slechts één geconfigureerd register het block bevat, en meerdere blocks tegelijk opgeven:
npx blockstudio add hero card
Downloading acme/hero...
Installed hero (2 files)
Downloading acme/card...
Installed card (3 files)
Blockstudio vindt de nieuwe mappen net als elk ander block in het theme.
Geïnstalleerde blocks bijwerken
De geïnstalleerde bestanden zijn een kopie. Er wordt niet bijgehouden welke versie je hebt geïnstalleerd en CLI werkt een block nooit vanzelf bij. Voeg het block opnieuw toe om een nieuwere versie op te halen. Zonder terminal, of in CI, stopt het commando als een map al bestaat:
npx blockstudio add tab-item
Block "tab-item" already exists at .../acme-theme/blockstudio/tab-item. Use --yes to overwrite.
In een terminal vraagt CLI eerst of je wilt overschrijven. --dry-run toont welke mappen zouden worden vervangen en --yes vervangt ze:
npx blockstudio add acme/tab-item --dry-run
Would overwrite tab-item
Would install:
tab-item (2 files)
Bij overschrijven worden de vermelde bestanden vervangen door de versie uit het register. Commit dus eerst lokale wijzigingen en controleer het resultaat met git diff.
Verwijder de map op naam om een block te de-installeren:
npx blockstudio remove tabs --yes
Removed tabs
remove verwacht de mapnaam, niet namespace/block. Afhankelijkheden worden niet verwijderd, dus tab-item blijft geïnstalleerd nadat je tabs hebt verwijderd.
Versiebeheer met git-referenties
De CLI heeft geen versieveld of versieoptie. Wat het ophaalt, wordt volledig bepaald door de URL’s; bij GitHub is de ref in de URL de versie. Een consument die naar main verwijst, krijgt bij de installatie de inhoud die main op dat moment bevat.
Als je een release wilt publiceren die vast blijft staan, moet de registry.json bij de tag ook vanaf die tag downloaden. Stel vóór het taggen baseUrl in op de tag:
"baseUrl": "https://raw.githubusercontent.com/acme/acme-blocks/v1.0.0/blocks"
Commit en push daarna de tag:
git commit -am 'Release v1.0.0'
git tag v1.0.0
git push origin main v1.0.0
Stel daarna baseUrl weer in op main en commit de wijziging, zodat de branch de nieuwste bestanden blijft aanbieden. Sla je de eerste stap over, dan krijgt een consument die de tag vastzet wel de lijst met blocks van die tag, maar worden de bestanden opgehaald van main.
Consumenten zetten een versie vast door de tag in hun register-URL te gebruiken:
{
"$schema": "https://blockstudio.dev/schema/blocks.json",
"directory": "blockstudio",
"registries": {
"acme": "https://raw.githubusercontent.com/acme/acme-blocks/v1.0.0/registry.json"
}
}
In dit voorbeeld is v1.0.0 getagd voordat tabs en tab-item bestonden, dus bevat het vastgezette register alleen de twee oorspronkelijke blocks:
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".
Een commit-SHA werkt ook in de register-URL, maar een commit kan zijn eigen SHA niet bevatten in baseUrl. Vastzetten op basis van een SHA fixeert daarom wel de blocklijst, maar de bestanden komen nog steeds van de ref waarnaar baseUrl van die commit verwijst. Gebruik daarom liever tags voor releases.
Zaken om rekening mee te houden
- Elk register wordt eerst opgehaald.
addlaadt alle registers inblocks.jsonvoordat het iets oplost, dus als één register onbereikbaar is, mislukt de opdracht, zelfs vooracme/hero. Verwijder registers die u niet meer gebruikt. - Onduidelijke namen vereisen een naamruimte. Als twee registers beide
herobevatten, vraagt een terminalsessie welke u wilt gebruiken, neemt--yesde eerste in de volgorde vanblocks.json, en stopt een niet-interactieve uitvoering metBlock "hero" found in multiple registries: acme, starter. Specify one: blockstudio add acme/hero. - Voor privérepositories zijn headers nodig. Gebruik de objectvorm van een registervermelding
met
urlenheaders. Headerwaarden ondersteunen placeholders${VAR}die uit de omgeving worden gelezen, en de CLI stuurt de headers mee met het ophalen van het register en met elke bestandsdownload. Zie GitHubhosting voor de tokenconfiguratie.
Volgende stappen
- Registeroverzicht: wat het register is en hoe de CLI werkt
- registry.json: alle velden van het manifest
- blocks.json: configuratie voor consumenten, authenticatie en het vinden van configuratie
- toevoegen: namespacebepaling, afhankelijkheden en hoe overschrijven werkt
- GitHub hosting: GitHub Pages en privérepositories
- Aangepaste server: een register aanbieden vanaf je eigen infrastructuur