Aller au contenu

registry.json

registry.json est un fichier JSON hébergé sur un serveur URL. Il répertorie tous les blocs disponibles dans un registre, leurs métadonnées, leurs dépendances et leurs manifestes de fichiers.

Schéma

JSON
{
  "$schema": "https://blockstudio.dev/schema/registry.json",
  "name": "ui",
  "description": "Core UI blocks for Blockstudio projects.",
  "baseUrl": "https://raw.githubusercontent.com/acme/blocks/main/blocks",
  "blocks": [
    {
      "name": "tabs",
      "title": "Tabs",
      "description": "Tabbed content with accessible keyboard navigation.",
      "category": "layout",
      "type": "blockstudio",
      "dependencies": ["tab-item"],
      "files": [
        "block.json",
        "index.php",
        "style.scss"
      ]
    }
  ]
}

Champs de premier niveau

name

Obligatoire. Identifiant du registre. CLI le valide, mais ne l’affiche pas : les commandes et leur sortie utilisent la clé choisie par le consommateur pour le registre dans blocks.json.

description

Facultatif. Brève description du contenu de ce registre.

baseUrl

Obligatoire. URL de base pour télécharger les fichiers de blocs. Doit être un URL valide.

Les fichiers sont récupérés en combinant le URL de base, le nom du bloc et le chemin du fichier : {baseUrl}/{block.name}/{file}.

Par exemple, si baseUrl vaut https://raw.githubusercontent.com/acme/blocks/main/blocks et qu’un bloc nommé tabs contient le fichier index.php, CLI récupère :

Code
https://raw.githubusercontent.com/acme/blocks/main/blocks/tabs/index.php

Champs de bloc

name

Obligatoire. Nom du dossier du bloc. Cet identifiant est utilisé dans les commandes CLI et devient le nom du dossier sur le disque.

title

Facultatif. Nom lisible affiché dans list et la sortie search.

description

Facultatif. Description d’une ligne affichée dans les résultats search.

category

Facultatif. Libellé de regroupement pour la sortie list.

type

Facultatif. Une valeur parmi blockstudio, create-block ou wordpress.

Cette information est uniquement indicative. CLI ne modifie pas son comportement selon le type de bloc. Il télécharge et copie toujours les fichiers indiqués dans files.

dependencies

Facultatif. Tableau d’autres noms de blocs du même registre qui doivent être installés avec ce bloc.

Lorsqu’un utilisateur ajoute un bloc avec des dépendances, CLI résout l’arborescence complète des dépendances et installe tous les éléments dans le bon ordre. Les dépendances circulaires sont détectées et rejetées.

Les dépendances doivent exister dans le même registre. Les dépendances entre registres ne sont pas prises en charge.

files

Obligatoire. Tableau de chemins de fichiers relatifs au dossier du bloc. Au moins un fichier est requis.

Il s’agit des fichiers exacts que CLI télécharge et écrit sur le disque. Les chemins peuvent inclure des sous-répertoires :

JSON
{
  "files": [
    "block.json",
    "index.php",
    "style.scss",
    "src/components/tabs.tsx",
    "src/styles/tabs.css"
  ]
}

Résolution des fichiers

Pour chaque fichier du manifeste d’un bloc, CLI construit une URL de téléchargement :

Code
{baseUrl}/{block.name}/{file}

Et l’écrit à l’emplacement suivant :

Code
{directory}/{block.name}/{file}

La structure des répertoires à l’intérieur du dossier du bloc est conservée. Si un chemin de fichier contient des sous-répertoires, ceux-ci sont créés automatiquement.

Les fichiers sont toujours récupérés depuis le baseUrl dans registry.json, et non depuis un emplacement relatif au URL du registre dans blocks.json.

Validation

À chaque récupération, CLI valide registry.json selon un schéma Zod. Les registres invalides produisent des messages d’erreur explicites indiquant les champs concernés.

Les champs obligatoires manquants, les tableaux blocks ou files vides, les URL invalides et les valeurs type inconnues sont détectés avant le téléchargement de tout fichier.