Vai al contenuto

Pubblicare un registro di blocchi su GitHub

Dopo aver creato alcuni blocchi efficaci, vorrete riutilizzarli anche nel progetto successivo. Copiare a mano le cartelle tra i temi funziona, finché le copie divergono e nessuno ricorda più in quale tema si trovi la versione corretta. Racchiudere ogni blocco in un pacchetto con una build propria comporta molte formalità per una cartella che contiene un block.json e un template.

Un registro di blocchi offre una via di mezzo. È un file registry.json e un insieme di cartelle di blocchi, serviti tramite un semplice HTTP. Chi li usa esegue un comando CLI, il sorgente del blocco viene copiato nel tema e da quel momento ne gestisce la copia. Basta un repository GitHub per ospitare il registro, perché GitHub serve ogni file di un repository pubblico tramite un URL raw.

Questa guida crea un registro chiamato acme con quattro blocchi, lo pubblica dal repository acme/acme-blocks, installa i blocchi in un tema e fissa una versione tramite un tag git.

Il pacchetto blockstudio su npm è alla versione 0.0.1. Questa release è un segnaposto: il suo unico comando, add, stampa Adding block: <name> e termina senza recuperare alcun contenuto. I comandi e i risultati di questa guida provengono dal registro CLI nel repository Blockstudio (packages/registry), cioè l’CLI documentazione del registro descritta.

Come si integrano i componenti

Ci sono due file da conoscere:

  • registry.json viene pubblicato dall’autore del blocco. Elenca i blocchi, i file che li compongono e un baseUrl da cui scaricarli.
  • blocks.json si trova nel tema o nel plugin di chi usa il registro. Indica i registri da usare e la directory in cui installare i blocchi.

Quando installate un blocco, CLI recupera tutti i registri indicati in blocks.json, trova il blocco, risolve le dipendenze, scarica ogni file elencato da {baseUrl}/{block}/{file} e lo scrive in {directory}/{block}/{file}. Non trasforma nulla: i file su disco sono identici a quelli nel repository.

Passaggio 1: organizzare il repository

Create un repository con un registry.json nella directory principale e una cartella per ogni blocco in blocks/:

Codice
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

Il nome della cartella è il nome del blocco nel registro e diventa il nome della cartella nel tema di chi lo installa. Fatelo coincidere con la seconda parte del nome del blocco in block.json (acme/hero si trova in hero/), così la cartella installata sarà facile da individuare.

Passaggio 2: scrivere i blocchi

Ogni cartella contiene un normale blocco Blockstudio. Il blocco Hero ha un campo:

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 segue lo stesso schema e aggiunge un style.scss. tabs esegue il rendering di <InnerBlocks allowedBlocks='["acme/tab-item"]' />, mentre tab-item dichiara "parent": ["acme/tabs"], quindi tabs non è utile senza tab-item. Nel passaggio successivo, il registro specifica questa dipendenza.

Questi blocchi non hanno nulla di specifico per i registri. Il comando CLI copia le cartelle, quindi si possono pubblicare allo stesso modo sia i blocchi creati con @wordpress/create-block sia quelli registrati con PHP semplice.

Passaggio 3: scrivere registry.json

registry.json elenca ogni blocco e ogni file che CLI deve scaricare:

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

Alcune regole determinano se questo file funziona:

  • files è un elenco esplicito. CLI scarica esattamente questi percorsi e nient’altro. Non vengono usati pattern glob, quindi una nuova risorsa viene inclusa solo quando la aggiungete qui. I percorsi possono contenere sottodirectory, che vengono create durante l’installazione.
  • baseUrl deve essere un URL assoluto. CLI lo convalida come URL e rifiuta i valori relativi. I file dei blocchi vengono sempre recuperati da baseUrl, mai da una posizione relativa al punto in cui è stato caricato registry.json.
  • dependencies assegna nomi ai blocchi nello stesso registro. Aggiungendo tabs si installa prima tab-item. Le dipendenze mancanti o circolari interrompono l’installazione con un errore.
  • name è obbligatorio ma non viene visualizzato. I comandi e l’output usano la chiave fornita dal consumatore al registro in blocks.json, che non deve necessariamente corrispondere.
  • type ha solo valore informativo. Accetta blockstudio, create-block oppure wordpress e non cambia il comportamento di CLI.

CLI convalida l’intero file a ogni recupero e segnala ogni campo non valido, così un errore di battitura viene individuato prima che venga scaricato alcun file. La riga $schema offre le stesse verifiche nel vostro editor.

Passaggio 4: pubblicare tramite URL raw

Eseguite il commit e il push del repository su GitHub. Ogni file di un repository pubblico sarà quindi disponibile all’indirizzo:

Codice
https://raw.githubusercontent.com/<owner>/<repo>/<ref>/<path>

<ref> è un branch, un tag o uno SHA di commit. Per questo registro ci sono due URL importanti:

  • Il registro URL che i consumatori configurano: https://raw.githubusercontent.com/acme/acme-blocks/main/registry.json
  • Il baseUrl in registry.json: https://raw.githubusercontent.com/acme/acme-blocks/main/blocks

