blocks.json
blocks.json si trova nella radice del tema o del plugin. Indica a CLI dove installare i blocchi e in quali registri cercare.
Schema
{
"$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"
}
}
Campi
$schema
Facoltativo. Indica lo Schema JSON per il completamento automatico e la convalida nell’editor.
directory
Obbligatorio. Percorso relativo a blocks.json in cui vengono installati i blocchi.
Ogni blocco ha una propria sottocartella in questa directory. Se directory è blockstudio e aggiungi hero, i file vengono salvati in blockstudio/hero/.
registries
Obbligatorio. Oggetto che associa i nomi dei namespace ai riferimenti dei registri.
La chiave è il namespace usato nei comandi CLI (npx blockstudio add ui/hero). Il valore è una stringa URL oppure un oggetto con url e headers facoltativo.
Formato stringa (registri pubblici):
{
"registries": {
"ui": "https://example.com/registry.json"
}
}
Formato oggetto (registri autenticati):
{
"registries": {
"private": {
"url": "https://private.example.com/registry.json",
"headers": {
"Authorization": "Bearer ${REGISTRY_TOKEN}"
}
}
}
}
Puoi combinare entrambi i formati nella stessa configurazione e configurare tutti i registri che vuoi. Quando aggiungi un blocco senza namespace, CLI cerca in tutti i registri.
Autenticazione
Per i registri che richiedono l’autenticazione, usa il formato oggetto con headers. CLI invia queste intestazioni a ogni richiesta al registro, sia per recuperare registry.json sia per scaricare i singoli file.
Token Bearer
{
"registries": {
"private": {
"url": "https://api.example.com/registry.json",
"headers": {
"Authorization": "Bearer ${REGISTRY_TOKEN}"
}
}
}
}
Autenticazione di base
{
"registries": {
"private": {
"url": "https://api.example.com/registry.json",
"headers": {
"Authorization": "Basic ${REGISTRY_CREDENTIALS}"
}
}
}
}
Intestazioni personalizzate
Puoi aggiungere qualsiasi intestazione. È utile per chiavi API, identificatori dell’organizzazione o altri valori previsti dal server del registro:
{
"registries": {
"internal": {
"url": "https://blocks.internal.company.com/registry.json",
"headers": {
"X-API-Key": "${BLOCKS_API_KEY}",
"X-Org-ID": "acme"
}
}
}
}
Variabili d’ambiente
I valori delle intestazioni supportano la sintassi ${VAR_NAME} per leggere le variabili d’ambiente. In questo modo, i token non vengono salvati nel controllo di versione.
CLI risolve le variabili d’ambiente durante l’esecuzione. Se una variabile indicata non è impostata, CLI termina con un errore che specifica la variabile mancante e l’intestazione in cui è stata usata.
Imposta la variabile nella shell o nell’ambiente CI. CLI legge solo le variabili d’ambiente del processo e non carica autonomamente i file .env:
export REGISTRY_TOKEN=ghp_abc123
npx blockstudio add private/hero
I valori statici delle intestazioni (senza ${...}) vengono passati così come sono.
Individuazione della configurazione
CLI risale dalla directory di lavoro corrente alla ricerca di blocks.json. Puoi quindi eseguire i comandi da qualsiasi sottodirectory del progetto.
my-theme/
blocks.json <- found here
blockstudio/
hero/
templates/
page.php <- running `npx blockstudio add` here still works
Se non viene trovato blocks.json, CLI ti indica di eseguire npx blockstudio init.
Esempio: tema con due registri
{
"$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"
}
}
Esempio: plugin con directory personalizzata
{
"$schema": "https://blockstudio.dev/schema/blocks.json",
"directory": "src/blocks",
"registries": {
"starter": "https://raw.githubusercontent.com/acme/blocks/main/registry.json"
}
}