Um plug in de bloco é um plugin WordPress que adiciona um bloco personalizado à lista do editor Gutenberg, com edição visual própria e renderização controlada por você. Diferente de um widget de page builder, ele vive no núcleo do editor e funciona em qualquer tema compatível com blocos. A maioria dos tutoriais começa pelo código React e assusta quem chega do front-end clássico. Aqui a gente inverte: primeiro o scaffolding oficial cria o esqueleto, depois você entende cada arquivo. Em cinco passos, do terminal ao bloco publicado, você terá um plug in de bloco rodando num site real, com build de produção e metadados corretos.

Primeiros passos: Visão geral do plug in de bloco

Criar um plug in de bloco hoje leva cerca de 30 minutos do zero ao build de produção, contra os dias que a configuração manual de Webpack exigia até 2021. O caminho oficial parte do pacote @wordpress/create-block, que monta a pasta com block.json, index.js, edit.js e save.js já prontos para uso.

A tabela abaixo mapeia cada etapa ao seu objetivo e ao check que prova que ela funcionou, para você não avançar com um passo quebrado e nem perder tempo depurando um bloco que nem chegou a registrar direito.

A FULL recomenda começar pelo ambiente local antes de subir para produção: a gente vê no suporte que muito bloco quebra ao ir direto para o site no ar sem o npm run build rodado.

O que você precisa antes de criar um plug in de bloco

Antes de escrever a primeira linha, você precisa de três coisas: Node.js 18 ou superior, npm instalado e um WordPress 6.3+ para usar o apiVersion 3 atual. O Node é exigência do @wordpress/create-block, que roda em ambiente JavaScript, então sem ele o scaffolding nem inicia.

Um WordPress abaixo de 6.3 ainda cria blocos, mas trava no apiVersion 2, e essa diferença explica boa parte dos blocos que “somem” depois de uma atualização do core.

A pilha de ferramentas é enxuta e quase toda gratuita. Você vai usar o terminal, um editor de código como o VS Code e o wp-env ou um Local by Flywheel para subir o WordPress local. O Gutenberg já vem com a biblioteca de componentes React embutida, então você não instala React manualmente. Se você nunca mexeu com linha de comando, vale antes ler o nosso guia de como usar o editor de blocos do WordPress para conhecer o terreno onde o bloco vai viver.

Passo a passo: Criando o plug in de bloco do zero

Os cinco passos abaixo levam você do terminal vazio ao bloco ativo em produção, e cada um termina com um check objetivo. Em ambientes de teste da FULL, o fluxo completo roda em torno de 25 a 35 minutos quando o Node já está instalado e o WordPress local já está no ar.

A ordem importa: pular o build antes da ativação é o erro número um que chega ao suporte. Siga na sequência e valide cada passo antes de seguir para o próximo.

Passo 1: Gere o esqueleto com create-block

Rode npx @wordpress/create-block@latest meu-bloco na pasta de plugins do WordPress. O comando baixa o pacote oficial e cria uma pasta completa com block.json, src/index.js, src/edit.js, src/save.js e o package.json de build. Para um bloco dinâmico renderizado no servidor, adicione --variant=dynamic, que gera também o render.php. Em segundos você tem um plug in de bloco já funcional, antes de tocar em qualquer código.

Passo 2: Configure o block.json

Abra o block.json e revise os campos apiVersion, name, title e category. O apiVersion deve ser 3 em WordPress 6.3 ou superior; o name segue o padrão namespace/bloco e precisa ser único no site. O title é o nome que aparece na busca do editor. Esse arquivo é a fonte única de verdade do bloco desde o WordPress 5.8, lido pela função register_block_type no PHP.

Passo 3: Defina a edição no edit.js

No src/edit.js, a função Edit() retorna o JSX que o usuário vê e manipula dentro do editor. É aqui que você adiciona campos de texto, controles de cor e a barra lateral de configurações com os componentes de @wordpress/components. Para um primeiro plug in de bloco, mantenha simples: um parágrafo editável com RichText já demonstra o ciclo completo. O useBlockProps() conecta seu markup ao sistema de estilos do bloco.

Passo 4: Compile com npm run build

Entre na pasta do bloco e rode npm install seguido de npm run build. O build compila o src para a pasta build, que é o que o WordPress de fato carrega. Durante o desenvolvimento, use npm run start para recompilar a cada salvamento. Sem a pasta build gerada, o registerBlockType no index.js não chega ao navegador e o bloco simplesmente não aparece na lista do Gutenberg.

Passo 5: Ative e valide no editor

