CSS e JavaScript personalizzati in PrestaShop senza compromettere gli aggiornamenti

Aggiornato a giugno 2026, i quattro metodi sicuri per gli aggiornamenti descritti qui sotto valgono da PrestaShop 1.7 fino alla 9 (pipeline SCSS di Hummingbird inclusa). Gli esempi di codice usano l'API register* per gli asset introdotta dalla 1.7.

Cambi il colore di un pulsante. Apri il foglio di stile del tema, lo modifichi, il pulsante ora è corretto. Tre settimane dopo aggiorni il tema per applicare una correzione di sicurezza e la tua modifica sparisce: sovrascritta in silenzio, senza avvisi e senza traccia di ciò che avevi toccato. Prima o poi ogni commerciante PrestaShop che personalizza il negozio modificando i file principali si scontra con questo problema, e la parte più frustrante è che si può evitare del tutto. La piattaforma offre diversi punti, al riparo dagli aggiornamenti, in cui inserire CSS e JavaScript personalizzati; il trucco è sapere quale scegliere in base alla modifica che devi fare e perché “modifica semplicemente il tema” finisce spesso per tradirti. Questa guida parla proprio di questo: dove può vivere il tuo codice personalizzato perché un aggiornamento del tema, del core o di un modulo non lo cancelli mai.

Perché modificare i file del tema e dei moduli è una trappola

Un tema PrestaShop è un insieme di file su disco: template Smarty (.tpl), fogli di stile e JavaScript, tutti sotto /themes/your-theme/. Quando aggiorni quel tema, che tu carichi di nuovo uno ZIP più recente o applichi una patch del fornitore, il processo di aggiornamento sostituisce quei file in blocco con la nuova versione. Non fonde le tue modifiche: le sovrascrive. Lo stesso vale per ogni modulo: i suoi asset si trovano in /modules/module-name/views/, e un aggiornamento del modulo sostituisce interamente quella directory. Niente diff, niente conferma, niente backup. Il tuo lavoro semplicemente sparisce e, poiché non compare alcun errore, spesso te ne accorgi solo quando lo nota un cliente.

Quindi cosa significa per te? Ogni ora passata a modificare file principali è un'ora che passerai di nuovo al prossimo aggiornamento, e “il prossimo aggiornamento” non è facoltativo, perché è così che arrivano nel tuo negozio correzioni di sicurezza e bug fix. Il senso dei metodi qui sotto è spezzare questo ciclo: scrivere la personalizzazione una volta sola, in un punto che il sistema di aggiornamento non tocca mai, e smettere di riapplicare lavoro perso.

Abbina il metodo alla modifica

Non esiste un unico modo “giusto” per aggiungere codice personalizzato: esiste il modo giusto per la tua modifica. Un ritocco di colore di una riga e un restyling visivo completo appartengono a posti completamente diversi. Scegli il metodo più leggero che sopravvive agli aggiornamenti e fa il lavoro:

Le sezioni seguenti spiegano ciascun metodo nel dettaglio specifico di PrestaShop. Due di questi argomenti hanno già guide dedicate, temi child e blocchi HTML dal back office, quindi, invece di ripeterne qui tutta la profondità, questo articolo resta concentrato sull'elemento che li accomuna tutti e quattro: mantenere il codice al sicuro dagli aggiornamenti.

Metodo 1, il file custom.css (per piccoli ritocchi CSS)

La maggior parte dei temi PrestaShop moderni include un file custom.css vuoto che il tema carica dopo tutti gli altri fogli di stile. Poiché viene caricato per ultimo, le tue regole prevalgono naturalmente nella cascata: per questo è un punto comodo per pochi ritocchi rapidi. Tieni però presente che custom.css di solito vive dentro l'albero del tema, quindi non è intrinsecamente protetto dagli aggiornamenti: uno ZIP del tema o un aggiornamento del fornitore può sostituirlo. Per una vera sicurezza negli aggiornamenti, inserisci le regole in un tema child o in un blocco di codice dal back office; riserva il custom.css del tema a ritocchi provvisori di colore, spaziatura o font che puoi permetterti di riapplicare.

