Publicando um registro de blocos no GitHub
Depois de criar alguns bons blocos, você vai querer usá-los também no próximo projeto. Copiar pastas manualmente entre temas funciona até que as cópias se distanciem e ninguém mais se lembre de qual tema tem a versão corrigida. Empacotar cada bloco com seu próprio processo de build dá muito trabalho para uma pasta que contém um block.json e um template.
Um registro de blocos fica entre essas opções. Ele é um arquivo registry.json e um conjunto de pastas de blocos, disponibilizados por HTTP simples. Os consumidores executam um comando CLI, o código-fonte do bloco é copiado para o tema e, a partir daí, eles passam a ser responsáveis por essa cópia. Um repositório GitHub basta para hospedar um, pois GitHub disponibiliza todos os arquivos de um repositório público em uma URL bruta.
Este guia cria um registro chamado acme com quatro blocos, publica-o a partir do repositório acme/acme-blocks, instala blocos dele em um tema e fixa uma versão por meio de uma tag git.
O pacote blockstudio em npm está na versão 0.0.1. Essa versão é um espaço reservado: seu único comando, add, imprime Adding block: <name> e termina sem buscar nada. Os comandos e a saída deste guia vêm do registro CLI no repositório Blockstudio (packages/registry), que é o CLI descrito na documentação do Registro.
Como as peças se encaixam
Há dois arquivos que você precisa conhecer:
registry.jsoné publicado pelo autor do bloco. Ele lista os blocos, os arquivos que compõem cada bloco e umbaseUrlde onde baixá-los.blocks.jsonfica no tema ou plugin do consumidor. Ele especifica quais registros usar e o diretório de instalação dos blocos.
Ao instalar um bloco, o CLI busca cada registro em blocks.json, encontra o bloco, resolve suas dependências, baixa cada arquivo listado de {baseUrl}/{block}/{file} e o grava em {directory}/{block}/{file}. Ele não transforma nada; portanto, os arquivos no disco são exatamente iguais aos do repositório.
Etapa 1: Estruture o repositório
Crie um repositório com um registry.json na raiz e uma pasta para cada bloco em blocks/:
acme-blocks/
registry.json
blocks/
hero/
block.json
index.php
card/
block.json
index.php
style.scss
tabs/
block.json
index.php
style.scss
tab-item/
block.json
index.php
O nome da pasta é o nome do bloco no registro e se torna o nome da pasta no tema do consumidor. Mantenha-o idêntico à segunda parte do nome do bloco em block.json (acme/hero fica em hero/), para facilitar a identificação da pasta instalada.
Etapa 2: Escreva os blocos
Cada pasta é um bloco Blockstudio comum. O bloco hero tem um campo:
{
"$schema": "https://blockstudio.dev/schema/block",
"apiVersion": 3,
"name": "acme/hero",
"title": "Hero",
"category": "design",
"blockstudio": {
"attributes": [
{
"id": "heading",
"type": "text",
"label": "Heading",
"default": "Build faster"
}
]
}
}
<section useBlockProps class="acme-hero">
<h1><?php echo esc_html( $a['heading'] ); ?></h1>
</section>
card segue o mesmo padrão e adiciona um style.scss. tabs renderiza <InnerBlocks allowedBlocks='["acme/tab-item"]' />, e tab-item declara "parent": ["acme/tabs"]; por isso, tabs não é útil sem tab-item. O registro expressa essa relação na próxima etapa.
Não há nada específico do registro nesses blocos. O CLI copia pastas, então um bloco criado com @wordpress/create-block ou registrado com PHP simples pode ser publicado da mesma maneira.
Etapa 3: Escreva registry.json
registry.json lista todos os blocos e arquivos que o CLI deve baixar:
{
"$schema": "https://blockstudio.dev/schema/registry.json",
"name": "acme",
"description": "Acme block library.",
"baseUrl": "https://raw.githubusercontent.com/acme/acme-blocks/main/blocks",
"blocks": [
{
"name": "hero",
"title": "Hero",
"description": "Full-width hero section with a heading.",
"category": "layout",
"type": "blockstudio",
"files": ["block.json", "index.php"]
},
{
"name": "card",
"title": "Card",
"description": "Content card with a title.",
"category": "components",
"type": "blockstudio",
"files": ["block.json", "index.php", "style.scss"]
},
{
"name": "tabs",
"title": "Tabs",
"description": "Tabbed content with keyboard navigation.",
"category": "layout",
"type": "blockstudio",
"dependencies": ["tab-item"],
"files": ["block.json", "index.php", "style.scss"]
},
{
"name": "tab-item",
"title": "Tab Item",
"description": "Single tab panel used inside Tabs.",
"category": "layout",
"type": "blockstudio",
"files": ["block.json", "index.php"]
}
]
}
Algumas regras determinam se este arquivo funciona:
filesé uma lista explícita. CLI baixa exatamente estes caminhos e nada mais. Não há expansão de curingas, então um novo recurso só é incluído quando você o adiciona aqui. Os caminhos podem conter subdiretórios, que são criados durante a instalação.baseUrlprecisa ser um URL absoluto. CLI o valida como URL e rejeita valores relativos. Os arquivos de bloco são sempre obtidos debaseUrl, nunca de um local relativo a onderegistry.jsonfoi carregado.dependenciesnomeia blocos no mesmo registro. Adicionartabsinstalatab-itemprimeiro. Dependências ausentes ou circulares interrompem a instalação com um erro.nameé obrigatório, mas não é exibido. Os comandos e a saída usam a chave que o consumidor fornece ao registro emblocks.json, que não precisa corresponder.typeé informativo. Aceitablockstudio,create-blockouwordpresse não altera o funcionamento de CLI.
CLI valida o arquivo inteiro a cada busca e informa cada campo com falha,
para que um erro de digitação apareça antes de qualquer download. A linha $schema oferece
as mesmas verificações no editor.
Etapa 4: Publique por meio de URLs brutas
Confirme e envie o repositório para GitHub. Cada arquivo em um repositório público fica então disponível em:
https://raw.githubusercontent.com/<owner>/<repo>/<ref>/<path>
<ref> é uma branch, uma tag ou um SHA de commit. Para este registro, há duas
URLs importantes:
- O URL que os consumidores configuram:
https://raw.githubusercontent.com/acme/acme-blocks/main/registry.json - O
baseUrlemregistry.json:https://raw.githubusercontent.com/acme/acme-blocks/main/blocks
Com esse baseUrl, o index.php de hero é obtido de
https://raw.githubusercontent.com/acme/acme-blocks/main/blocks/hero/index.php.
O host bruto retorna o conteúdo do arquivo em vez da página GitHub HTML, que é o que
CLI precisa. Um proprietário, repositório ou ref incorreto aparece como 404 no
primeiro comando:
Registry returned 404 for https://raw.githubusercontent.com/acme/acme-blocks/main/registry.json
Etapa 5: Instale blocos em um tema
Na raiz do tema que consumirá os blocos, crie blocks.json:
npx blockstudio init --yes
Created .../acme-theme/blocks.json
init --yes grava um objeto registries vazio. Adicione o registro sob o
namespace que você quer digitar nos comandos:
{
"$schema": "https://blockstudio.dev/schema/blocks.json",
"directory": "blockstudio",
"registries": {
"acme": "https://raw.githubusercontent.com/acme/acme-blocks/main/registry.json"
}
}
Execute init sem --yes em um terminal para responder interativamente às mesmas perguntas
(diretório do bloco, nomes e URLs dos registros).
Verifique se o registro é resolvido:
npx blockstudio list
acme (4 blocks)
Name Title Category Type
hero Hero layout blockstudio
card Card components blockstudio
tabs Tabs layout blockstudio
tab-item Tab Item layout blockstudio
search corresponde a uma parte do texto, sem diferenciar maiúsculas de minúsculas, nos nomes, títulos e
descrições:
npx blockstudio search tab
Results for "tab"
acme/tabs - Tabs
Tabbed content with keyboard navigation.
acme/tab-item - Tab Item
Single tab panel used inside Tabs.
Visualize uma instalação com --dry-run. A dependência aparece primeiro porque
é instalada primeiro:
npx blockstudio add acme/tabs --dry-run
Would install:
tab-item (2 files)
tabs (3 files)
Agora instale de verdade:
npx blockstudio add acme/tabs
Downloading acme/tabs...
Installed tab-item (2 files)
Installed tabs (3 files)
As duas pastas agora estão no diretório blockstudio do tema, exatamente como
no repositório:
blockstudio/tab-item/block.json
blockstudio/tab-item/index.php
blockstudio/tabs/block.json
blockstudio/tabs/index.php
blockstudio/tabs/style.scss
Você pode omitir o namespace quando apenas um registro configurado contém o bloco e passar vários blocos de uma vez:
npx blockstudio add hero card
Downloading acme/hero...
Installed hero (2 files)
Downloading acme/card...
Installed card (3 files)
Blockstudio detecta as novas pastas como qualquer outro bloco do tema.
Atualizar blocos instalados
Os arquivos instalados são uma cópia. Nada registra qual versão foi instalada, e CLI nunca atualiza um bloco por conta própria. Para obter uma versão mais recente, adicione o bloco novamente. Sem um terminal, ou em CI, uma pasta existente interrompe o comando:
npx blockstudio add tab-item
Block "tab-item" already exists at .../acme-theme/blockstudio/tab-item. Use --yes to overwrite.
Em um terminal, CLI pergunta antes de sobrescrever. --dry-run informa as
pastas que substituiria, e --yes as substitui:
npx blockstudio add acme/tab-item --dry-run
Would overwrite tab-item
Would install:
tab-item (2 files)
A sobrescrita substitui os arquivos listados pela versão do registro, então confirme as alterações locais primeiro e revise o resultado com git diff.
Para desinstalar, remova a pasta pelo nome:
npx blockstudio remove tabs --yes
Removed tabs
remove recebe o nome da pasta, não namespace/block. Ele não remove
dependências, então tab-item continua instalado após a remoção de tabs.
Versionamento com refs de git
CLI não tem campo de versão nem flag de versão. O que ele obtém é decidido
inteiramente pelas URLs e, em GitHub, a ref em URL é a versão. Um
consumidor que aponta para main recebe o que main contém no momento da instalação.
Para publicar uma versão fixa, o registry.json na tag também precisa
baixar da tag. Antes de criar a tag, defina baseUrl como a tag:
"baseUrl": "https://raw.githubusercontent.com/acme/acme-blocks/v1.0.0/blocks"
Em seguida, confirme, crie a tag e envie:
git commit -am 'Release v1.0.0'
git tag v1.0.0
git push origin main v1.0.0
Depois, defina baseUrl novamente como main e confirme, para que a branch continue
servindo os arquivos atuais. Se você pular a primeira etapa, um consumidor fixado na tag
receberá a lista de blocos da tag, mas baixará os arquivos de main.
Os consumidores fixam uma versão usando a tag no URL do registro:
{
"$schema": "https://blockstudio.dev/schema/blocks.json",
"directory": "blockstudio",
"registries": {
"acme": "https://raw.githubusercontent.com/acme/acme-blocks/v1.0.0/registry.json"
}
}
Neste exemplo, v1.0.0 recebeu uma tag antes da existência de tabs e tab-item, então
o registro fixado só oferece os dois blocos originais:
npx blockstudio list
acme (2 blocks)
Name Title Category Type
hero Hero layout blockstudio
card Card components blockstudio
npx blockstudio add acme/tabs
Block "tabs" not found in registry "acme".
Um SHA de commit também funciona no URL do registro, mas um commit não pode conter seu próprio
SHA em baseUrl. Portanto, fixar por SHA define a lista de blocos, enquanto os arquivos
ainda vêm da ref indicada por baseUrl naquele commit. Por isso, prefira tags para
versões lançadas.
Pontos a ter em mente
- Todos os registros são buscados primeiro.
addcarrega todos os registros emblocks.jsonantes de resolver qualquer coisa, então um registro inacessível faz o comando falhar até mesmo paraacme/hero. Remova os registros que não usa mais. - Nomes ambíguos precisam de um namespace. Se dois registros tiverem
hero, uma sessão de terminal pergunta qual deles usar,--yesusa o primeiro na ordemblocks.json, e uma execução não interativa é encerrada comBlock "hero" found in multiple registries: acme, starter. Specify one: blockstudio add acme/hero. - Repositórios privados precisam de cabeçalhos. Use o formato de objeto de uma entrada de registro
com
urleheaders. Os valores dos cabeçalhos aceitam espaços reservados de${VAR}, lidos do ambiente, e o CLI envia os cabeçalhos junto com a busca do registro e com cada download de arquivo. Consulte a hospedagem GitHub para configurar o token.
Próximas etapas
- Visão geral do registro: o que é o registro e como funciona o CLI
- registry.json: todos os campos do manifesto
- blocks.json: configuração do consumidor, autenticação e descoberta da configuração
- adicionar: resolução de namespace, dependências e comportamento de sobrescrita
- GitHub hospedagem: GitHub Pages e repositórios privados
- Servidor personalizado: servir um registro a partir da sua própria infraestrutura