Aller au contenu

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.json est publié par l’auteur du bloc. Il répertorie les blocs, les fichiers qui composent chacun d’eux et un baseUrl pour les télécharger.
  • blocks.json se 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/ :

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

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 :

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

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

Quelques règles déterminent si ce fichier fonctionne :

  • files est 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.
  • baseUrl doit ê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 depuis baseUrl, jamais depuis un emplacement relatif à l’endroit où registry.json a été chargé.
  • dependencies nomme les blocs du même registre. L’ajout de tabs installe d’abord tab-item. Les dépendances manquantes ou circulaires interrompent l’installation et génèrent une erreur.
  • name est obligatoire, mais n’est pas affiché. Les commandes et la sortie utilisent la clé que le consommateur attribue au registre dans blocks.json, qui peut être différente.
  • type est à titre indicatif. Il accepte blockstudio, create-block ou wordpress, 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 :

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

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

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

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

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 recherche une sous-chaîne sans distinction de casse dans les noms, les titres et les descriptions :

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.

Prévisualisez une installation avec --dry-run. La dépendance est indiquée en premier, car elle est installée en premier :

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

Procédez ensuite à l’installation :

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

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

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

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

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

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

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

Validez ensuite les modifications, créez l’étiquette et poussez-la :

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

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

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".

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. add charge tous les registres dans blocks.json avant de résoudre quoi que ce soit ; un seul registre inaccessible fait donc échouer la commande, même pour acme/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, --yes choisit le premier selon l’ordre blocks.json, et une exécution non interactive se termine avec Block "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 url et headers. 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