Pular para o conteúdo

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 um baseUrl de onde baixá-los.
  • blocks.json fica 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/:

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

JSON
{
  "$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"
      }
    ]
  }
}
PHP
<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:

JSON
{
  "$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.
  • baseUrl precisa ser um URL absoluto. CLI o valida como URL e rejeita valores relativos. Os arquivos de bloco são sempre obtidos de baseUrl, nunca de um local relativo a onde registry.json foi carregado.
  • dependencies nomeia blocos no mesmo registro. Adicionar tabs instala tab-item primeiro. 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 em blocks.json, que não precisa corresponder.
  • type é informativo. Aceita blockstudio, create-block ou wordpress e 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:

Código
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 baseUrl em registry.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:

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

Shell
npx blockstudio init --yes
Código
Created .../acme-theme/blocks.json

init --yes grava um objeto registries vazio. Adicione o registro sob o namespace que você quer digitar nos comandos:

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

Shell
npx blockstudio list
Código
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:

Shell
npx blockstudio search tab
Código
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:

Shell
npx blockstudio add acme/tabs --dry-run
Código
Would install:
  tab-item (2 files)
  tabs (3 files)

Agora instale de verdade:

Shell
npx blockstudio add acme/tabs
Código
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:

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

Shell
npx blockstudio add hero card
Código
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:

Shell
npx blockstudio add tab-item
Código
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:

Shell
npx blockstudio add acme/tab-item --dry-run
Código
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:

Shell
npx blockstudio remove tabs --yes
Código
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:

JSON
"baseUrl": "https://raw.githubusercontent.com/acme/acme-blocks/v1.0.0/blocks"

Em seguida, confirme, crie a tag e envie:

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

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

Shell
npx blockstudio list
Código
acme (2 blocks)

  Name  Title  Category      Type
  hero  Hero   layout        blockstudio
  card  Card   components    blockstudio
Shell
npx blockstudio add acme/tabs
Código
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. add carrega todos os registros em blocks.json antes de resolver qualquer coisa, então um registro inacessível faz o comando falhar até mesmo para acme/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, --yes usa o primeiro na ordem blocks.json, e uma execução não interativa é encerrada com Block "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 url e headers. 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