Atualizado em maio de 2026.

Gravei um vídeo sobre o @wordpress/create-block quando ele ainda estava na versão 2.0. De lá para cá a ferramenta amadureceu bastante: hoje está na linha 4.89, ganhou um sistema de variants, suporte a templates externos e já nasce alinhada às novidades de performance do WordPress 6.8. Neste guia, atualizado, vou mostrar como criar um bloco do zero com a versão atual da ferramenta.

O que é o create-block

O @wordpress/create-block é o pacote Node oficial para fazer o scaffolding (a estrutura inicial) de um bloco do Gutenberg. Com um único comando você recebe um plugin funcional: o block.json, o processo de build já configurado via @wordpress/scripts e os arquivos de edição e exibição do bloco. É, no mundo dos blocos, o equivalente ao que ferramentas como o create-react-app foram para o React: você pula toda a configuração e já começa a escrever código.

Requisitos

A versão atual exige um ambiente Node recente. Antes de começar, confirme:

• Node.js 20.10.0 ou superior
• npm 10.2.3 ou superior

Você pode checar com node -v e npm -v. Se as versões forem mais antigas, o próprio create-block avisa antes de continuar.

Criando seu primeiro bloco

Não é preciso instalar nada globalmente. O comando recomendado é:

npx @wordpress/create-block@latest meu-primeiro-bloco
cd meu-primeiro-bloco
npm startCode language: CSS (css)

Use sempre o @latest no final do pacote — assim o npx não reaproveita uma versão antiga que tenha ficado em cache.

Uma dica útil: se você rodar o comando sem informar o nome do bloco, o create-block entra em modo interativo e pergunta passo a passo o título, o namespace, a descrição e a variant do bloco. É a forma mais simples para quem está começando.

As opções da linha de comando

O create-block aceita uma série de flags para personalizar o projeto. Estas são as principais da versão atual:

Opção	O que faz
-V, --version	Mostra a versão do create-block instalada.
-t, --template	Template do projeto: standard (padrão), es5, um pacote npm externo ou um diretório local.
--variant	Escolhe a variant do template (ex.: static ou dynamic).
--no-plugin	Gera apenas os arquivos do bloco, sem criar a estrutura de plugin.
--target-dir	Define a pasta onde os arquivos serão criados.
--namespace	Prefixo interno do nome do bloco.
--title	Título exibido para o bloco.
--short-description	Descrição curta do bloco e do plugin.
--category	Categoria em que o bloco aparece no editor.
--wp-scripts / --no-wp-scripts	Ativa ou desativa a integração com o @wordpress/scripts.
--wp-env	Ativa a integração com o @wordpress/env (ambiente local via Docker).
--textdomain	Define o text domain para internacionalização.
-h, --help	Mostra a ajuda com todas as opções.

Variants: bloco estático ou dinâmico

Os templates embutidos oferecem duas variants, que definem como o bloco gera sua saída:

• static (padrão) — toda a saída é renderizada no save.js e o HTML fica salvo no banco de dados. Ideal para blocos cujo conteúdo não muda depois de publicado.
• dynamic — adiciona um render.php ao projeto; a saída do front-end é gerada por PHP a cada carregamento. Use quando o conteúdo muda com o tempo: listas de posts recentes, dados vindos de uma API, a data atual, etc.

Para criar um bloco dinâmico:

npx @wordpress/create-block@latest meu-bloco --variant dynamicCode language: CSS (css)

Blocos interativos com a Interactivity API

A maior novidade desde aquele vídeo de 2021 é a Interactivity API — o padrão do WordPress para adicionar interatividade no front-end dos blocos sem você ter que montar o próprio JavaScript do zero.

Os templates embutidos do create-block não geram blocos interativos. Para isso existe um template externo oficial:

npx @wordpress/create-block@latest meu-bloco-interativo --template @wordpress/create-block-interactive-templateCode language: CSS (css)

Esse template tem variants próprias: default, typescript e client-side-navigation — esta última já gera um bloco com navegação client-side completa (roteamento, navegação entre páginas e indicador de carregamento). Se você omitir o nome do bloco, o create-block pergunta qual variant usar.

Templates externos

Como vimos acima, a opção --template aceita muito mais do que os templates embutidos: você pode passar qualquer pacote npm ou o caminho de um diretório local. Isso permite que a comunidade — e você — criem templates reaproveitáveis.

Os dois templates oficiais mantidos pela equipe do WordPress são:

• @wordpress/create-block-tutorial-template — gera o bloco “Copyright Date” usado no guia oficial de criação de blocos. Ótimo para aprender.
• @wordpress/create-block-interactive-template — gera blocos com a Interactivity API, como mostrado acima.

Os comandos do projeto

Depois do scaffolding, o package.json do projeto vem com estes scripts:

Comando	O que faz
npm start	Inicia o ambiente de desenvolvimento com recompilação automática.
npm run build	Compila o código para produção.
npm run format	Formata todos os arquivos do projeto.
npm run lint:js	Verifica os arquivos JavaScript.
npm run lint:css	Verifica os arquivos de estilo.
npm run packages-update	Atualiza os pacotes do WordPress usados no projeto.
npm run plugin-zip	Gera um arquivo ZIP do projeto em formato de plugin, pronto para distribuir.

Se você usou a flag --wp-env, também terá o comando npm run env para subir o ambiente local com Docker.

Um detalhe que mudou: hoje os scripts build e start já incluem a flag --blocks-manifest automaticamente. Tutoriais antigos pediam para adicioná-la na mão — não é mais necessário.

Registro eficiente de blocos no WordPress 6.8

Esse --blocks-manifest tem um motivo. O plugin gerado pelo create-block hoje registra os blocos com a função wp_register_block_types_from_metadata_collection(), introduzida no WordPress 6.8:

wp_register_block_types_from_metadata_collection(
    __DIR__ . '/build',
    __DIR__ . '/build/blocks-manifest.php'
);Code language: PHP (php)

Em vez de ler vários arquivos block.json do disco, o WordPress lê um único manifesto (blocks-manifest.php) gerado no build. O ganho de performance é especialmente relevante em plugins com muitos blocos. É por isso que o block.json gerado já vem com apiVersion: 3 e requiresAtLeast: 6.8.

Conclusão

O create-block deixou de ser apenas um gerador de “esqueleto” e virou a porta de entrada recomendada para qualquer projeto de bloco — do bloco estático mais simples ao bloco interativo com a Interactivity API. Em vez de decorar números de versão, vale guardar o essencial: rode npx @wordpress/create-block@latest, escolha a variant certa para o seu caso e deixe a ferramenta cuidar do build.

Se quiser ver o processo na prática, confira também os outros posts sobre desenvolvimento de blocos aqui no blog.