Pular para o conteúdo

blocks.json

blocks.json fica na raiz do seu tema ou plugin. Ele informa ao CLI onde instalar blocos e em quais registros pesquisar.

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. Aponta para o esquema JSON, usado para preenchimento automático e validação no editor.

directory

Obrigatório. Caminho relativo a blocks.json onde os blocos são instalados.

Cada bloco tem sua própria subpasta neste diretório. Se directory for blockstudio e você adicionar hero, os arquivos serão gravados em blockstudio/hero/.

registries

Obrigatório. Um objeto que mapeia nomes de namespace para referências de registro.

A chave é o namespace usado nos comandos CLI (npx blockstudio add ui/hero). O valor pode ser uma string URL ou um objeto com url e, opcionalmente, headers.

Formato de string (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}"
      }
    }
  }
}

Os dois formatos podem ser combinados na mesma configuração. Você pode configurar quantos registros quiser. Ao adicionar um bloco sem namespace, CLI pesquisa em todos eles.

Autenticação

Registros que exigem autenticação usam o formato de objeto com headers. CLI envia esses cabeçalhos em cada solicitação a esse registro, tanto na consulta de registry.json quanto nos downloads de arquivos individuais.

Token de portador

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

Autenticação básica

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

Cabeçalhos personalizados

Qualquer cabeçalho pode ser adicionado. Isso funciona para chaves API, identificadores de organização ou outros valores esperados pelo servidor do seu registro:

JSON
{
  "registries": {
    "internal": {
      "url": "https://blocks.internal.company.com/registry.json",
      "headers": {
        "X-API-Key": "${BLOCKS_API_KEY}",
        "X-Org-ID": "acme"
      }
    }
  }
}

Variáveis de ambiente

Os valores dos cabeçalhos aceitam a sintaxe ${VAR_NAME} para ler variáveis de ambiente. Assim, os tokens ficam fora do controle de versão.

CLI resolve as variáveis de ambiente durante a execução. Se uma variável referenciada não estiver definida, CLI encerra com um erro que identifica a variável ausente e o cabeçalho em que ela foi usada.

Defina a variável no shell ou no ambiente de CI. CLI lê apenas o ambiente do processo; não carrega arquivos .env por conta própria:

Shell
export REGISTRY_TOKEN=ghp_abc123
npx blockstudio add private/hero

Valores estáticos de cabeçalho (sem ${...}) são transmitidos sem alterações.

Localização da configuração

CLI sobe a partir do diretório de trabalho atual em busca de blocks.json. Assim, você pode executar comandos a partir de qualquer subdiretório do projeto.

Código
my-theme/
  blocks.json        <- found here
  blockstudio/
    hero/
  templates/
    page.php          <- running `npx blockstudio add` here still works

Se blocks.json não for encontrado, CLI informa que você deve executar npx blockstudio init.

Exemplo: tema com dois 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"
  }
}

Exemplo: plugin com diretório personalizado

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