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
{
"$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) :
{
"registries": {
"ui": "https://example.com/registry.json"
}
}
Format objet (registres avec authentification) :
{
"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
{
"registries": {
"private": {
"url": "https://api.example.com/registry.json",
"headers": {
"Authorization": "Bearer ${REGISTRY_TOKEN}"
}
}
}
}
Authentification de base
{
"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 :
{
"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 :
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.
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
{
"$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é
{
"$schema": "https://blockstudio.dev/schema/blocks.json",
"directory": "src/blocks",
"registries": {
"starter": "https://raw.githubusercontent.com/acme/blocks/main/registry.json"
}
}