Contents
Introducción
Este tutorial explica, paso a paso y con todo lujo de detalles, cómo crear bloques de Gutenberg usando la herramienta oficial @wordpress/scripts (JavaScript). Cubriremos la configuración del entorno, la estructura del plugin/bloque, los archivos necesarios (block.json, código JS con JSX), estilos, el proceso de compilación y cómo registrar el bloque en WordPress para que funcione tanto en el editor como en el frontend.
Requisitos previos
- WordPress 5.5 (recomendado por compatibilidad con block.json y funciones modernas).
- Un entorno de desarrollo de WordPress (local o remoto) con acceso al directorio de plugins.
- Node.js y npm instalados (Node 14 recomendado).
- Conocimientos básicos de JavaScript, JSX y conceptos de bloques de Gutenberg.
Estructura sugerida del plugin/bloque
Vamos a crear un plugin que contenga uno o más bloques. Una estructura típica mínima:
mi-plugin-bloques/ ├─ build/ # Archivos resultantes tras compilar ├─ src/ │ ├─ index.js # Entrada JS (registro del bloque o import) │ ├─ edit.js # Componente Edit (opcional) │ ├─ save.js # Componente Save (opcional) │ ├─ editor.scss # Estilos para editor │ └─ style.scss # Estilos para frontend ├─ block.json # Metadatos del bloque ├─ package.json └─ mi-plugin-bloques.php # Archivo principal PHP del plugin
Paso 1 — Crear el plugin y configurar npm
Dentro de la carpeta wp-content/plugins crea una carpeta para tu plugin, por ejemplo mi-plugin-bloques. Inicializa npm e instala @wordpress/scripts:
cd wp-content/plugins/mi-plugin-bloques npm init -y npm install @wordpress/scripts --save-dev
Modifica el package.json para añadir los scripts de compilación. Un ejemplo mínimo:
{
name: mi-plugin-bloques,
version: 1.0.0,
scripts: {
start: wp-scripts start,
build: wp-scripts build,
format: wp-scripts format:js
},
devDependencies: {
@wordpress/scripts: ^25.0.0
}
}
Paso 2 — Definir el metadata: block.json
block.json describe el bloque y permite a WordPress registrar automáticamente scripts y estilos generados en build/. Ejemplo:
{
apiVersion: 2,
name: mi-plugin/bloque-ejemplo,
title: Bloque Ejemplo,
category: widgets,
icon: smiley,
description: Un bloque de ejemplo creado con @wordpress/scripts,
supports: {
html: false
},
attributes: {
content: {
type: string,
source: html,
selector: p
}
},
textdomain: mi-plugin-bloques,
editorScript: file:./build/index.js,
style: file:./build/style.css,
editorStyle: file:./build/editor.css
}
Paso 3 — Código del bloque (JS / JSX)
Con @wordpress/scripts no necesitas configurar Babel o webpack manualmente. Crea los archivos en src/ y wp-scripts se encargará del empaquetado y transformación JSX.
Ejemplo sencillo en src/index.js que registra un bloque usando registerBlockType y exporta componentes edit y save:
import { registerBlockType } from @wordpress/blocks
import { __ } from @wordpress/i18n
import Edit from ./edit
import save from ./save
import ./editor.scss
import ./style.scss
registerBlockType( mi-plugin/bloque-ejemplo, {
edit: Edit,
save,
} )
Componente Edit (src/edit.js):
import { __ } from @wordpress/i18n
import { RichText, useBlockProps } from @wordpress/block-editor
export default function Edit( { attributes, setAttributes } ) {
const blockProps = useBlockProps()
return (
setAttributes( { content } ) }
placeholder={ __( Escribe aquí..., mi-plugin-bloques ) }
/>
)
}
Componente Save (src/save.js):
import { RichText, useBlockProps } from @wordpress/block-editor
export default function save( { attributes } ) {
return (
Paso 4 — Estilos para editor y frontend
Crea los estilos en src/editor.scss y src/style.scss. Ejemplo básico:
/ src/editor.scss /
.wp-block-mi-plugin-bloque-ejemplo {
border: 1px dashed #ccc
padding: 12px
}
/ src/style.scss /
.wp-block-mi-plugin-bloque-ejemplo p {
color: #222
font-size: 16px
}
Paso 5 — Registrando el bloque en PHP (archivo principal del plugin)
Si tu WordPress soporta la API de block.json, puedes registrar automáticamente los bloques leyendo block.json. Un archivo principal PHP mínimo:
mi-plugin-bloque-editor,
style => mi-plugin-bloque-style,
) )
}
}
add_action( init, mi_plugin_bloques_init )
Paso 6 — Compilar y probar
- En la carpeta del plugin ejecuta npm start para iniciar el proceso de desarrollo y watch. Esto generará archivos en build/ y actualizará en caliente en el editor.
- Alternativamente, ejecuta npm run build para generar los archivos optimizados en build/ listos para producción.
- Activa el plugin en el administrador de WordPress y abre el editor de bloques para insertar y probar tu bloque.
Detalles importantes y buenas prácticas
- block.json: Es la manera moderna de declarar metadatos. Permite a WP enlazar automáticamente scripts y estilos del build cuando usas register_block_type_from_metadata o register_block_type( __DIR__ ).
- Dependencias JS: @wordpress/scripts configura externals como wp.element, wp.blocks, etc., por lo que no debes empaquetar esas librerías en tu bundle.
- Transpilación JSX: @wordpress/scripts incluye Babel, por lo que puedes usar JSX y las nuevas características de JS sin configuración adicional.
- Preferir API v2: Usa apiVersion 2 en block.json para aprovechar mejoras en atributos y comportamientos.
- Internationalization: Usa __() y otras funciones de @wordpress/i18n en JS y carga el textdomain en PHP si haces strings traducibles.
- Estilos separados: Mantén estilos de editor y frontend separados para evitar CSS innecesario en el editor o en el sitio público.
- Control de versiones: Usa filemtime en wp_register_script/wp_register_style para cache busting en producción o herramientas de build que generen hashes.
Ejemplo de build automático con wp-scripts
La ventaja de @wordpress/scripts es la automatización: no necesitas config de webpack. Ejecutando los scripts definidos en package.json se crea una carpeta build/ con:
- build/index.js — bundle del editor
- build/style.css — estilos del frontend
- build/editor.css — estilos del editor
Si block.json apunta a esos archivos (usando file:./build/…) WordPress los enlazará cuando registres el bloque desde el metadata.
Registro alternativo manual (para compatibilidad)
Si no usas block.json o tu instalación no soporta register_block_type_from_metadata, registra manualmente los assets en PHP:
// Registro manual de script y estilo
wp_register_script(
mi-plugin-bloque-editor,
plugins_url( build/index.js, __FILE__ ),
array( wp-blocks, wp-element, wp-i18n, wp-editor, wp-components ),
filemtime( plugin_dir_path( __FILE__ ) . build/index.js )
)
wp_register_style(
mi-plugin-bloque-style,
plugins_url( build/style.css, __FILE__ ),
array(),
filemtime( plugin_dir_path( __FILE__ ) . build/style.css )
)
register_block_type( mi-plugin/bloque-ejemplo, array(
editor_script => mi-plugin-bloque-editor,
style => mi-plugin-bloque-style,
) )
Depuración y errores comunes
- Si el bloque no aparece: revisa la consola del navegador por errores de JS y confirma que build/index.js se está cargando.
- Errores de JSX: asegúrate de que @wordpress/scripts está instalado y que ejecutas wp-scripts start/build desde la carpeta raíz del plugin.
- Atributos vacíos o no guardados: revisa que uses correctas funciones de RichText (value / onChange / RichText.Content) y que los atributos están definidos en block.json.
- Problemas con versiones de WP: algunas funciones (como register_block_type_from_metadata) requieren versiones relativamente modernas en instalaciones antiguas usa el registro manual.
Extensiones y pasos siguientes
- Crear bloques dinámicos con render_callback en PHP para contenido que debe generarse en el servidor.
- Usar componentes de @wordpress/components para controles complejos en el editor.
- Integrar control de estilos con CSS Custom Properties o con editor color palette y font sizes del theme.
- Agregar pruebas y CI que ejecuten build y verifiquen código antes de desplegar.
Recapitulación rápida
Workflow mínimo:
- Crear carpeta del plugin y package.json.
- Instalar @wordpress/scripts.
- Crear src/ con index.js, edit.js, save.js y estilos.
- Definir block.json para metadatos y referenciar build/.js y build/.css.
- Usar wp-scripts start durante desarrollo y wp-scripts build para producción.
- Registrar el bloque en PHP con register_block_type_from_metadata o manualmente.
Con esto tienes una guía completa y práctica para empezar a crear bloques de Gutenberg modernos empleando @wordpress/scripts (JS). Si sigues estos pasos tendrás un flujo de trabajo robusto, sin necesidad de tocar configuraciones complejas de Babel/webpack y cumpliendo con las buenas prácticas recomendadas por el equipo de WordPress.
|
|
Acepto donaciones de BAT's mediante el navegador Brave 🙂 |