Configuración WordPress para desarrolladores: local, lint y bloques

La instalación de cinco minutos te deja un sitio en marcha. No te deja un puesto de desarrollador. En 2026 una configuración WordPress sólida es un stack local que se puede recrear, un pipeline de lint alineado con el core, depuración segura que nunca pinta errores en el frontend y tooling de bloques que envía los mismos assets que pruebas.

Esta guía es la checklist que usamos al provisionar un nuevo repositorio de tema o plugin: tipo de entorno, wp-env, @wordpress/scripts, constantes de debug y una capa fina de blindaje en wp-config.php y mu-plugins. En proyectos con equipos en Madrid o Barcelona, el mismo .wp-env.json en git corta el debate de “en mi máquina funciona”.

#Entorno local con wp-env

Las instalaciones manuales de Apache y PHP divergen. Una máquina corre PHP 8.2, otra sigue en 8.1, y los builds de bloques fallan solo en CI. El camino oficial es wp-env: contenedores Docker para WordPress, MySQL y herramientas opcionales, controlados por un .wp-env.json en la raíz del proyecto.

Instala una vez de forma global o como dependencia del proyecto:

npm install --save-dev @wordpress/env
npx wp-env start

Configuración mínima para un plugin en desarrollo:

{
  "core": "WordPress/WordPress#6.7",
  "plugins": [ "." ],
  "config": {
    "WP_DEBUG": true,
    "WP_DEBUG_LOG": true,
    "WP_DEBUG_DISPLAY": false,
    "SCRIPT_DEBUG": true
  }
}

Por qué gana a un stack genérico en trabajo de plugins:

• La versión de core queda fijada en git, así que “funciona en mi máquina” deja de ser una discusión.
• wp-env run cli te da WP-CLI dentro de los mismos contenedores que ve el navegador.
• Los tests y scripts e2e de @wordpress/scripts esperan este layout.

Combínalo con la documentación del entorno de desarrollo del editor de bloques cuando necesites notas de Node, create-block y extensiones de editor recomendadas.

Para trabajo de agencia que sigue en temas PHP clásicos, puedes mantener un binario PHP en el host para scripts puntuales, pero deja el sitio en wp-env para que media, cron y rewrites coincidan con staging.

Comandos útiles del día a día cuando el stack está arriba:

npx wp-env run cli wp plugin list
npx wp-env run cli wp cache flush
npx wp-env logs
npx wp-env stop

Mapea un dominio propio en el archivo hosts solo cuando el proyecto necesita cookies o SSO que localhost rompe. Si no, la URL por defecto basta y simplifica certificados.

Cuando un compañero clona el repo, la nota de onboarding debe tener tres líneas: instalar Docker, npm install, npx wp-env start. Cualquier cosa más larga suele significar que el entorno escapó a paquetes de host sin documentar.

#Tipo de entorno y disciplina en wp-config

Desde WordPress 5.5, WP_ENVIRONMENT_TYPE es el interruptor que debería leer cada plugin. Defínelo pronto en wp-config.php:

define( 'WP_ENVIRONMENT_TYPE', 'local' ); // local | development | staging | production

Luego ramifica el comportamiento sin inventar constantes propias:

if ( wp_get_environment_type() === 'production' ) {
	// Caché activa, logging verboso apagado.
} else {
	define( 'SCRIPT_DEBUG', true );
}

Constantes de blindaje que van en cada boilerplate de producción:

define( 'DISALLOW_FILE_EDIT', true );
define( 'FORCE_SSL_ADMIN', true );
define( 'WP_POST_REVISIONS', 5 );
define( 'AUTOMATIC_UPDATER_DISABLED', true ); // cuando el deploy gestiona updates de core

Usa DISALLOW_FILE_MODS solo cuando el árbol entero es inmutable y las actualizaciones llegan por CI. En hosts gestionados que aún parchean plugins desde el escritorio, esa constante peleará con el host.

Las claves de autenticación y las sales no son decoración. Rótalas tras un compromiso; todas las sesiones terminan al instante. Guarda la rotación en el runbook de deploy, no en una nota adhesiva.

#Linting con @wordpress/scripts

El linting es cómo te mantienes compatible con Gutenberg sin memorizar cada regla de ESLint. El paquete @wordpress/scripts envuelve webpack, Babel, ESLint, Stylelint, Jest y Playwright detrás de scripts npm familiares.

Superficie típica de package.json para un plugin de bloques:

{
  "scripts": {
    "start": "wp-scripts start",
    "build": "wp-scripts build",
    "lint:js": "wp-scripts lint-js",
    "lint:css": "wp-scripts lint-css",
    "lint:pkg-json": "wp-scripts lint-pkg-json",
    "format": "wp-scripts format",
    "packages-update": "wp-scripts packages-update"
  }
}

Ejecuta npm run lint:js en CI en cada pull request. Formatea con Prettier vía wp-scripts format para que los diffs hablen de lógica, no de comillas.

PHP sigue necesitando su propia puerta. Instala WordPress Coding Standards (WPCS) con Composer y corre PHPCS en temas y plugins. No esperes que @wordpress/scripts lo sustituya; cubre la mitad JS y CSS del stack.

Orden práctico de CI que atrapa la mayoría de regresiones:

