Vai al contenuto

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

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

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

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

Formato oggetto (registri autenticati):

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

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

Autenticazione di base

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

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

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

Codice
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

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

Esempio: plugin con directory personalizzata

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