Aller au contenu

blocks.json

blocks.json se trouve à la racine de votre thème ou extension. Il indique à CLI où installer les blocs et dans quels registres effectuer les recherches.

Schéma

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

Champs

$schema

Facultatif. Renvoie au schéma JSON pour la saisie semi-automatique et la validation dans l’éditeur.

directory

Obligatoire. Chemin relatif à partir de blocks.json où les blocs sont installés.

Chaque bloc dispose de son propre sous-dossier dans ce répertoire. Si directory vaut blockstudio et que vous ajoutez hero, les fichiers sont placés dans blockstudio/hero/.

registries

Obligatoire. Objet associant des noms d’espaces de noms à des références de registre.

La clé est l’espace de noms utilisé dans les commandes CLI (npx blockstudio add ui/hero). La valeur est une chaîne URL ou un objet avec url et headers facultatif.

Format chaîne (registres publics) :

JSON
{
  "registries": {
    "ui": "https://example.com/registry.json"
  }
}

Format objet (registres avec authentification) :

JSON
{
  "registries": {
    "private": {
      "url": "https://private.example.com/registry.json",
      "headers": {
        "Authorization": "Bearer ${REGISTRY_TOKEN}"
      }
    }
  }
}

Les deux formats peuvent être mélangés dans la même configuration. Vous pouvez configurer autant de registres que vous le souhaitez. Lorsque vous ajoutez un bloc sans espace de noms, CLI les consulte tous.

Authentification

Les registres qui nécessitent une authentification utilisent le format objet avec headers. CLI envoie ces en-têtes à chaque requête adressée à ce registre, y compris lors de la récupération de registry.json et du téléchargement de chaque fichier.

Jeton Bearer

JSON
{
  "registries": {
    "private": {
      "url": "https://api.example.com/registry.json",
      "headers": {
        "Authorization": "Bearer ${REGISTRY_TOKEN}"
      }
    }
  }
}

Authentification de base

JSON
{
  "registries": {
    "private": {
      "url": "https://api.example.com/registry.json",
      "headers": {
        "Authorization": "Basic ${REGISTRY_CREDENTIALS}"
      }
    }
  }
}

En-têtes personnalisés

Vous pouvez ajouter n’importe quel en-tête. Cela convient aux clés API, aux identifiants d’organisation ou à tout autre élément attendu par votre serveur de registre :

JSON
{
  "registries": {
    "internal": {
      "url": "https://blocks.internal.company.com/registry.json",
      "headers": {
        "X-API-Key": "${BLOCKS_API_KEY}",
        "X-Org-ID": "acme"
      }
    }
  }
}

Variables d’environnement

Les valeurs des en-têtes acceptent la syntaxe ${VAR_NAME} pour lire des variables d’environnement. Cela permet de ne pas inclure les jetons dans le contrôle de version.

CLI résout les variables d’environnement à l’exécution. Si une variable référencée n’est pas définie, CLI se termine avec une erreur indiquant le nom de la variable manquante et l’en-tête dans lequel elle est utilisée.

Définissez la variable dans votre shell ou votre environnement CI. CLI lit uniquement l’environnement du processus ; il ne charge pas les fichiers .env de lui-même :

Shell
export REGISTRY_TOKEN=ghp_abc123
npx blockstudio add private/hero

Les valeurs d’en-tête statiques (sans ${...}) sont transmises telles quelles.

Découverte de la configuration

CLI remonte depuis le répertoire de travail courant à la recherche de blocks.json. Vous pouvez ainsi exécuter des commandes depuis n’importe quel sous-répertoire de votre projet.

Code
my-theme/
  blocks.json        <- found here
  blockstudio/
    hero/
  templates/
    page.php          <- running `npx blockstudio add` here still works

Si aucun blocks.json n’est trouvé, CLI vous indique d’exécuter npx blockstudio init.

Exemple : thème avec deux registres

JSON
{
  "$schema": "https://blockstudio.dev/schema/blocks.json",
  "directory": "blockstudio",
  "registries": {
    "ui": "https://blocks.mycompany.com/ui/registry.json",
    "internal": "https://blocks.mycompany.com/internal/registry.json"
  }
}

Exemple : extension avec répertoire personnalisé

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