WP24Horas
♙ ◴
PARCEIRO RECOMENDADO Vai colocar um WordPress no ar? Comece com uma hospedagem que acompanha o seu projeto. Conhecer a HostGator link patrocinado

Desenvolvimento e Programação

Criando Blocos Personalizados com Gutenberg e React

Por Asllan Maciel4 min de leitura
Criando Blocos Personalizados com Gutenberg e React
Esta entrada é parte 10 de 20 na série WordPress Extremo: Gutenberg + React + Blocos Customizados

WordPress Extremo: Gutenberg + React + Blocos Customizados

Como Criar um Bloco WordPress com Filtro por Múltiplas Categorias

Bloco de Posts com Filtro por Múltiplas Categorias

Como Filtrar Posts por Categoria em um Bloco Gutenberg

Filtrando Posts por Categoria no Editor do Bloco

Como Criar um Bloco Dinâmico no WordPress com Renderização PHP

Bloco Dinâmico com Renderização no Servidor

Conectando Blocos Gutenberg à REST API

Conectando Blocos com a REST API do WordPress

Componentes Reutilizáveis e Campos Compostos no Gutenberg

Componentes Reutilizáveis e Atributos Compostos em Blocos Gutenberg

Adicionando Imagem Ícone e Classe CSS Personalizada em Bloco Gutenberg

Ícones, Imagens e Classes Personalizadas no Gutenberg

Atributos Visuais e Estilo Dinâmico com Gutenberg

Cor, Alinhamento e Estilo Dinâmico com Gutenberg + React

Como Estilizar Blocos Gutenberg com CSS e Classes Dinâmicas

Estilizando Blocos Gutenberg com CSS e Classes Dinâmicas

Criando Campos Dinâmicos e InspectorControls no Gutenberg

Campos Dinâmicos e InspectorControls no Gutenberg: Deixe Seu Bloco Interativo

Criando Blocos Personalizados com Gutenberg e React

Criando Blocos Personalizados com Gutenberg e React

Como Salvar Dados Personalizados no WordPress Usando Blocos Gutenberg e REST API

Salvando Dados Personalizados no Backend via REST API

Blocos Reutilizáveis com InnerBlocks no Gutenberg

Blocos Reutilizáveis com InnerBlocks no Gutenberg

Comunicação entre Blocos com Block Context API no WordPress

Comunicação entre Blocos com Block Context API no WordPress

Como Criar Blocos Condicionais no Gutenberg com Atributos

Como Criar Blocos Condicionais no Gutenberg com Atributos

Internacionalização de Blocos Gutenberg (i18n)

Internationalização de Blocos Gutenberg (i18n)

Como Carregar Scripts e Estilos no WordPress Apenas Quando Necessário

Scripts e Estilos Condicionais: Carregando apenas quando necessário

Uso de Slots e Templates Personalizados

Como Inserir Blocos Gutenberg via Código, Shortcodes ou PHP

Inserindo Blocos via Código ou Shortcodes

Como Validar e Testar Blocos Gutenberg

Testes e Validação de Blocos com @wordpress/scripts

Como Distribuir Seus Blocos Gutenberg em Plugins ou no GitHub

Distribuindo Seus Blocos: Plugins, Repositório e GitHub

E aí, dev! No Dia 7 da nossa jornada WordPress Extremo, a gente entra na parte que mais separa os generalistas dos devs WordPress de verdade: criar blocos personalizados com Gutenberg e React.

E olha, vou ser direto: não é difícil — o que falta é clareza no caminho.
Muita gente ensina isso de forma solta, e aí o projeto vira uma bagunça com pasta src misturando PHP com JS, build apagando tudo, e o bloco nem aparece…

Pois nesse post aqui, a gente vai fazer do jeito certo:
✔️ separado,
✔️ escalável,
✔️ e 100% compatível com a estrutura modular que estamos usando desde o Dia 1.

Vale dizer que alguns detalhes atendem ao nosso projeto atual, mas que, em alguns casos, pode ser feito de outra forma.


🎯 Objetivo de hoje

  • Criar um bloco React moderno, do zero
  • Manter a estrutura separada do código PHP
  • Compilar corretamente com @wordpress/scripts
  • Registrar e visualizar o bloco no editor Gutenberg
  • Entender o que cada parte do código faz

📦 Estrutura de pastas que usamos