Molti temi, inclusi quelli in stile Classic (Classic è il tema predefinito di PrestaShop 8), caricano /themes/your-theme/assets/css/custom.css; anche il tema più recente Hummingbird è un'opzione moderna. Ma il supporto a custom.css e il suo percorso esatto dipendono dal tema, quindi non darlo per scontato come comportamento nativo universale: alcuni temi più vecchi o commerciali usano invece /themes/your-theme/css/custom.css, e una minoranza non lo collega affatto. Verifica la registrazione degli asset del tema attivo o la sua documentazione e cerca un custom.css già esistente (spesso vuoto) prima di crearne uno. Inserisci le tue regole, per esempio un override del pulsante principale come .btn-primary { background-color: #2c3e50; border-color: #2c3e50; }, svuota la cache e hai finito.

Conoscine i limiti prima di farci affidamento. custom.css è solo CSS: niente JavaScript. Viene caricato su ogni pagina, che la regola serva lì oppure no, e non ti offre alcun modo per puntare a un tipo di pagina, a un gruppo clienti o a un negozio specifico. Inoltre una minoranza di temi non lo collega affatto. Per pochi ritocchi questi limiti non contano; appena iniziano a pesare, passa a uno dei metodi qui sotto.

Metodo 2, un tema child (per personalizzazioni importanti e continuative)

Quando fai più di una manciata di modifiche, modificare template, ridisegnare intere sezioni, aggiungere il tuo JavaScript, un tema child è la sede al riparo dagli aggiornamenti per tutto questo lavoro. Un tema child eredita tutto dal parent e ti permette di sovrascrivere solo i file specifici che ti interessano, in una directory separata che gli aggiornamenti del parent non possono raggiungere. Fai puntare un config/theme.yml al parent (con la chiave parent: che indica la cartella del tema parent), copi solo i file che vuoi sovrascrivere e aggiungi accanto a essi il tuo custom.css e i tuoi file .js.

Questa è la risposta corretta per una personalizzazione seria, ed è un argomento abbastanza ampio da meritare una guida dedicata invece di un paragrafo frettoloso, compreso il motivo fondamentale per cui si crea un tema child invece di modificare direttamente il parent. Lo abbiamo spiegato in modo completo in temi child in PrestaShop: perché non dovresti mai modificare il tema parent. Se non hai ancora scelto il tema da personalizzare, fai un passo indietro e parti da come scegliere il tema PrestaShop giusto per la tua attività: un parent adatto ai temi child ti risparmia molti problemi in seguito.

Metodo 3, inserire codice dal back office (senza accesso ai file)

I blocchi del back office tengono piccoli snippet HTML, CSS e JavaScript fuori dai file del tema.

Se non hai accesso SSH o FTP, non lo vuoi, o semplicemente non vuoi ridistribuire file per uno snippet di tracciamento di una riga, un modulo per blocchi di codice ti permette di aggiungere CSS, JavaScript e HTML personalizzati direttamente dal back office di PrestaShop. Il codice vive nel database invece che in un file del tema o di un modulo: proprio per questo un aggiornamento del tema o del core non può toccarlo, e proprio per questo puoi disattivare un blocco per annullarne l'effetto all'istante, senza eliminare nulla.

È lo strumento quotidiano per aggiungere uno script di Google Analytics o Meta Pixel, inserire un override CSS stagionale nell'head della pagina o posizionare un banner promozionale, e merita una guida propria invece di un paragrafo qui. La trovi in blocchi HTML: aggiungere contenuti personalizzati ovunque nel tuo negozio PrestaShop, dove spieghiamo come assegnare i blocchi agli hook e mostrarli solo sulle pagine o ai gruppi clienti che scegli. Il nostro modulo mprhtmlblocks è costruito esattamente per questo: codice personalizzato, gestito dal back office, agganciato agli hook e mostrato in modo condizionale, senza nulla che il prossimo aggiornamento possa sovrascrivere.

Metodo 4, un piccolo modulo personalizzato con hook per gli asset (per sviluppatori)

