SCRIPT_DEBUG: cosa abilita

SCRIPT_DEBUG è una costante di debug spesso ignorata, ma fondamentale per chi sviluppa temi e plugin con interazioni JavaScript complesse. Vediamo cosa attiva esattamente e quando attivarla per non rovinare le performance.

Cosa fa SCRIPT_DEBUG

Quando SCRIPT_DEBUG=true, WordPress carica le versioni non minificate dei file JS e CSS del core: invece di common.min.js viene incluso common.js. Così' puoi debuggare stack trace JS con nomi funzioni leggibili e variabili non rinominate. La maggior parte dei plugin moderni segue la stessa convenzione: se SCRIPT_DEBUG è true, caricano la versione 'sorgentè.

Impatto sulle performance

I file non minificati pesano in media 3-5x di più rispetto ai minified, con effetto su TTFB e largest contentful paint. Su frontend questo significa pagine fino al 30% più lente per first paint. Per questo SCRIPT_DEBUG va attivato SOLO in dev/staging, mai in produzione.

Casi d’uso tipici

1) Debug errore JS proveniente da core o plugin (vedi stack trace umano), 2) sviluppo di feature che usa jQuery UI o React WordPress (Gutenberg), 3) test di compatibilità tra plugin che caricano librerie comuni in versioni diverse. WP Error Monitor cattura errori JS lato client se attivi lo snippet front-end: avere SCRIPT_DEBUG attivo aiuta a leggere meglio le segnalazioni.

Conflitti jQuery e dipendenze

WordPress include jQuery in versione 'noConflict mode'. Plugin che includono jQuery diversa creano conflitti. Con SCRIPT_DEBUG=true vedi tutte le versioni caricate nel network tab DevTools: spesso scopri jQuery 1.x + 3.x in stessa pagina. Soluzione: configura wp_deregister_script + wp_register_script per forzare una sola versione. WP Error Monitor cattura errori JavaScript correlati (es. variable not a function) con stack trace lato browser.

Source map per asset minified

Anche in produzione con minified, puoi includere source map (.map file accanto al .min.js) che permette debug con codice originale. Plugin moderni li includono; per custom, configura webpack/gulp per generarli. Server side, esponi i .map solo via header CSP o IP whitelist (non vuoi che competitor vedano source). WP Error Monitor JS snippet supporta source map per stack trace umani anche in prod.

Async e defer per JS performance

Anche con SCRIPT_DEBUG=false (minified), gli script JS possono bloccare il rendering. WP_enqueue_script supporta args 'in_footer' true (carica in fondo, non blocca head) e tramite filter script_loader_tag puoi aggiungere async o defer. Async: scarica parallel, esegue appena pronto (anche prima DOM ready, attenzione). Defer: scarica parallel, esegue dopo HTML parsato (sicuro). Best practice: async per analytics indipendenti, defer per script che dipendono da DOM. WP Error Monitor traccia tempo di blocco asset (TBT) come metric: se TBT > 200ms su mobile, optimization necessaria.

Webpack/Vite per bundling moderno

Per progetti custom serio, abbandona il modello classico WP wp_enqueue_script di tanti file separati a favore di bundling con Webpack o Vite. Vantaggi: code splitting (carica solo ciò che serve per pagina), tree shaking (elimina codice non usato), source map per debug, hot module replacement in dev, asset hashing per cache busting. Setup: package.json con dipendenze, webpack.config.js, build script in CI/CD che genera bundle minified. WordPress includi solo i bundle finali. Riduzione tipica peso JS: 40-70%. WP Error Monitor identifica via source map quale source file ha generato l’errore.

Bilanciamento performance vs debug

Il bilanciamento performance vs debug deve essere consapevole: SCRIPT_DEBUG raddoppia peso JS/CSS, SAVEQUERIES aggiunge 30% memoria PHP, WP_DEBUG enableled aggiunge ~5% overhead. In produzione vuoi questi off, ma sai che se serve debug devi accenderli temporaneamente. Strategia: setup 'debug mode' che si attiva via query string token solo per IP team (es. ?wpem_debug=TOKEN), abilita SAVEQUERIES e WP_DEBUG_LOG verbose solo per quella richiesta. Così' utenti normali hanno performance piene, team può debuggare in prod sicuro. WP Error Monitor include questa feature out-of-the-box.

Procedura passo-passo

1. Apri wp-config.php del sito di sviluppo.
2. Aggiungi: define('SCRIPT_DEBUG', true);
3. Svuota cache browser e CDN se presente.
4. Carica una pagina e ispeziona Network tab: i file devono essere .js non .min.js.
5. Riproduci l’errore JS che vuoi debuggare.
6. Apri console DevTools per leggere lo stack trace umano.
7. A debug completato, rimuovi SCRIPT_DEBUG o impostalo false.
8. Identifica versioni jQuery multiple con SCRIPT_DEBUG=true.
9. Configura wp_deregister/wp_register_script per consolidare.

Errori comuni e come risolverli

• Plugin continua a caricare versione minified: Il plugin non rispetta la convenzione: serve patch o segnalazione all’autore.
• Performance staging troppo lente: Normale: SCRIPT_DEBUG raddoppia peso asset. Disattiva quando non serve.
• Conflitti tra librerie: SCRIPT_DEBUG espone vere versioni: utile per identificare versioni jQuery duplicate.
• jQuery dollar non definito: Plugin in conflict mode: usa jQuery(document).ready() esplicito.
• Source map espone codice: Restrici accesso con location specifica e allow IP team in nginx.

Domande frequenti

D: Posso usare SCRIPT_DEBUG con cache page (WP Rocket)?
R: Sì, ma svuota cache dopo modifica wp-config.php.

D: Impatta gli asset di tema/plugin?
R: Solo se rispettano la convenzione: dipende dall’autore.

D: WP Error Monitor traccia errori JS solo con SCRIPT_DEBUG?
R: No, indipendente: ma con SCRIPT_DEBUG i messaggi sono più leggibili.

D: SCRIPT_DEBUG cambia versioni jQuery?
R: No, carica solo versioni non minified: stessa versione.

D: Source map produzione, posso?
R: Sì con cautela: utile per debug, esponi solo team.

Hai bisogno di aiuto?

Se vuoi affidare il monitoraggio WordPress al team di G Tech Group, scrivici tramite il modulo di contatto.