Como encolar scripts y estilos correctamente con wp_enqueue_ en WordPress

Introducción: por qué encolar correctamente

Encolar scripts y estilos en WordPress no es un detalle menor: es la forma correcta de cargar recursos respetando dependencias, evitando duplicados, manteniendo compatibilidad con plugins y temas y mejorando rendimiento y caché. Usar directamente etiquetas ltscriptgt o ltlinkgt en plantillas provoca colisiones, problemas de orden y dificulta la depuración. WordPress provee un sistema robusto con funciones como wp_enqueue_script y wp_enqueue_style que debes dominar.

Conceptos clave

• Handle: identificador único para cada script/estilo.
• Dependencias: lista de handles que deben cargarse antes.
• Versión: para control de caché puede usarse filemtime para busting durante desarrollo.
• Encolado vs registro: register prepara un recurso enqueue lo añade a la cola de carga.
• Hooks: usa los hooks adecuados: wp_enqueue_scripts (frontend), admin_enqueue_scripts (admin), login_enqueue_scripts (login), enqueue_block_editor_assets (editor de bloques).

Funciones principales

• wp_enqueue_script( handle, src, deps, ver, in_footer )
• wp_register_script( handle, src, deps, ver, in_footer )
• wp_enqueue_style( handle, src, deps, ver, media )
• wp_register_style( handle, src, deps, ver, media )
• wp_localize_script( handle, object_name, l10n ) — para pasar datos de PHP a JS (no sólo traducciones).
• wp_add_inline_script / wp_add_inline_style — añadir pequeños bloques inline respetando dependencias.
• wp_deregister_script / wp_dequeue_script — eliminar scripts previamente registrados/enqueued.

Parámetros esenciales explicados

Buenas prácticas

1. Siempre encolar con las funciones de WordPress en el hook adecuado.
2. Usar handles únicos y descriptivos (por ejemplo: mi-tema-main, pluginX-slider).
3. Declarar dependencias correctamente para evitar errores de orden.
4. Cargar scripts en el footer cuando sea posible (in_footer = true).
5. No registrar o deregistrar jQuery a menos que sea estrictamente necesario y sepas las implicaciones.
6. Usar filemtime en desarrollo para busting de caché y versiones semánticas en producción.
7. Evitar imprimir scripts/styles en plantillas centraliza en functions.php o archivos del plugin.

Ejemplos prácticos

1) Encolar estilo y script básicos en un tema (functions.php)

2) Registrar y encolar (útil si quieres condicionar más tarde)

3) Reemplazar jQuery por CDN (con precauciones)

Solo hacerlo si sabes que no romperás dependencias. Es recomendable cargar la versión adecuada y fallbacks si falla el CDN.

4) Pasar datos de PHP a JavaScript con wp_localize_script

Útil para rutas, nonce, strings traducibles o cualquier dato dinámico.

 admin_url( admin-ajax.php ),
        nonce    => wp_create_nonce( mi_action_nonce ),
        siteUrl  => home_url()
    )

    wp_localize_script( mi-tema-main, MiTemaData, data )
}
add_action( wp_enqueue_scripts, mi_tema_localize_script )
?>

5) Añadir script inline relacionado con un handle

Evita imprimir inline directamente en su lugar, usa wp_add_inline_script para mantener el orden y solo cuando el handle está presente.

6) Encolar solo en admin o editor de bloques

Errores comunes y cómo evitarlos

• No usar handles únicos — produce colisiones y rompe dependencias.
• Encolar en hooks equivocados o directamente en plantillas — centraliza en functions.php o archivos del plugin.
• Olvidar dependencias — provoca errores de referencia a objetos/funciones JS no definidos.
• Forzar versiones incorrectas de librerías compartidas (ej. jQuery) — rompe plugins que dependen de la versión incluida por WP.
• Imprimir scripts inline sin comprobar si la dependencia está encolada — usar wp_add_inline_script para garantizar orden.

Rendimiento y optimizaciones

• Usa compresión y minificación en procesos de build (Gulp, Webpack). En entorno de desarrollo activa SCRIPT_DEBUG para cargar archivos no minificados.
• Evita cargar recursos en todas las páginas carga condicionalmente donde se necesiten.
• Usa versionado efectivo (filemtime o versionado de build) para invalidar caché cuando cambia el recurso.
• Valora la posibilidad de combinar recursos en un build cuando trabajas en un ecosistema controlado (pero no con wp_enqueue en producción sin pensar en plugins externos).
• Considera preconnect/prefetch para CDNs (esto se hace con etiquetas en head, pero mantén la lógica separada y no inyectes enlaces arbitrarios desde plantillas).

Checklist rápido antes de publicar

1. Tus handles son únicos y descriptivos.
2. Has declarado las dependencias correctas.
3. Los scripts que pueden ir en footer usan in_footer = true.
4. Has usado filemtime o un sistema de versionado para busting de caché en desarrollo.
5. No estás reemplazando librerías centrales (ej. jQuery) sin pruebas.
6. Los assets del admin se encolan con admin_enqueue_scripts y los del editor con enqueue_block_editor_assets.

Conclusión

Encolar correctamente scripts y estilos con el API de WordPress es imprescindible para un desarrollo profesional y escalable. Siguiendo las buenas prácticas de handles, dependencias, hooks adecuados y versionado, evitarás la mayoría de problemas de compatibilidad y rendimiento. Usa las funciones mostradas para mantener tu tema o plugin ordenado, seguro y compatible con el ecosistema WordPress.

	Acepto donaciones de BAT's mediante el navegador Brave 🙂