Per gli sviluppatori, la sede più pulita e controllabile per gli asset personalizzati è un piccolo modulo che li registra tramite la pipeline asset nativa di PrestaShop. È completamente indipendente dal tema: non c'è nulla nell'albero del tema da sovrascrivere, quindi sopravvive sia ai cambi di tema sia agli aggiornamenti del core, e sblocca il caricamento condizionale che non puoi ottenere con custom.css.

Il lavoro avviene in un solo hook, hookActionFrontControllerSetMedia(). Al suo interno chiami registerStylesheet() e registerJavascript() sul controller, passando un id asset, il percorso dentro il modulo e un array di opzioni. Quelle opzioni sono il vantaggio rispetto alle vecchie chiamate addCSS() / addJS() dell'epoca 1.6: una priority (numeri più alti caricano più tardi, ed è così che garantisci che il tuo script venga eseguito dopo quello del tema), una query media, una position JS impostata su bottom e gli attributi async/defer. Su PrestaShop 1.7 e versioni successive, preferisci i metodi register*; ricorri ad addCSS/addJS solo quando mantieni un negozio 1.6.

public function install()
{
    return parent::install()
        && $this->registerHook('actionFrontControllerSetMedia');
}

public function hookActionFrontControllerSetMedia($params)
{
    if (!$this->context->controller instanceof ProductController) {
        return;
    }

    $this->context->controller->registerStylesheet(
        'module-' . $this->name . '-product',
        'modules/' . $this->name . '/views/css/product.css',
        ['media' => 'all', 'priority' => 200]
    );

    $this->context->controller->registerJavascript(
        'module-' . $this->name . '-product',
        'modules/' . $this->name . '/views/js/product.js',
        ['position' => 'bottom', 'priority' => 200]
    );
}

Il bug della query string di addCSS da conoscere

C'è una vecchia insidia per cui addCSS(), usato con una query string per invalidare la cache (qualcosa come ?v=1.2.3), può produrre un percorso che PrestaShop altera male: il foglio di stile compare nel sorgente della pagina, ma il browser non lo applica mai. È una di quelle cose esasperanti da debuggare perché non genera nessun 404. Se usi il cache busting per i tuoi asset, usa registerStylesheet(), che gestisce correttamente il versioning.

Caricamento condizionale: solo dove serve

Il vero motivo per cui gli sviluppatori scelgono un modulo è il caricamento condizionale. Dentro lo stesso hook puoi ispezionare $this->context->controller e registrare gli asset solo quando corrisponde: per esempio controllando instanceof ProductController prima di aggiungere CSS per la pagina prodotto, oppure instanceof OrderController prima di aggiungere JavaScript per il pagamento. Il vantaggio è concreto: il tuo codice personalizzato resta fuori dal 90% delle pagine che non ne hanno bisogno, quindi non lo paghi nel tempo di caricamento di ogni pagina. Lo stesso principio, caricare leggero, caricare tardi, è ciò che mantiene veloce un negozio personalizzato, ed è lo spirito con cui piccoli ritocchi front-end come un pulsante “torna su” vengono forniti come asset condizionali corretti invece che come script inline buttato dentro un template.

JavaScript richiede più attenzione del CSS

Il CSS raramente si ribella; JavaScript sì. Due elementi causano la maggior parte dei problemi. Primo, jQuery: PrestaShop 1.7+ include jQuery 3.x nel front office, quindi se il tuo script dipende da jQuery, assegnagli una priorità abbastanza alta da caricarlo dopo jQuery, altrimenti vedrai "$ is not defined" al primo rendering. Il back office è un mondo a parte (le versioni più vecchie avevano jQuery 1.x, quelle più nuove 3.x), quindi controlla il sorgente della pagina prima di scrivere script lato amministrazione dando per scontata una versione.

