Criando Blocos Personalizados com Gutenberg e React

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 👇