Vá em Plugins no painel do WordPress, ative o seu plug in de bloco e abra um post novo. Clique no “+” do editor, busque pelo title que você definiu e insira o bloco. Edite o conteúdo, salve e visualize no front-end para confirmar a renderização. Se o bloco aparece no editor mas sai vazio na página, o problema costuma estar no save.js ou no atributo render do block.json apontando para o arquivo errado.

Bloco estático ou dinâmico: Qual escolher no plug in de bloco

A escolha entre bloco estático e dinâmico define como o conteúdo é salvo e onde ele é montado, e muda 100% da manutenção futura. No bloco estático, o save.js grava o HTML final direto no banco de dados, o que é rápido e ideal para conteúdo fixo como um aviso ou um botão simples.

No dinâmico, o render.php monta o HTML a cada visita, lendo $attributes em tempo real, o que serve a dados que mudam, como uma lista de posts recentes.

A diferença prática aparece na hora de evoluir o bloco. Um bloco estático que você altere depois pode gerar o temido “block validation error”, porque o HTML salvo não bate mais com o save() novo. O bloco dinâmico não tem esse risco: como o render.php gera tudo na hora, mudar o template não invalida o conteúdo antigo. Para quem vai manter o bloco por anos, vale conhecer também o caminho com criar blocos customizados com ACF PRO, que reduz a parte de código a um mínimo.

Erros comuns que travam um plug in de bloco

A maioria dos chamados sobre blocos que “não funcionam” no suporte da FULL cai em três causas previsíveis, todas detectáveis em menos de cinco minutos. A primeira é o apiVersion do block.json fixado em 3 num WordPress abaixo de 6.3: o bloco carrega sem erro visível no editor, mas some da lista após atualizar o core.

A segunda causa é a ausência da pasta build, esquecida quando o desenvolvedor sobe o src cru para o servidor sem rodar o passo de compilação.

A terceira causa é o render.php declarado no block.json sem o atributo render apontando o caminho certo: o bloco aparece no editor mas renderiza vazio no front-end. Para depurar, abra o console do navegador e procure por erros de registerBlockType; eles denunciam build faltando ou nome de bloco duplicado. Quem precisa mover blocos entre sites sem reescrever nada deve olhar o guia de como exportar e importar blocos no Gutenberg, que evita parte desses conflitos de versão.

Plug in de bloco ou page builder: Quando cada um faz sentido

Na maior parte dos projetos de cliente que passam pela base da FULL, a decisão entre um plug in de bloco nativo e um page builder se resume a quem vai manter o site no dia a dia. O bloco Gutenberg é leve, versiona bem no Git e não amarra o conteúdo a um plugin específico.

Se o plugin sai, o HTML estático permanece. O bloco nativo compete por portabilidade e performance, com payload mínimo de CSS e JS no front-end.

O page builder, como o Elementor, compete por velocidade de montagem visual sem código, ideal para agências que entregam dezenas de landing pages. O custo é o lock-in: desativar o builder costuma quebrar o layout. Se a dúvida é qual usar no seu caso, o comparativo Elementor vs Gutenberg abre os dois lado a lado. E quem quer dominar o ecossistema visual encontra o passo a passo completo na categoria de Elementor da FULL, com tutoriais por nível.

Acelere o desenvolvimento com a stack certa da FULL

Montar um plug in de bloco do zero é viável, mas manter um site com blocos próprios, plugins premium e build atualizado é onde o tempo escapa. O plano PRO da FULL sai por R$849 e libera o bundle com Elementor PRO, Crocoblock, ACF PRO e mais 14 plugins ativados em um clique. Distribuído pelos sites que você gerencia, isso fica em torno de R$85 por site, o que a gente vê no suporte ser mais barato que licenciar cada plugin avulso e ainda controlar atualização um a um. Para quem desenvolve com @wordpress/create-block e ACF PRO juntos, ter as licenças centralizadas tira a fricção de renovação manual a cada ano.

Perguntas frequentes sobre plug in de bloco

Próximos passos para dominar blocos no WordPress

Com o seu primeiro plug in de bloco rodando, o caminho natural é aprofundar em atributos, controles da sidebar e blocos dinâmicos que consultam o banco. Vale também entender como o PHP do WordPress monta páginas por trás, no nosso guia de criar posts e páginas com PHP, já que o render.php segue a mesma lógica. Para juntar tudo em uma trilha de aprendizado, o guia domine o Elementor reúne os materiais de criação visual e os de bloco nativo em um só lugar. O importante agora é repetir os cinco passos com um segundo bloco: a fluência vem da segunda vez, não da primeira.

Legenda: o plug in de bloco aparece na busca do editor assim que o npm run build é concluído e o plugin é ativado.