Con questo baseUrl, index.php di hero viene recuperato da https://raw.githubusercontent.com/acme/acme-blocks/main/blocks/hero/index.php. L’host raw restituisce il contenuto del file invece della pagina GitHub HTML, necessaria a CLI. Un proprietario, repository o ref errato viene segnalato come 404 al primo comando:

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

Passaggio 5: installare i blocchi in un tema

Nella radice del tema che li utilizza, create blocks.json:

Shell
npx blockstudio init --yes
Codice
Created .../acme-theme/blocks.json

init --yes scrive un oggetto registries vuoto. Aggiungete il registro nello spazio dei nomi che volete digitare nei comandi:

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

Eseguite init senza --yes in un terminale per rispondere alle stesse domande in modo interattivo (directory dei blocchi, nomi e URL dei registri).

Verificate che il registro venga risolto:

Shell
npx blockstudio list
Codice
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 cerca una sottostringa senza distinzione tra maiuscole e minuscole nei nomi, nei titoli e nelle descrizioni:

Shell
npx blockstudio search tab
Codice
Results for "tab"

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

Visualizzate un’anteprima dell’installazione con --dry-run. La dipendenza è elencata per prima, perché viene installata per prima:

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

Poi installate davvero:

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

Ora entrambe le cartelle si trovano nella directory blockstudio del tema, esattamente come nel repository:

Codice
blockstudio/tab-item/block.json
blockstudio/tab-item/index.php
blockstudio/tabs/block.json
blockstudio/tabs/index.php
blockstudio/tabs/style.scss

Potete omettere lo spazio dei nomi quando solo un registro configurato contiene il blocco e passare più blocchi contemporaneamente:

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

Blockstudio rileva le nuove cartelle come qualsiasi altro blocco del tema.

Aggiornare i blocchi installati

I file installati sono una copia. Non viene tracciata la versione installata e CLI non aggiorna mai un blocco autonomamente. Per scaricare una versione più recente, aggiungete di nuovo il blocco. Se non usate un terminale o eseguite il comando in CI, una cartella esistente interrompe il comando:

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

In un terminale, CLI chiede invece conferma prima di sovrascrivere. --dry-run segnala le cartelle che sostituirebbe e --yes le sostituisce:

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

La sovrascrittura sostituisce i file elencati con la versione del registro, quindi eseguite prima il commit delle modifiche locali e controllate il risultato con git diff.

Per disinstallare, rimuovete la cartella indicandone il nome:

Shell
npx blockstudio remove tabs --yes
Codice
Removed tabs

remove richiede il nome della cartella, non namespace/block. Non rimuove le dipendenze, quindi tab-item resta installato dopo la rimozione di tabs.

Controllo delle versioni con riferimenti git

CLI non ha un campo né un’opzione per la versione. Ciò che recupera è determinato interamente dagli URL e, su GitHub, il ref in URL è la versione. Un consumatore che punta a main ottiene ciò che main contiene al momento dell’installazione.

Per pubblicare una release immutabile, anche registry.json nel tag deve scaricare dal tag. Prima di creare il tag, impostate baseUrl sul tag:

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

Poi eseguite il commit, create il tag e fate il push:

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

In seguito, reimpostate baseUrl su main ed eseguite il commit, così il branch continua a servire i file correnti. Se saltate il primo passaggio, un consumatore vincolato al tag ottiene l’elenco dei blocchi del tag, ma scarica i file da main.

I consumatori fissano la versione usando il tag nel registro 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"
  }
}

In questo esempio v1.0.0 è stato creato prima che esistessero tabs e tab-item, quindi il registro fissato offre solo i due blocchi originali:

Shell
npx blockstudio list
Codice
acme (2 blocks)

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

Anche uno SHA di commit funziona nel registro URL, ma un commit non può contenere il proprio SHA in baseUrl. Fissare la versione tramite SHA blocca quindi l’elenco dei blocchi, mentre i file continuano a provenire dal ref indicato da baseUrl di quel commit. Per le release, quindi, preferite i tag.

Aspetti da tenere presenti

  • Ogni registro viene recuperato per primo. add carica tutti i registri in blocks.json prima di risolvere qualsiasi elemento, quindi un registro irraggiungibile fa fallire il comando anche per acme/hero. Rimuovete i registri che non usate più.
  • I nomi ambigui richiedono uno spazio dei nomi. Se due registri contengono entrambi hero, una sessione da terminale chiede quale usare, --yes sceglie il primo nell’ordine di blocks.json e un’esecuzione non interattiva termina con Block "hero" found in multiple registries: acme, starter. Specify one: blockstudio add acme/hero.
  • I repository privati richiedono intestazioni. Usate la forma a oggetto di una voce del registro con url e headers. I valori delle intestazioni supportano segnaposto ${VAR} letti dall’ambiente, e CLI invia le intestazioni con il recupero del registro e con ogni download di file. Per configurare il token, consultate l’hosting di GitHub.

Passaggi successivi

  • Panoramica del registro: cos’è il registro e come funziona CLI
  • registry.json: tutti i campi del manifest
  • blocks.json: configurazione del consumatore, autenticazione e rilevamento della configurazione
  • add: risoluzione degli spazi dei nomi, dipendenze e comportamento in caso di sovrascrittura
  • hosting di GitHub: GitHub Pages e repository privati
  • Server personalizzato: servire un registro dalla propria infrastruttura