1. composer phpcs (o tu wrapper de PHPCS)
2. npm run lint:js y npm run lint:css
3. npm run build para que un webpack roto falle antes de la review
4. Opcional: wp-env start y luego PHPUnit del plugin o Playwright del paquete de scripts

Ignora el output generado en build/ en las reviews de git, salvo que el proyecto commit’tee assets compilados a propósito para hosts sin Node. Prefiere build en CI o en el deploy. EditorConfig más la config Prettier por defecto del paquete scripts saca las guerras de indentación de los pull requests.

Si un tema legacy aún envía scripts de admin de la era jQuery, introduce @wordpress/scripts primero para bloques nuevos en lugar de reescribir cada enqueue el día uno. Stacks mixtos están bien; reglas mixtas no. Una config ESLint por directorio de paquete.

#Depuración sin filtrar errores

Nunca muestres errores PHP a los visitantes. Regístralos.

define( 'WP_DEBUG', true );
define( 'WP_DEBUG_LOG', true ); // escribe en wp-content/debug.log por defecto
define( 'WP_DEBUG_DISPLAY', false );
@ini_set( 'display_errors', 0 );

Mejor: apunta WP_DEBUG_LOG a una ruta fuera del document root y deniega acceso HTTP a cualquier debug.log residual bajo wp-content. En producción, deja WP_DEBUG en false salvo en pleno incidente. Activa SAVEQUERIES solo para sesiones cortas de profiling; cuesta memoria y no debería quedarse encendido de noche.

Complementa las constantes con herramientas que expliquen qué pasó:

• Query Monitor para hooks, llamadas HTTP y consultas lentas en la barra de admin
• Xdebug enganchado al contenedor PHP de wp-env cuando necesitas paso a paso
• DevTools del navegador con SCRIPT_DEBUG para cargar scripts de core sin minificar al cazar un conflicto

Cuando el staging muestra pantalla blanca, mira debug.log, el log de errores del host y wp-env logs (si es local) antes de instalar otro plugin de “debug”. La mayoría de caídas de producción por mala configuración aparecen como un fatal único en el log, no como una función que falta.

Reproduce el bug en una instancia wp-env desechable con el mismo conjunto de plugins antes de tocar constantes en producción. Si el problema solo aparece con object cache o CDN, anótalo en el ticket; Docker local no inventa Redis por ti salvo que lo añadas a la config del env.

#Tooling de bloques en 2026

Los bloques interactivos ya no son proyectos laterales. La ruta por defecto actual es:

1. Genera con npx @wordpress/create-block my-block --variant dynamic (o static, según la estrategia de render)
2. Desarrolla contra wp-env para que el registro vía block.json coincida con un admin real
3. Usa npm start para watch builds y npm run build para assets de producción
4. Registra el bloque en PHP con register_block_type( __DIR__ . '/build' ) cuando la metadata vive en block.json

Mantén scripts de editor y frontend separados en block.json para no enviar React solo de editor a cada visitante. Prefiere viewScript / viewStyle para interactividad en el frontend en lugar de volcar todo en un bundle.

En temas que aún hacen enqueue de assets clásicos, migra piezas interactivas nuevas a bloques de forma incremental. Un tema híbrido puede enviar block patterns y unos pocos bloques custom mientras el resto de plantillas sigue en PHP. Eso es normal en 2026; un rewrite completo del Site Editor es decisión de producto, no requisito de tooling.

Cuando las dependencias se desvían, npx wp-scripts packages-update refresca paquetes @wordpress/* dentro de la toolchain de scripts. Fija majors en package-lock.json y revisa el lockfile en los PRs igual que las actualizaciones de Composer.

#Limpieza fina del core con un mu-plugin

No necesitas un plugin “desactivar todo” del directorio. Un must-use pequeño mantiene las reglas en control de versiones:

<?php
/**
 * Plugin Name: Lean core
 */

remove_action( 'wp_head', 'print_emoji_detection_script', 7 );
remove_action( 'wp_print_styles', 'print_emoji_styles' );
remove_action( 'wp_head', 'wp_generator' );
add_filter( 'xmlrpc_enabled', '__return_false' );

Desactiva XML-RPC solo cuando estés seguro de que ningún cliente remoto lo necesita. Desactiva scripts de emoji cuando controlas iconos de marca y quieres menos peticiones en el frontend. Deja RSS en sitios de contenido; sitios brochure pueden cerrar feeds con un hook intencional, no con un snippet aleatorio de un foro.

#Lista de comprobación de lanzamiento

Antes de que un sitio de cliente salga a producción:

1. WP_ENVIRONMENT_TYPE es production.
2. DISALLOW_FILE_EDIT es true; SSL en admin está forzado.
3. Las revisiones están limitadas; el display de debug está apagado.
4. Local y CI arrancan desde el mismo .wp-env.json y pasan lint y build de @wordpress/scripts.
5. Los assets de bloques son builds de producción, no restos del modo watch.
6. Las sales son únicas; debug.log no es accesible por HTTP.

Una configuración WordPress que se recrea desde git vale más que un wp-config.php ingenioso solo. Paridad local, puertas de lint y logging honesto son lo que evita que el trabajo de bloques y el PHP clásico se peleen.

¿Necesitas una revisión sénior de un stack existente o un plugin de bloques nuevo? Habla con un desarrollador WordPress en WPPoland.