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
{
"$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:
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:
{
"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:
{baseUrl}/{block.name}/{file}
Y lo guarda en:
{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.