Publier un registre de blocs sur GitHub
Une fois quelques blocs de qualité créés, vous voudrez aussi les utiliser dans votre prochain projet. Copier manuellement des dossiers entre thèmes fonctionne jusqu’à ce que les copies divergent et que plus personne ne sache dans quel thème se trouve la version corrigée. Emballer chaque bloc dans un paquet avec son propre système de compilation demande beaucoup de formalités pour un dossier qui contient un block.json et un modèle.
Un registre de blocs offre une solution intermédiaire. Il s’agit d’un fichier registry.json et d’un ensemble de dossiers de blocs servis sur un simple HTTP. Les utilisateurs exécutent une commande CLI, le code source du bloc est copié dans leur thème, et ils deviennent ensuite responsables de cette copie. Un dépôt GitHub suffit pour l’héberger, car GitHub sert chaque fichier d’un dépôt public à une URL brute URL.
Ce guide crée un registre appelé acme avec quatre blocs, le publie depuis le dépôt acme/acme-blocks, installe des blocs depuis celui-ci dans un thème et épingle une version au moyen d’une étiquette git.
Le paquet blockstudio sur npm est à la version 0.0.1. Cette version est un espace réservé : sa seule commande, add, affiche Adding block: <name> puis se termine sans rien récupérer. Les commandes et les résultats présentés dans ce guide proviennent du registre CLI dans le dépôt Blockstudio (packages/registry), c’est le CLI décrit dans la documentation du registre.
Comment les éléments s’articulent
Deux fichiers sont à connaître :
registry.jsonest publié par l’auteur du bloc. Il répertorie les blocs, les fichiers qui composent chacun d’eux et unbaseUrlpour les télécharger.blocks.jsonse trouve dans le thème ou l’extension de l’utilisateur. Il indique les registres à utiliser et le répertoire où installer les blocs.
Quand vous installez un bloc, CLI récupère chaque registre indiqué dans blocks.json, trouve le bloc, résout ses dépendances, télécharge chaque fichier répertorié depuis {baseUrl}/{block}/{file} et l’enregistre dans {directory}/{block}/{file}. Rien n’est transformé : les fichiers sur le disque sont exactement ceux du dépôt.
Étape 1 : structurer le dépôt
Créez un dépôt contenant un registry.json à la racine et un dossier par bloc sous 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
Le nom du dossier est le nom du bloc dans le registre et devient celui du dossier dans le thème de l’utilisateur. Faites-le correspondre exactement à la seconde partie du nom du bloc dans block.json (acme/hero se trouve dans hero/), afin de retrouver facilement le dossier installé.
Étape 2 : écrire les blocs
Chaque dossier contient un bloc Blockstudio ordinaire. Le bloc Hero comporte un seul champ :
{
"$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 suit le même modèle et ajoute un style.scss. tabs rend <InnerBlocks allowedBlocks='["acme/tab-item"]' />, et tab-item déclare "parent": ["acme/tabs"] ; tabs ne sert donc à rien sans tab-item. Le registre exprime cette relation à l’étape suivante.
Ces blocs ne présentent aucune particularité liée au registre. CLI copie les dossiers ; vous pouvez donc publier de la même façon un bloc créé avec @wordpress/create-block ou enregistré avec PHP simple.
Étape 3 : rédiger registry.json
registry.json répertorie tous les blocs et tous les fichiers que CLI doit télécharger :
{
"$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"]
}
]
}
Quelques règles déterminent si ce fichier fonctionne :
filesest une liste explicite. Le CLI télécharge exactement ces chemins et rien d’autre. Il n’y a pas de recherche par motif : un nouvel élément n’est inclus qu’une fois ajouté ici. Les chemins peuvent contenir des sous-répertoires, qui sont créés à l’installation.baseUrldoit être un URL absolu. Le CLI le valide en tant que URL et rejette les valeurs relatives. Les fichiers de blocs sont toujours récupérés depuisbaseUrl, jamais depuis un emplacement relatif à l’endroit oùregistry.jsona été chargé.dependenciesnomme les blocs du même registre. L’ajout detabsinstalle d’abordtab-item. Les dépendances manquantes ou circulaires interrompent l’installation et génèrent une erreur.nameest obligatoire, mais n’est pas affiché. Les commandes et la sortie utilisent la clé que le consommateur attribue au registre dansblocks.json, qui peut être différente.typeest à titre indicatif. Il accepteblockstudio,create-blockouwordpress, et ne change pas le fonctionnement de CLI.
Le CLI valide le fichier entier à chaque récupération et signale chaque champ en erreur. Une faute de frappe est ainsi détectée avant le téléchargement de tout fichier. La ligne $schema effectue les mêmes vérifications dans votre éditeur.
Étape 4 : publier via des URL brutes
Validez les modifications et poussez le dépôt vers GitHub. Chaque fichier d’un dépôt public est alors disponible à l’adresse suivante :
https://raw.githubusercontent.com/<owner>/<repo>/<ref>/<path>
<ref> correspond à une branche, une étiquette ou un SHA de commit. Pour ce registre, deux URL comptent :
- L’URL du registre URL que les consommateurs configurent :
https://raw.githubusercontent.com/acme/acme-blocks/main/registry.json - Le
baseUrldansregistry.json:https://raw.githubusercontent.com/acme/acme-blocks/main/blocks
Avec ce baseUrl, le index.php de hero est récupéré depuis
https://raw.githubusercontent.com/acme/acme-blocks/main/blocks/hero/index.php.
L’hôte brut renvoie le contenu du fichier au lieu de la page GitHub HTML, dont CLI a besoin. Une erreur dans le propriétaire, le dépôt ou la référence apparaît sous forme de 404 dès la première commande :
Registry returned 404 for https://raw.githubusercontent.com/acme/acme-blocks/main/registry.json
Étape 5 : installer les blocs dans un thème
À la racine du thème consommateur, créez blocks.json :
npx blockstudio init --yes
Created .../acme-theme/blocks.json
init --yes crée un objet registries vide. Ajoutez le registre sous l’espace de noms que vous souhaitez saisir dans les commandes :
{
"$schema": "https://blockstudio.dev/schema/blocks.json",
"directory": "blockstudio",
"registries": {
"acme": "https://raw.githubusercontent.com/acme/acme-blocks/main/registry.json"
}
}
Dans un terminal, exécutez init sans --yes pour répondre interactivement aux mêmes questions (répertoire des blocs, noms et URL des registres).
Vérifiez que le registre est bien trouvé :
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 recherche une sous-chaîne sans distinction de casse dans les noms, les titres et les descriptions :
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.
Prévisualisez une installation avec --dry-run. La dépendance est indiquée en premier, car elle est installée en premier :
npx blockstudio add acme/tabs --dry-run
Would install:
tab-item (2 files)
tabs (3 files)
Procédez ensuite à l’installation :
npx blockstudio add acme/tabs
Downloading acme/tabs...
Installed tab-item (2 files)
Installed tabs (3 files)
Les deux dossiers se trouvent maintenant dans le répertoire blockstudio du thème, exactement comme dans le dépôt :
blockstudio/tab-item/block.json
blockstudio/tab-item/index.php
blockstudio/tabs/block.json
blockstudio/tabs/index.php
blockstudio/tabs/style.scss
Vous pouvez omettre l’espace de noms lorsqu’un seul registre configuré contient le bloc, et transmettre plusieurs blocs à la fois :
npx blockstudio add hero card
Downloading acme/hero...
Installed hero (2 files)
Downloading acme/card...
Installed card (3 files)
Blockstudio détecte les nouveaux dossiers comme n’importe quel autre bloc du thème.
Mettre à jour les blocs installés
Les fichiers installés sont des copies. Aucune trace de la version installée n’est conservée, et CLI ne met jamais un bloc à jour de lui-même. Pour récupérer une version plus récente, ajoutez le bloc de nouveau. Sans terminal, ou dans l’intégration continue, la commande s’arrête si le dossier existe déjà :
npx blockstudio add tab-item
Block "tab-item" already exists at .../acme-theme/blockstudio/tab-item. Use --yes to overwrite.
Dans un terminal, CLI demande plutôt confirmation avant d’écraser les fichiers. --dry-run indique les dossiers qui seraient remplacés, et --yes les remplace :
npx blockstudio add acme/tab-item --dry-run
Would overwrite tab-item
Would install:
tab-item (2 files)
L’écrasement remplace les fichiers indiqués par la version du registre. Commitez donc vos modifications locales d’abord, puis vérifiez le résultat avec git diff.
Pour désinstaller un bloc, supprimez son dossier par son nom :
npx blockstudio remove tabs --yes
Removed tabs
remove prend le nom du dossier, et non namespace/block. Il ne supprime pas les dépendances : tab-item reste donc installé après la suppression de tabs.
Gestion des versions avec les références git
Le CLI n’a ni champ de version ni option de version. Ce qu’il récupère dépend entièrement des URL et, sur GitHub, la référence dans le URL correspond à la version. Un consommateur qui pointe vers main obtient ce que main contient au moment de l’installation.
Pour publier une version figée, le registry.json de l’étiquette doit également télécharger les fichiers depuis cette étiquette. Avant de créer l’étiquette, définissez baseUrl sur celle-ci :
"baseUrl": "https://raw.githubusercontent.com/acme/acme-blocks/v1.0.0/blocks"
Validez ensuite les modifications, créez l’étiquette et poussez-la :
git commit -am 'Release v1.0.0'
git tag v1.0.0
git push origin main v1.0.0
Ensuite, rétablissez baseUrl à main et commitez afin que la branche continue de fournir les fichiers à jour. Si vous omettez la première étape, un consommateur figé sur l’étiquette obtient la liste de blocs étiquetée, mais télécharge les fichiers depuis main.
Les consommateurs figent la version en utilisant l’étiquette dans l’URL de leur registre URL :
{
"$schema": "https://blockstudio.dev/schema/blocks.json",
"directory": "blockstudio",
"registries": {
"acme": "https://raw.githubusercontent.com/acme/acme-blocks/v1.0.0/registry.json"
}
}
Dans cet exemple, v1.0.0 a été étiqueté avant l’existence de tabs et de tab-item. Le registre figé ne propose donc que les deux blocs d’origine :
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".
Un SHA de commit fonctionne aussi dans l’URL du registre URL, mais un commit ne peut pas contenir son propre SHA dans baseUrl. Le figement par SHA fixe donc la liste des blocs, tandis que les fichiers proviennent toujours de la référence indiquée par le baseUrl de ce commit. Préférez donc les étiquettes pour les versions publiées.
Points à retenir
- Chaque registre est récupéré en premier.
addcharge tous les registres dansblocks.jsonavant de résoudre quoi que ce soit ; un seul registre inaccessible fait donc échouer la commande, même pouracme/hero. Supprimez les registres que vous n’utilisez plus. - Les noms ambigus nécessitent un espace de noms. Si deux registres contiennent tous deux
hero, une session de terminal demande lequel utiliser,--yeschoisit le premier selon l’ordreblocks.json, et une exécution non interactive se termine avecBlock "hero" found in multiple registries: acme, starter. Specify one: blockstudio add acme/hero. - Les dépôts privés nécessitent des en-têtes. Utilisez la forme objet d’une entrée de registre avec
urletheaders. Les valeurs d’en-tête acceptent des espaces réservés${VAR}lus depuis l’environnement, et le CLI envoie les en-têtes lors de la récupération du registre et de chaque téléchargement de fichier. Consultez l’hébergement GitHub pour configurer le jeton.
Étapes suivantes
- Présentation du registre : ce qu’est le registre et comment fonctionne CLI
- registry.json : tous les champs du manifeste
- blocks.json : configuration du consommateur, authentification et détection de la configuration
- add : résolution des espaces de noms, dépendances et comportement lors de l’écrasement
- Hébergement GitHub : GitHub Pages et dépôts privés
- Serveur personnalisé : héberger un registre sur votre propre infrastructure