Ga naar de inhoud

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.json wordt gepubliceerd door de auteur van het blok. Het vermeldt de blokken, de bestanden waaruit elk blok bestaat en een baseUrl om ze te downloaden.
  • blocks.json staat 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/:

Code
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:

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 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:

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

Een paar regels bepalen of dit bestand werkt:

  • files is 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.
  • baseUrl moet een absolute URL zijn. De CLI valideert deze als URL en weigert relatieve waarden. Blockbestanden worden altijd opgehaald van baseUrl, nooit vanaf een locatie relatief aan waar registry.json is geladen.
  • dependencies benoemt blocks in hetzelfde register. Door tabs toe te voegen, wordt eerst tab-item geïnstalleerd. Ontbrekende en circulaire afhankelijkheden breken de installatie af met een foutmelding.
  • name is vereist, maar wordt niet weergegeven. Commando’s en uitvoer gebruiken de sleutel die de gebruiker aan het register geeft in blocks.json; die hoeft niet overeen te komen.
  • type is informatief. Deze accepteert blockstudio, create-block of wordpress en 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:

Code
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 baseUrl in registry.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:

Code
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:

Shell
npx blockstudio init --yes
Code
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:

JSON
{
  "$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:

Shell
npx blockstudio list
Code
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:

Shell
npx blockstudio search tab
Code
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:

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

Installeer het vervolgens echt:

Shell
npx blockstudio add acme/tabs
Code
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:

Code
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:

Shell
npx blockstudio add hero card
Code
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:

Shell
npx blockstudio add tab-item
Code
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:

Shell
npx blockstudio add acme/tab-item --dry-run
Code
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:

Shell
npx blockstudio remove tabs --yes
Code
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:

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

Commit en push daarna de tag:

Shell
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:

JSON
{
  "$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:

Shell
npx blockstudio list
Code
acme (2 blocks)

  Name  Title  Category      Type
  hero  Hero   layout        blockstudio
  card  Card   components    blockstudio
Shell
npx blockstudio add acme/tabs
Code
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. add laadt alle registers in blocks.json voordat het iets oplost, dus als één register onbereikbaar is, mislukt de opdracht, zelfs voor acme/hero. Verwijder registers die u niet meer gebruikt.
  • Onduidelijke namen vereisen een naamruimte. Als twee registers beide hero bevatten, vraagt een terminalsessie welke u wilt gebruiken, neemt --yes de eerste in de volgorde van blocks.json, en stopt een niet-interactieve uitvoering met Block "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 url en headers. 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