Saltar al contenido

registry.json

registry.json es un archivo JSON alojado en un URL. Enumera todos los bloques disponibles en un registro, sus metadatos, dependencias y manifiestos de archivos.

Esquema

JSON
{
  "$schema": "https://blockstudio.dev/schema/registry.json",
  "name": "ui",
  "description": "Core UI blocks for Blockstudio projects.",
  "baseUrl": "https://raw.githubusercontent.com/acme/blocks/main/blocks",
  "blocks": [
    {
      "name": "tabs",
      "title": "Tabs",
      "description": "Tabbed content with accessible keyboard navigation.",
      "category": "layout",
      "type": "blockstudio",
      "dependencies": ["tab-item"],
      "files": [
        "block.json",
        "index.php",
        "style.scss"
      ]
    }
  ]
}

Campos de nivel superior

name

Obligatorio. Identificador del registro. CLI lo valida, pero no lo muestra: los comandos y la salida usan la clave que el consumidor eligió para el registro en blocks.json.

description

Opcional. Descripción breve del contenido de este registro.

baseUrl

Obligatorio. URL base para descargar archivos de bloques. Debe ser un URL válido.

Los archivos se obtienen combinando el URL base, el nombre del bloque y la ruta del archivo: {baseUrl}/{block.name}/{file}.

Por ejemplo, si baseUrl tiene el valor https://raw.githubusercontent.com/acme/blocks/main/blocks y un bloque llamado tabs contiene el archivo index.php, CLI obtiene:

Código
https://raw.githubusercontent.com/acme/blocks/main/blocks/tabs/index.php

Campos de bloque

name

Obligatorio. Nombre de la carpeta del bloque. Este identificador se usa en los comandos CLI y se convierte en el nombre de la carpeta en el disco.

title

Opcional. Nombre legible para las personas que se muestra en list y en la salida de search.

description

Opcional. Descripción de una línea que se muestra en los resultados de search.

category

Opcional. Etiqueta de agrupación para la salida de list.

type

Opcional. Uno de estos valores: blockstudio, create-block o wordpress.

Solo tiene fines informativos. CLI no cambia su comportamiento según el tipo de bloque. Siempre descarga y copia los archivos indicados en files.

dependencies

Opcional. Matriz de otros nombres de bloques del mismo registro que deben instalarse junto con este bloque.

Cuando un usuario añade un bloque con dependencias, CLI resuelve todo el árbol de dependencias e instala todo en el orden correcto. Las dependencias circulares se detectan y se rechazan.

Las dependencias deben existir en el mismo registro. No se admiten dependencias entre registros.

files

Obligatorio. Matriz de rutas de archivos relativas a la carpeta del bloque. Se requiere al menos un archivo.

Son los archivos exactos que CLI descarga y guarda en el disco. Las rutas pueden incluir subdirectorios:

JSON
{
  "files": [
    "block.json",
    "index.php",
    "style.scss",
    "src/components/tabs.tsx",
    "src/styles/tabs.css"
  ]
}

Resolución de archivos

Para cada archivo del manifiesto de un bloque, CLI construye una URL de descarga:

Código
{baseUrl}/{block.name}/{file}

Y lo guarda en:

Código
{directory}/{block.name}/{file}

Se conserva la estructura de directorios dentro de la carpeta del bloque. Si una ruta de archivo contiene subdirectorios, estos se crean automáticamente.

Los archivos siempre se obtienen de baseUrl dentro de registry.json, no de una ubicación relativa al URL del registro en blocks.json.

Validación

CLI valida registry.json con un esquema Zod en cada consulta. Los registros no válidos generan mensajes de error claros que indican los campos que no superaron la validación.

Los campos obligatorios que faltan, las matrices blocks o files vacías, las URL no válidas y los valores type desconocidos se detectan antes de descargar archivos.