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
{
"$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):
{
"registries": {
"ui": "https://example.com/registry.json"
}
}
Formato de objeto (registros autenticados):
{
"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
{
"registries": {
"private": {
"url": "https://api.example.com/registry.json",
"headers": {
"Authorization": "Bearer ${REGISTRY_TOKEN}"
}
}
}
}
Autenticação básica
{
"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:
{
"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:
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.
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
{
"$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
{
"$schema": "https://blockstudio.dev/schema/blocks.json",
"directory": "src/blocks",
"registries": {
"starter": "https://raw.githubusercontent.com/acme/blocks/main/registry.json"
}
}