Pular para o conteúdo

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

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

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

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

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

E o grava em:

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