Secondo, ed è la regola che molti vorrebbero infrangere: non inserire mai un tag <script> grezzo dentro un template Smarty. Sembra una scorciatoia, ma uno script inline aggira la gestione degli asset di PrestaShop: non verrà gestito né combinato dal CCC (Combine, Compress, Cache) e può entrare in conflitto con la Content Security Policy nei negozi che impostano un header CSP. Distribuisci sempre JavaScript come file .js esterno registrato tramite l'hook corretto. Quanto alla sintassi moderna, arrow function, async/await, moduli ES, va bene su PrestaShop 8 e 9, dove IE11 non è più un problema; se supporti ancora negozi 1.7 con traffico da browser vecchi, potresti dover transpilarlo con Babel.

Quando il CSS personalizzato “non funziona”: specificità

La situazione più comune in assoluto, “il mio CSS personalizzato viene ignorato”, non è affatto un problema di aggiornamenti: è specificità. La tua regola viene caricata correttamente, ma il selettore del tema è più specifico, quindi il browser applica quello del tema. La soluzione, in ordine di preferenza:

• Fai corrispondere il selettore del tema. Apri gli strumenti di sviluppo, trova il selettore esatto usato dal tema e scrivi il tuo in modo che corrisponda. Poiché custom.css viene caricato per ultimo, un selettore di pari specificità vince già.
• Aggiungi un parent per aumentare il peso. Se la corrispondenza non basta, limita l'ambito: #wrapper .btn-primary batte un semplice .btn-primary senza ricorrere alla forza bruta.
• Usa !important solo come vero ultimo rimedio. Funziona, ma ogni !important che aggiungi rende più difficile il prossimo override e ti ritrovi in una corsa alla specificità che il tuo io futuro dovrà districare.

Test: perché “ho cambiato qualcosa e non è successo nulla”

Le modifiche a CSS e JS personalizzati che sembrano non produrre alcun effetto sono quasi sempre causate da un livello di cache, non dal tuo codice. Procedi in quest'ordine:

• Svuota la cache di PrestaShop. Vai in Parametri avanzati → Prestazioni e fai clic su Svuota cache dopo ogni modifica. Mentre sviluppi template, imposta Forza compilazione su Sì, così Smarty rigenera l'output.
• Attenzione al CCC. Con Combine, Compress, Cache abilitato, i singoli file vengono uniti in bundle, e questo può cambiare l'ordine di caricamento. Se qualcosa si comporta in modo strano, disabilita temporaneamente il CCC per isolarlo, poi riabilitalo per la produzione.
• Usa il browser. La scheda Network conferma che il file sia stato davvero caricato (200, non 404); la scheda Elements mostra se la regola viene applicata o barrata da una più specifica.
• Svuota la CDN. Se usi Cloudflare o un'altra CDN, svuotala dopo le modifiche agli asset: copie edge obsolete sono dietro una quota enorme di segnalazioni del tipo “ma l'ho già cambiato”.

La versione breve

• Non modificare mai direttamente i file del tema o dei moduli: il prossimo aggiornamento li sovrascrive senza avviso.
• 1-5 piccoli ritocchi CSS: inseriscili in custom.css.
• Modifiche importanti e continuative: crea un tema child.
• Nessun accesso ai file o snippet rapidi: usa un blocco HTML/codice dal back office.
• Sviluppatore, caricamento condizionale: un piccolo modulo con registerStylesheet() / registerJavascript().
• Distribuisci il JS come file esterni, caricalo in fondo, svuota ogni cache dopo le modifiche e conserva un backup delle personalizzazioni fuori dalla directory del tema.

Personalizzare PrestaShop e sopravvivere agli aggiornamenti non sono obiettivi in conflitto: sembrano esserlo solo quando il tuo codice vive nel posto sbagliato. Scegli il metodo più leggero e sicuro per gli aggiornamenti in base alla modifica che hai davanti, e l'aggiornamento di un tema torna a essere ciò che dovrebbe: un clic di routine, non una giornata passata a riapplicare lavoro perso. Se preferisci gestire il codice personalizzato dal back office invece di toccare file, il nostro modulo mprhtmlblocks ti permette di inserire e attivare/disattivare blocchi HTML, CSS e JavaScript uno per uno: salvati nel database, intoccati dal prossimo aggiornamento.

