blocks.json
blocks.json se encuentra en la raíz de tu tema o plugin. Indica a CLI dónde instalar los bloques y en qué registros buscar.
Esquema
{
"$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"
}
}
Campos
$schema
Opcional. Apunta al esquema JSON para el autocompletado y la validación del editor.
directory
Obligatorio. Ruta relativa desde blocks.json donde se instalan los bloques.
Cada bloque tiene su propia subcarpeta dentro de este directorio. Si directory es blockstudio y añades hero, los archivos se guardan en blockstudio/hero/.
registries
Obligatorio. Objeto que asigna nombres de espacios de nombres a referencias de registros.
La clave es el espacio de nombres usado en los comandos CLI (npx blockstudio add ui/hero).
El valor puede ser una cadena URL o un objeto con url y headers opcional.
Formato de cadena (registros públicos):
{
"registries": {
"ui": "https://example.com/registry.json"
}
}
Formato de objeto (registros autenticados):
{
"registries": {
"private": {
"url": "https://private.example.com/registry.json",
"headers": {
"Authorization": "Bearer ${REGISTRY_TOKEN}"
}
}
}
}
Puedes combinar ambos formatos en la misma configuración. Puedes configurar tantos registros como quieras. Al añadir un bloque sin espacio de nombres, CLI busca en todos ellos.
Autenticación
Los registros que requieren autenticación usan el formato de objeto con headers.
CLI envía estos encabezados en cada solicitud a ese registro, incluidas tanto la obtención de registry.json como las descargas de archivos individuales.
Token Bearer
{
"registries": {
"private": {
"url": "https://api.example.com/registry.json",
"headers": {
"Authorization": "Bearer ${REGISTRY_TOKEN}"
}
}
}
}
Autenticación básica
{
"registries": {
"private": {
"url": "https://api.example.com/registry.json",
"headers": {
"Authorization": "Basic ${REGISTRY_CREDENTIALS}"
}
}
}
}
Encabezados personalizados
Se puede añadir cualquier encabezado. Esto sirve para claves API, identificadores de organizaciones o cualquier otro valor que espere el servidor del registro:
{
"registries": {
"internal": {
"url": "https://blocks.internal.company.com/registry.json",
"headers": {
"X-API-Key": "${BLOCKS_API_KEY}",
"X-Org-ID": "acme"
}
}
}
}
Variables de entorno
Los valores de encabezado admiten la sintaxis ${VAR_NAME} para leer variables de entorno.
Así, los tokens no se incluyen en el control de versiones.
CLI resuelve las variables de entorno en tiempo de ejecución. Si una variable mencionada no está definida, CLI termina con un error que indica el nombre de la variable que falta y el encabezado en el que se usó.
Define la variable en tu shell o entorno de CI. CLI solo lee el entorno del proceso; no carga archivos .env por sí mismo:
export REGISTRY_TOKEN=ghp_abc123
npx blockstudio add private/hero
Los valores estáticos de encabezado (sin ${...}) se pasan tal cual.
Detección de configuración
CLI sube desde el directorio de trabajo actual buscando blocks.json.
Así puedes ejecutar comandos desde cualquier subdirectorio del proyecto.
my-theme/
blocks.json <- found here
blockstudio/
hero/
templates/
page.php <- running `npx blockstudio add` here still works
Si no se encuentra blocks.json, CLI te indica que ejecutes npx blockstudio init.
Ejemplo: tema con dos registros
{
"$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"
}
}
Ejemplo: plugin con directorio personalizado
{
"$schema": "https://blockstudio.dev/schema/blocks.json",
"directory": "src/blocks",
"registries": {
"starter": "https://raw.githubusercontent.com/acme/blocks/main/registry.json"
}
}