Installate un plugin e questo si trascina dietro la propria copia di jQuery. Il vostro tema ha già caricato jQuery tramite wp_enqueue_script. Il plugin, di nuovo, lo carica direttamente da una CDN. Sulla pagina: due o persino tre versioni della stessa libreria. Conflitti, dimensioni gonfiate, comportamento imprevedibile.

Il problema è vecchio quanto WordPress, eppure succede ancora: gli sviluppatori copiano e incollano <script src="jquery.js"> in header.php «perché è più veloce». Più veloce, fino al primo conflitto con un plugin che si aspetta la versione nativa di WP.

A partire dal 2026, WordPress distribuisce jQuery 3.6.0 di serie e fornisce un modo semplice e deterministico per includerlo senza duplicazioni e senza tracciare manualmente le versioni. Di seguito trovate l'unico approccio corretto, dal basilare wp_enqueue_script alla sostituzione sicura con una versione CDN e all'uso della modalità noConflict.

💡 Panoramica rapida:

• Come WordPress carica già jQuery e perché non dovreste farlo manualmente
• wp_enqueue_script con la dipendenza jquery: una riga in functions.php
• Quando e come sostituire in sicurezza il jQuery integrato con una versione CDN (Google / cdnjs)
• Modalità noConflict: protezione contro le collisioni con altre librerie
• Consigli per temi e plugin: quando NON sovrascrivere il jQuery integrato

JQuery è già nel core: cosa fa WordPress per voi

A partire dalla versione 3.6, WordPress registra jQuery con l'handle jquery. Non dovete scaricare jquery.min.js, metterlo nella cartella del tema e includerlo con un tag <script>. Il core lo fa automaticamente non appena specificate jquery nelle dipendenze del vostro script.

La versione corrente di jQuery nel core di WordPress è la 3.6.0. Viene fornita in bundle con jQuery Migrate (per la retrocompatibilità con codice legacy) e si carica solo quando qualche script dichiara jquery come dipendenza. Nessuna dipendenza significa che jQuery non compare sulla pagina e il sito non carica risorse inutili.

Ecco perché un <script src="/wp-content/themes/mytime/jquery.js"> diretto in header.php è un errore, non una scorciatoia. Scavalcate il sistema delle dipendenze, togliete a WP la capacità di gestire l'ordine di caricamento e ottenete un duplicato quando un plugin richiede legittimamente jquery tramite wp_enqueue_script.

Il modo giusto: wp_enqueue_script con una dipendenza

Il meccanismo di base sta in una riga dentro l'hook wp_enqueue_scripts. Voi scrivete il vostro script e WordPress capisce quando e in che ordine caricare tutto.

Create (o aprite) il functions.php del vostro tema e aggiungete:

1
function mytheme_enqueue_scripts() {
2
    wp_enqueue_script(
3
        'mytheme-main',
4
        get_template_directory_uri() . '/js/main.js',
5
        array( 'jquery' ),
6
        '1.0.0',
7
        array(
8
            'strategy'  => 'defer',
9
            'in_footer' => true,
10
        )
11
    );
12
}
13
add_action( 'wp_enqueue_scripts', 'mytheme_enqueue_scripts' );

Cosa succede qui:

• mytheme-main è l'handle univoco per il vostro script. Inventatene uno vostro, con il prefisso del nome del tema.
• get_template_directory_uri() . '/js/main.js' è il percorso del file. Potete anche usare un URL CDN esterno.
• array( 'jquery' ) è il punto chiave: state dicendo a WP «il mio script dipende da jQuery». Il core lo vede e mette automaticamente in coda jQuery prima del vostro script. Niente tag <script> nel template.
• '1.0.0' è la versione per il cache busting. Cambiatela a ogni aggiornamento dello script.
• array( 'strategy' => 'defer', 'in_footer' => true ): da WordPress 6.3, il parametro $args accetta un array. defer significa «esegui lo script dopo che il DOM è stato costruito ma prima di DOMContentLoaded». in_footer posiziona lo script nel footer.

La vecchia sintassi con un quinto parametro booleano (true = nel footer) funziona ancora, ma per i nuovi progetti usate la sintassi con array. È più leggibile e vi dà il controllo su async/defer.

