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.jsonviene pubblicato dall’autore del blocco. Elenca i blocchi, i file che li compongono e unbaseUrlda cui scaricarli.blocks.jsonsi 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/:
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:
{
"$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 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:
{
"$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.baseUrldeve essere un URL assoluto. CLI lo convalida come URL e rifiuta i valori relativi. I file dei blocchi vengono sempre recuperati dabaseUrl, mai da una posizione relativa al punto in cui è stato caricatoregistry.json.dependenciesassegna nomi ai blocchi nello stesso registro. Aggiungendotabssi installa primatab-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 inblocks.json, che non deve necessariamente corrispondere.typeha solo valore informativo. Accettablockstudio,create-blockoppurewordpresse 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:
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
baseUrlinregistry.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:
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:
npx blockstudio init --yes
Created .../acme-theme/blocks.json
init --yes scrive un oggetto registries vuoto. Aggiungete il registro nello
spazio dei nomi che volete digitare nei comandi:
{
"$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:
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 cerca una sottostringa senza distinzione tra maiuscole e minuscole nei nomi, nei titoli e
nelle descrizioni:
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.
Visualizzate un’anteprima dell’installazione con --dry-run. La dipendenza è elencata per prima, perché
viene installata per prima:
npx blockstudio add acme/tabs --dry-run
Would install:
tab-item (2 files)
tabs (3 files)
Poi installate davvero:
npx blockstudio add acme/tabs
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:
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:
npx blockstudio add hero card
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:
npx blockstudio add tab-item
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:
npx blockstudio add acme/tab-item --dry-run
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:
npx blockstudio remove tabs --yes
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:
"baseUrl": "https://raw.githubusercontent.com/acme/acme-blocks/v1.0.0/blocks"
Poi eseguite il commit, create il tag e fate il push:
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:
{
"$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:
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".
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.
addcarica tutti i registri inblocks.jsonprima di risolvere qualsiasi elemento, quindi un registro irraggiungibile fa fallire il comando anche peracme/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,--yessceglie il primo nell’ordine diblocks.jsone un’esecuzione non interattiva termina conBlock "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
urleheaders. 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