Cómo Agregar JavaScript Personalizado a Temas de WordPress

Quieres agregar JavaScript personalizado a tu tema de WordPress. Tal vez sea un efecto de desplazamiento, un fragmento de seguimiento de terceros o funcionalidad interactiva. Pegas el código en tu archivo de plantilla y nada funciona—o peor aún, mezclas PHP y JavaScript y rompes todo.

Esto sucede constantemente. La solución es sencilla: usa el sistema de gestión de scripts integrado de WordPress en lugar de codificar etiquetas <script> directamente.

Por Qué Deberías Encolar Scripts en WordPress

WordPress funciona sobre un ecosistema complejo de temas y plugins. Cuando insertas JavaScript directamente en las plantillas, creas problemas:

• Carga duplicada: Múltiples plugins podrían cargar la misma biblioteca.
• Fallos de dependencias: Tu script se ejecuta antes de que se carguen sus dependencias.
• Problemas de caché: Los navegadores no pueden almacenar en caché correctamente los scripts en línea.
• Conflictos: Los scripts interfieren entre sí sin coordinación.

La función wp_enqueue_script resuelve estos problemas permitiendo que WordPress gestione el orden de carga de scripts, las dependencias y la ubicación de salida.

La Forma Correcta de Agregar JavaScript a WordPress

Paso 1: Crea Tu Archivo JavaScript

Coloca tu JavaScript en el directorio de tu tema. Una estructura común:

your-theme/
├── js/
│   └── custom.js
├── functions.php
└── style.css

Escribe JavaScript limpio sin mezclar PHP:

document.addEventListener('DOMContentLoaded', function() {
    // Tu código aquí
});

Paso 2: Encola el Script en functions.php

Agrega esto al functions.php de tu tema:

function mytheme_enqueue_scripts() {
    wp_enqueue_script(
        'mytheme-custom',                              // Handle
        get_template_directory_uri() . '/js/custom.js', // Source
        array(),                                        // Dependencies
        '1.0.0',                                        // Version
        array( 'in_footer' => true )                   // Load in footer
    );
}
add_action( 'wp_enqueue_scripts', 'mytheme_enqueue_scripts' );

Para temas hijos, usa get_stylesheet_directory_uri() en lugar de get_template_directory_uri().

Entendiendo los Parámetros de wp_enqueue_script

La función acepta cinco parámetros:

Carga Condicional de Scripts

No cargues scripts en todas partes cuando solo se necesitan en páginas específicas:

function mytheme_enqueue_scripts() {
    if ( is_singular( 'post' ) ) {
        wp_enqueue_script( 'mytheme-post-scripts', /* ... */ );
    }

    if ( is_page( 'contact' ) ) {
        wp_enqueue_script( 'mytheme-contact-form', /* ... */ );
    }
}
add_action( 'wp_enqueue_scripts', 'mytheme_enqueue_scripts' );

Estrategias de Carga Conscientes del Rendimiento

WordPress 6.3 introdujo soporte nativo para carga defer y async:

wp_enqueue_script(
    'mytheme-analytics',
    get_template_directory_uri() . '/js/analytics.js',
    array(),
    '1.0.0',
    array(
        'in_footer' => true,
        'strategy'  => 'defer'
    )
);

Defer ejecuta scripts después del análisis del DOM mientras mantiene su orden declarado. Async ejecuta scripts inmediatamente una vez descargados, sin orden garantizado. Usa defer para la mayoría de casos y async para scripts independientes como analíticas.

WordPress Moderno: Módulos de Script e Integración de Bloques

WordPress continúa evolucionando su manejo de JavaScript. Dos desarrollos que vale la pena mencionar:

API de Módulos de Script: WordPress 6.5 introdujo wp_enqueue_script_module() para módulos ES nativos. Esto habilita patrones modernos de JavaScript con importaciones de módulos adecuadas.

Temas basados en bloques: Si estás construyendo bloques, declara scripts en block.json usando los campos viewScript o viewScriptModule en lugar de encolado manual. WordPress maneja la carga automáticamente cuando el bloque se renderiza.

Estos enfoques funcionan junto con el encolado tradicional—elige según las necesidades de tu proyecto.

Conclusión

Agregar JavaScript personalizado a temas de WordPress requiere usar el sistema de encolado, no etiquetas de script codificadas directamente. Crea archivos JavaScript separados, regístralos con wp_enqueue_script, declara las dependencias correctamente y usa carga condicional para evitar solicitudes innecesarias. Para mejor rendimiento, aprovecha las estrategias defer y async disponibles desde WordPress 6.3.

El patrón es simple: mantén PHP y JavaScript separados, deja que WordPress gestione la carga, y tus scripts funcionarán de manera confiable a través de temas y plugins.

Preguntas Frecuentes

Gain Debugging Superpowers

Unleash the power of session replay to reproduce bugs, track slowdowns and uncover frustrations in your app. Get complete visibility into your frontend with OpenReplay — the most advanced open-source session replay tool for developers. Check our GitHub repo and join the thousands of developers in our community.