Verificate che il vostro tema chiami wp_head() prima del </head> di chiusura e wp_footer() prima di </body>. Senza queste chiamate, wp_enqueue_script semplicemente non funziona. Questa è una trappola comune quando si migra da temi molto vecchi.

Come sostituire il jQuery integrato con la vostra versione

A volte la versione nativa non basta. Volete jQuery 4.0.0 da una CDN per le ultime correzioni, oppure vi serve una versione specifica per compatibilità con un plugin legacy. Potete sostituirla, ma con attenzione.

L'errore: chiamare semplicemente wp_enqueue_script('jquery', 'https://cdn.jsdelivr.net/npm/[email protected]/dist/jquery.min.js'). WordPress NON sovrascrive un handle già registrato. Otterrete sia la versione nativa che quella CDN sulla stessa pagina.

La sequenza corretta: prima deregistrate il jquery nativo, poi registrate il vostro:

1
function mytheme_use_cdn_jquery() {
2
    // Deregister the built-in jQuery
3
    wp_deregister_script( 'jquery' );
4
 
5
    // Register your own — from CDN
6
    wp_register_script(
7
        'jquery',
8
        'https://cdn.jsdelivr.net/npm/[email protected]/dist/jquery.min.js',
9
        array(),
10
        '4.0.0',
11
        true
12
    );
13
 
14
    // Enqueue it
15
    wp_enqueue_script( 'jquery' );
16
}
17
add_action( 'wp_enqueue_scripts', 'mytheme_use_cdn_jquery' );

Tre punti spesso trascurati:

Google Hosted Libraries. La CDN alternativa di Google è ancora attiva e ospita jQuery 3.7.1: https://ajax.googleapis.com/ajax/libs/jquery/3.7.1/jquery.min.js. Il vantaggio: milioni di siti hanno già scaldato la cache del browser per questo URL. Lo svantaggio: Google aggiunge i propri header e non aggiorna le versioni immediatamente dopo il rilascio.

cdnjs. Se vi serve jQuery 4.0.0, prendetelo da cdn.jsdelivr.net/npm/[email protected]/. cdnjs rispecchia il pacchetto npm e lo serve con header CORS corretti.

Non deregistrate jQuery nei temi pubblici. Se il vostro tema è destinato al repository di WordPress.org, usate il jQuery nativo del core. Il motivo è semplice: quando un sito ha sia un tema (con jQuery 4.0.0 da CDN) che un plugin (che si aspetta jQuery 3.6.0 dal core), il conflitto lo risolve l'utente, non lo sviluppatore. Nei temi commerciali e nei progetti personalizzati, sentitevi liberi di sostituirlo.

Modalità noConflict: quando c'è più di una libreria sulla pagina

Di default, jQuery occupa la variabile globale $. Il problema è che $ è un nome diffuso: lo usano anche Prototype, MooTools e alcuni framework legacy. Se un plugin o un altro script rivendica anch'esso $, vince quello caricato per ultimo e gli altri si rompono.

Protezione in una riga all'inizio del vostro script:

1
var $j = jQuery.noConflict();

Dopo questa riga, $ viene rilasciato per le altre librerie e il vostro codice funziona tramite $j. Esempio completo: una sidebar con animazione hover:

1
jQuery(document).ready( function( $ ) {
2
    // Here $ is jQuery, but only inside this function
3
    $( '#sidebar li a' ).hover(
4
        function() {
5
            $( this ).stop().animate( { paddingLeft: '20px' }, 400 );
6
        },
7
        function() {
8
            $( this ).stop().animate( { paddingLeft: '0' }, 400 );
9
        }
10
    );
11
} );

Qui $ funziona come jQuery all'interno della chiusura jQuery(document).ready(), e fuori è libero per altri. Questo è più pulito che disseminare variabili $j, $jq e $myJQ in tutto il codice.

Quando noConflict non serve: se il vostro sito gira interamente su WordPress senza framework JS di terze parti e tutti i plugin sono scritti per wp_enqueue_script, $ è al sicuro. Ma includere noConflict nel boilerplate standard del vostro tema è una buona abitudine che costa solo una riga.

Cosa dovrebbero fare gli sviluppatori di plugin

Se scrivete un plugin per la distribuzione pubblica, usate solo wp_enqueue_script con una dipendenza da jquery. Niente wp_deregister_script('jquery') dentro i plugin: non sapete quale versione di jQuery si aspettano gli altri plugin sullo stesso sito.