/wp-content/plugins/wp-arquitetura-extrema/
├── src/                   → Classes PHP com PSR-4 (autoload via Composer)
├── blocks/
│   └── hello/
│       ├── block.json     ✅ Registro do bloco
│       ├── edit.js        ✅ Interface no editor
│       ├── save.js        ✅ Conteúdo salvo no post
│       └── index.js       ✅ Ponto de entrada do bloco
├── webpack.config.js      ✅ Build personalizado (especial pro nosso projeto)
├── package.json           ✅ Gerenciador NPM
├── .gitignore
└── wp-arquitetura-extrema.php

⚙️ Passo a passo completo

1. Instale o Node.js (se ainda não tiver)

👉 https://nodejs.org


2. Inicialize o NPM

Nota: npm é o gerenciador de pacotes padrão para o ambiente de tempo de execução JavaScript Node.js. E, precisamos rodar os comandos usando Terminal como Administrador.

Na pasta do plugin:

npm init -y

3. Instale o pacote de build do WordPress

npm install @wordpress/scripts --save-dev

4. Edite seu package.json

Atualize os scripts:

"scripts": {
  "build": "wp-scripts build",
  "start": "wp-scripts start"
}

5. Configure o Webpack (para compilar fora da pasta /src)

Nota: Precisamos fazer isso porque estamos usando a pasta /src para armazenar nossas Classes atuais processadas com composer.

📄 webpack.config.js:

const path = require('path');
const defaultConfig = require('@wordpress/scripts/config/webpack.config');

module.exports = {
  ...defaultConfig,
  entry: {
    'hello': path.resolve(__dirname, 'blocks/hello/index.js'),
  },
  output: {
    path: path.resolve(__dirname, 'blocks/hello/build'),
    filename: '[name].js',
    clean: false, // evita apagar pastas por acidente
  },
};

6. Crie o bloco no caminho correto

📄 blocks/hello/block.json

{
  "apiVersion": 2,
  "name": "wp24h/hello",
  "title": "Bloco Hello WP24H",
  "category": "widgets",
  "icon": "smiley",
  "description": "Um bloco simples para começar.",
  "editorScript": "file:./build/hello.js"
}

📄 blocks/hello/edit.js

import { __ } from '@wordpress/i18n';
import { useBlockProps } from '@wordpress/block-editor';

export default function Edit() {
  return (
    <div { ...useBlockProps() }>
      <p>{ __( '👋 Este é um bloco customizado', 'wp-arquitetura-extrema' ) }</p>
    </div>
  );
}

📄 blocks/hello/save.js

import { useBlockProps } from '@wordpress/block-editor';

export default function save() {
  return (
    <div { ...useBlockProps.save() }>
      <p>👋 Este é o conteúdo salvo do bloco WP24Horas!</p>
    </div>
  );
}

📄 blocks/hello/index.js

import { registerBlockType } from '@wordpress/blocks';
import Edit from './edit';
import save from './save';

registerBlockType('wp24h/hello', {
  edit: Edit,
  save
});

7. Compile o bloco

npm run build

Isso vai gerar blocks/hello/build/hello.js, que será carregado no editor.


8. Registre o bloco no WordPress (no plugin)

📄 Dentro do wp-arquitetura-extrema.php, adicione:

add_action('init', function() {
    register_block_type(__DIR__ . '/blocks/hello');
});

9. Veja seu bloco no editor!

  • Crie ou edite uma página/post
  • Clique no botão ➕ Adicionar bloco
  • Procure por Bloco Hello WP24H
  • Insira, salve e veja funcionando!

❗ Dicas importantes

  • Nunca use index.js diretamente não compilado no block.json
    → Use apenas a versão que sai do npm run build
  • Cuidado com webpack.config.js mal configurado:
    → Pode apagar arquivos se path estiver errado
  • Mantenha seu JS separado do PHP
    → /src para classes PHP
    → /blocks para blocos React

✅ Conclusão do Dia 7

Hoje você:

  • Criou um bloco personalizado do zero
  • Compilou com segurança usando @wordpress/scripts
  • Aprendeu a separar PHP de JS no projeto
  • Evitou armadilhas e seguiu uma arquitetura real de produção

💬 Curtiu esse conteúdo?

Esse tipo de arquitetura moderna é o que eu ensino em profundidade nos cursos e mentorias em:

👉 wp24horas.com.br
📲 Me segue: @wp24horas

Ou comenta aqui suas dúvidas que eu respondo pessoalmente 👇

WordPress Extremo: Gutenberg + React + Blocos Customizados

Campos Dinâmicos e InspectorControls no Gutenberg: Deixe Seu Bloco Interativo Salvando Dados Personalizados no Backend via REST API

Sobre o autor

Asllan Maciel

Asllan Maciel, Fundador do WP24Horas, Consultor de Marketing Digital e amante do Empreendedorismo Digital. Tem um caso de amor com o WordPress.