Domande frequenti

Il file custom.css del tema è davvero al riparo dagli aggiornamenti?

Non del tutto. Poiché custom.css di solito vive dentro l'albero del tema, uno ZIP del tema o un aggiornamento del fornitore può sostituirlo insieme a tutto il resto. È comodo: viene caricato per ultimo, quindi le tue regole prevalgono nella cascata, ma trattalo come il posto per ritocchi provvisori che puoi permetterti di riapplicare. Per una vera sicurezza negli aggiornamenti, metti le regole in un tema child o in un blocco di codice dal back office, dove il sistema di aggiornamento non può raggiungerle.

Il mio CSS personalizzato viene caricato, ma lo stile del tema prevale ancora. Cosa c'è che non va?

È un problema di specificità, non di aggiornamenti o cache. Il selettore del tema è più specifico del tuo, quindi il browser applica quello del tema. Apri gli strumenti di sviluppo, trova il selettore esatto usato dal tema e scrivi il tuo in modo che corrisponda: poiché custom.css viene caricato per ultimo, un selettore equivalente vince già. Aggiungi un parent di ambito come #wrapper solo se la corrispondenza non basta, e ricorri a !important solo come vero ultimo rimedio.

Posso semplicemente incollare un tag <script> in un template?

No. Uno script inline aggira la gestione degli asset di PrestaShop, quindi non verrà combinato dal CCC, e può rompersi nei negozi che impostano un header Content Security Policy. Distribuisci sempre JavaScript come file .js esterno registrato tramite hookActionFrontControllerSetMedia() con registerJavascript(), oppure tramite un blocco di codice dal back office: mai come markup grezzo in un .tpl.

Come carico il mio CSS o JS solo su determinate pagine?

È il motivo principale per usare un piccolo modulo invece di custom.css. Dentro hookActionFrontControllerSetMedia(), ispeziona $this->context->controller e registra l'asset solo quando corrisponde: per esempio instanceof ProductController per il CSS della pagina prodotto, oppure instanceof OrderController per il JS del pagamento. Così il tuo codice resta fuori dalle pagine che non ne hanno bisogno, e non lo paghi a ogni caricamento pagina.

Perché il mio script genera "$ is not defined"?

Il tuo JavaScript viene eseguito prima che jQuery sia stato caricato. PrestaShop 1.7+ include jQuery 3.x nel front office, quindi assegna al tuo script una priority abbastanza alta in registerJavascript() da farlo caricare dopo jQuery. Il back office è un mondo separato, le versioni più vecchie avevano jQuery 1.x, quindi controlla il sorgente della pagina prima di scrivere script lato amministrazione dando per scontata una versione.

Ho cambiato il CSS e non è successo nulla. Dove guardo?

Quasi sempre in un livello di cache, non nel tuo codice. Procedi in ordine: svuota la cache di PrestaShop da Parametri avanzati → Prestazioni; disabilita temporaneamente il CCC (Combine, Compress, Cache) se l'ordine di caricamento sembra sbagliato; verifica nella scheda Network del browser che il file sia stato caricato con 200, non con 404; e svuota la CDN (Cloudflare e simili): copie edge obsolete causano una quota enorme di segnalazioni del tipo “ma l'ho già cambiato”.

Dovrei usare ancora addCSS() e addJS()?

Solo su un negozio 1.6. Su PrestaShop 1.7 e versioni successive, preferisci registerStylesheet() e registerJavascript(): ti danno priorità, media query, posizione in fondo per il JS e async/defer, e gestiscono correttamente il versioning per il cache busting. Il vecchio addCSS() ha un bug di lunga data per cui una query string ?v= può alterare il percorso in modo che il file appaia nel sorgente ma non venga mai applicato, senza alcun 404 ad avvisarti.

Guide correlate

• Temi child in PrestaShop: perché non dovresti mai modificare il tema parent
• Blocchi HTML: aggiungere contenuti personalizzati ovunque nel tuo negozio PrestaShop
• Pulsante Torna su: un piccolo dettaglio UX sorprendentemente importante