Il pattern corretto per un plugin si presenta così:

1
function myplugin_frontend_scripts() {
2
    wp_enqueue_script(
3
        'myplugin-frontend',
4
        plugins_url( '/js/frontend.js', __FILE__ ),
5
        array( 'jquery' ),
6
        MYPLUGIN_VERSION,
7
        true
8
    );
9
}
10
add_action( 'wp_enqueue_scripts', 'myplugin_frontend_scripts' );

MYPLUGIN_VERSION è la costante della versione del plugin. A ogni aggiornamento del plugin, il browser dell'utente riceve uno script fresco invece di uno vecchio in cache.

Per gli script di amministrazione (solo pannello admin), usate l'hook admin_enqueue_scripts. Anche nell'admin jQuery è registrato con lo stesso handle jquery.

⁉️🤔 Domande frequenti

Perché il mio codice jQuery non funziona anche se wp_enqueue_script è chiamato correttamente?

La causa più comune: il tema non chiama wp_head() e wp_footer(). Senza queste funzioni, WordPress non può fisicamente inserire i tag <script> nell'HTML. Aprite header.php. Dovrebbe esserci <?php wp_head(); ?> prima di </head>. In footer.php, dovrebbe esserci <?php wp_footer(); ?> prima di </body>. Se il tema è molto vecchio e queste chiamate mancano, aggiungetele. È sicuro. Tutti i temi e i plugin moderni si basano su wp_head/wp_footer. Senza di essi, non solo il caricamento degli script è rotto, ma anche i plugin SEO, i font e i dati strutturati.

Posso usare jQuery 4.0.0 in WordPress se il core distribuisce la 3.6.0?

Sì, tramite wp_deregister_script + wp_register_script (vedi la sezione sopra). Ma attenzione: jQuery 4.0.0 ha eliminato il supporto per IE 11 e diversi metodi deprecati. Se il vostro sito o plugin si basa su jQuery Migrate, attenetevi alla versione del core o includete Migrate esplicitamente. WordPress si sta gradualmente spostando verso JavaScript nativo e React per l'editor a blocchi, ma jQuery rimarrà nel core ancora a lungo: troppi temi e plugin ne dipendono.

Un plugin carica il proprio jQuery anche se l'ho già incluso tramite functions.php. Cosa devo fare?

Probabilmente il plugin ha inserito in modo rigido <script src="jquery..."> scavalcando wp_enqueue_script. È un errore del plugin. Due soluzioni: trovate la chiamata diretta nel codice del plugin e sostituitela con wp_enqueue_script con una dipendenza (se siete disposti a modificare il plugin), oppure contattate l'autore del plugin chiedendogli di correggerlo. Come workaround temporaneo, potete chiamare wp_dequeue_script o rimuovere l'hook del plugin, ma questo cura i sintomi anziché la causa.

Cosa è più veloce: jQuery dal core di WordPress o da una CDN?

Se il browser dell'utente ha già in cache jQuery da una CDN (Google o cdnjs), la versione CDN si carica istantaneamente con un codice 304 Not Modified. In caso contrario, la differenza di velocità di caricamento tra core e CDN è trascurabile per jQuery (circa 85 KB compressi). Per progetti ad alto traffico, una CDN fa risparmiare la banda del vostro server; per un tipico sito WordPress, non c'è differenza.

Dovreste abbandonare jQuery a favore del JS nativo

Risposta breve: dipende dal progetto. jQuery 4.0.0 compresso pesa circa 85 KB. Non è zero, ma non è nemmeno motivo di panico. Il JS nativo moderno (querySelectorAll, fetch e classList) copre il 90% di ciò per cui nel 2015 serviva jQuery. Se state costruendo un nuovo tema da zero e non dipendete da plugin jQuery, prendete in considerazione la vanilla JS. È più pulita e più veloce.

Ma se il progetto ha già dipendenze da jQuery (slider, gallerie, componenti UI di plugin), non complicatevi la vita. WordPress caricherà comunque jQuery quando un plugin lo richiede. Scrivete chiamate wp_enqueue_script pulite con le dipendenze, non interferite con la gestione dell'ordine di caricamento del core e jQuery funzionerà in modo veloce e prevedibile.

🔗 documentazione wp_enqueue_script | 🔗 documentazione wp_deregister_script