registry.json
registry.json é um arquivo JSON hospedado em um URL. Ele lista todos os blocos disponíveis em um registro, seus metadados, dependências e manifestos de arquivos.
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 nível superior
name
Obrigatório. O identificador do registro. CLI o valida, mas não o exibe: os comandos e a saída usam a chave escolhida pelo consumidor para o registro em blocks.json.
description
Opcional. Uma breve descrição do conteúdo deste registro.
baseUrl
Obrigatório. O URL base para baixar os arquivos dos blocos. Deve ser um URL válido.
Os arquivos são obtidos combinando o URL base, o nome do bloco e o caminho do arquivo: {baseUrl}/{block.name}/{file}.
Por exemplo, com baseUrl definido como https://raw.githubusercontent.com/acme/blocks/main/blocks e um bloco chamado tabs com o arquivo index.php, CLI consulta:
https://raw.githubusercontent.com/acme/blocks/main/blocks/tabs/index.php
Campos dos blocos
name
Obrigatório. O nome da pasta do bloco. Esse identificador é usado nos comandos CLI e se torna o nome da pasta no disco.
title
Opcional. Nome legível exibido na saída de list e search.
description
Opcional. Descrição de uma linha exibida nos resultados de search.
category
Opcional. Rótulo de agrupamento para a saída de list.
type
Opcional. Um entre blockstudio, create-block ou wordpress.
Apenas informativo. CLI não altera o comportamento conforme o tipo do bloco. Sempre baixa e copia os arquivos listados em files.
dependencies
Opcional. Uma lista de outros nomes de blocos do mesmo registro que devem ser instalados junto com este bloco.
Quando um usuário adiciona um bloco com dependências, CLI resolve toda a árvore de dependências e instala tudo na ordem correta. Dependências circulares são detectadas e rejeitadas.
As dependências devem existir no mesmo registro. Não há suporte para dependências entre registros.
files
Obrigatório. Uma lista de caminhos de arquivos relativos à pasta do bloco. É necessário ter pelo menos um arquivo.
Estes são os arquivos exatos que CLI baixa e grava no disco. Os caminhos podem incluir subdiretórios:
{
"files": [
"block.json",
"index.php",
"style.scss",
"src/components/tabs.tsx",
"src/styles/tabs.css"
]
}
Resolução de arquivos
Para cada arquivo no manifesto de um bloco, CLI monta um URL de download:
{baseUrl}/{block.name}/{file}
E o grava em:
{directory}/{block.name}/{file}
A estrutura de diretórios dentro da pasta do bloco é preservada. Se um caminho de arquivo contiver subdiretórios, eles serão criados automaticamente.
Os arquivos são sempre obtidos de baseUrl dentro de registry.json, e não de um local relativo ao URL do registro em blocks.json.
Validação
CLI valida registry.json em relação a um esquema Zod em cada consulta. Registros inválidos geram mensagens de erro claras, indicando os campos específicos que falharam na validação.
Campos obrigatórios ausentes, arrays blocks ou files vazios, URLs inválidos e valores type desconhecidos são detectados antes do download de qualquer arquivo.