Saltar al contenido

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

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

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

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

Formato de objeto (registros autenticados):

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

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

Autenticación básica

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

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

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

Código
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

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

Ejemplo: plugin con directorio personalizado

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