Eigenes CSS und JavaScript in PrestaShop ohne Update-Probleme

Aktualisiert im Juni 2026, die vier unten beschriebenen update-sicheren Methoden gelten für PrestaShop 1.7 bis 9 (einschließlich Hummingbirds SCSS-Pipeline). Die Codebeispiele verwenden die register*-Asset-API ab 1.7.

Sie ändern die Farbe eines Buttons. Sie öffnen das Stylesheet des Themes, bearbeiten es, und der Button sieht korrekt aus. Drei Wochen später aktualisieren Sie das Theme, um eine Sicherheitslücke zu schließen, und Ihre Änderung ist weg, still überschrieben, ohne Warnung und ohne Aufzeichnung dessen, was Sie angepasst hatten. Jeder PrestaShop-Händler, der Anpassungen direkt in Core-Dateien vornimmt, läuft früher oder später gegen diese Wand. Das Ärgerliche daran: Es ist komplett vermeidbar. Die Plattform bietet mehrere update-sichere Orte für eigenes CSS und JavaScript; entscheidend ist nur zu wissen, welcher Ort zur jeweiligen Änderung passt und warum „einfach das Theme bearbeiten“ im Hintergrund scheitert. Genau darum geht es in diesem Leitfaden: Wo Ihr eigener Code liegen sollte, damit ihn weder ein Theme-Update noch ein Core-Upgrade oder ein Modul-Update jemals löscht.

Warum das Bearbeiten von Theme- und Moduldateien eine Falle ist

Ein PrestaShop-Theme ist eine Sammlung von Dateien auf dem Server: Smarty-Templates (.tpl), Stylesheets und JavaScript, alles unter /themes/your-theme/. Wenn Sie dieses Theme aktualisieren, egal ob Sie eine neue ZIP-Datei hochladen oder einen Hersteller-Patch einspielen, ersetzt der Update-Prozess diese Dateien vollständig durch die neue Version. Er führt Ihre Änderungen nicht zusammen; er überschreibt sie. Dasselbe gilt für jedes Modul: Seine Assets liegen in /modules/module-name/views/, und ein Modul-Update ersetzt dieses Verzeichnis vollständig. Kein Diff, keine Rückfrage, kein Backup. Ihre Arbeit ist einfach weg, und weil kein Fehler angezeigt wird, merken Sie es oft erst, wenn ein Kunde es bemerkt.

Was bedeutet das für Sie? Jede Stunde, die Sie in Core-Dateien investieren, investieren Sie beim nächsten Update erneut, und „das nächste Update“ ist nicht optional, denn genau so erreichen Sicherheits- und Fehlerbehebungen Ihren Shop. Der Zweck der folgenden Methoden ist, diesen Kreislauf zu durchbrechen: Schreiben Sie Ihre Anpassung einmal an eine Stelle, die der Updater nie anfasst, und hören Sie auf, verlorene Arbeit immer wieder neu einzupflegen.

Die Methode muss zur Änderung passen

Es gibt nicht den einen „richtigen“ Weg, eigenen Code einzubinden. Es gibt den richtigen Weg für Ihre Änderung. Eine einzeilige Farbanpassung und ein vollständiger visueller Umbau gehören an völlig unterschiedliche Stellen. Wählen Sie die leichteste Methode, die Updates übersteht und die Aufgabe sauber erledigt:

Die folgenden Abschnitte behandeln jede Methode mit PrestaShop-spezifischen Details. Zwei dieser Methoden berühren Themen, für die es eigene ausführliche Leitfäden gibt, Child-Themes und HTML-Blöcke im Backoffice. Statt diese Tiefe hier zu wiederholen, konzentriert sich dieser Artikel auf den gemeinsamen Kern aller vier Ansätze: Ihren Code update-sicher zu halten.

Methode 1, die custom.css-Datei (für kleine CSS-Anpassungen)

Die meisten modernen PrestaShop-Themes bringen eine leere custom.css-Datei mit, die das Theme nach allen anderen Stylesheets lädt. Weil sie zuletzt geladen wird, gewinnen Ihre Regeln in der Kaskade automatisch. Das macht sie zu einem bequemen Ort für ein paar schnelle Anpassungen. Beachten Sie aber: custom.css liegt meist im Theme-Verzeichnis und ist daher nicht von sich aus update-sicher. Eine Theme-ZIP oder ein Hersteller-Update kann sie ersetzen. Für echte Update-Sicherheit gehören Ihre Regeln in ein Child-Theme oder einen Code-Block im Backoffice; reservieren Sie die themeeigene custom.css für austauschbare Farb-, Abstands- oder Schriftanpassungen, die Sie notfalls erneut einpflegen können.

Viele Themes, darunter Classic-artige Themes (Classic ist der Standard in PrestaShop 8), laden /themes/your-theme/assets/css/custom.css; das neuere Hummingbird-Theme ist eine weitere moderne Option. Die Unterstützung für custom.css und der genaue Pfad hängen jedoch vom Theme ab. Gehen Sie also nicht davon aus, dass es überall natives Standardverhalten ist, einige ältere oder kommerzielle Themes verwenden stattdessen /themes/your-theme/css/custom.css, und eine Minderheit bindet sie gar nicht ein. Prüfen Sie die Asset-Registrierung oder Dokumentation des aktiven Themes und suchen Sie nach einer vorhandenen, oft leeren custom.css, bevor Sie selbst eine anlegen. Fügen Sie Ihre Regeln dort ein, zum Beispiel einen Override für den primären Button wie .btn-primary { background-color: #2c3e50; border-color: #2c3e50; }, leeren Sie den Cache, und die Änderung ist aktiv.

Kennen Sie die Grenzen, bevor Sie sich darauf verlassen. custom.css ist nur CSS, kein JavaScript. Sie wird auf jeder Seite geladen, ob die Regel dort gebraucht wird oder nicht, und sie bietet keine Möglichkeit, gezielt einen bestimmten Seitentyp, eine Kundengruppe oder einen Shop anzusprechen. Außerdem bindet eine Minderheit von Themes sie gar nicht ein. Für ein paar Anpassungen spielen diese Grenzen keine Rolle; sobald sie relevant werden, wechseln Sie zu einer der folgenden Methoden.

Methode 2, ein Child-Theme (für umfangreiche, fortlaufende Anpassungen)

Wenn Sie mehr als nur eine Handvoll Änderungen vornehmen, Templates bearbeiten, ganze Bereiche neu gestalten, eigenes JavaScript ergänzen, ist ein Child-Theme der update-sichere Ort dafür. Ein Child-Theme erbt alles vom Parent-Theme und erlaubt Ihnen, nur die konkreten Dateien zu überschreiben, die Sie wirklich anpassen möchten, und zwar in einem separaten Verzeichnis, das Parent-Updates nicht erreichen. Sie verweisen in config/theme.yml auf das Parent-Theme (über den Schlüssel parent:, der den Ordner des Parent-Themes nennt), kopieren nur die Dateien hinein, die Sie überschreiben, und legen Ihre eigene custom.css und .js daneben ab.

Für ernsthafte Anpassungen ist das die richtige Antwort, und das Thema ist wichtig genug für einen eigenen ausführlichen Beitrag statt eines gehetzten Absatzes, einschließlich des entscheidenden Grundes, warum Sie ein Child-Theme erstellen sollten, statt direkt am Parent zu arbeiten. Das behandeln wir vollständig in Child-Themes in PrestaShop: warum Sie niemals das Parent-Theme bearbeiten sollten. Wenn Sie das Theme, das Sie anpassen möchten, noch nicht ausgewählt haben, beginnen Sie einen Schritt früher mit So wählen Sie das richtige PrestaShop-Theme für Ihr Geschäft, ein child-theme-freundliches Parent-Theme erspart Ihnen später viel Ärger.

Methode 3, Code aus dem Backoffice einfügen (ohne Dateizugriff)

Backoffice-Blöcke halten kleine HTML-, CSS- und JavaScript-Snippets aus Theme-Dateien heraus.

Wenn Sie keinen SSH- oder FTP-Zugang haben, ihn nicht möchten oder für ein einzeiliges Tracking-Snippet einfach keine Dateien neu bereitstellen wollen, können Sie mit einem Code-Block-Modul eigenes CSS, JavaScript und HTML direkt aus dem PrestaShop-Backoffice einfügen. Der Code liegt in der Datenbank statt in einer Theme- oder Moduldatei. Genau deshalb kann ihn ein Theme-Update oder Core-Upgrade nicht berühren, und genau deshalb können Sie einen Block deaktivieren, um seine Wirkung sofort zurückzunehmen, ohne etwas zu löschen.

Das ist das Alltagswerkzeug, um ein Google-Analytics- oder Meta-Pixel-Skript einzubinden, einen saisonalen CSS-Override im Seitenkopf zu platzieren oder ein Promo-Banner einzufügen, und es verdient einen eigenen Leitfaden statt nur eines Absatzes hier. Wir zeigen den Ablauf in HTML-Blöcke: eigene Inhalte überall in Ihrem PrestaShop-Shop einfügen. Dort geht es darum, Blöcke Hooks zuzuweisen und sie nur auf den Seiten oder für die Kundengruppen anzuzeigen, die Sie auswählen. Unser eigenes mprhtmlblocks-Modul ist genau dafür gebaut: eigener Code, verwaltet aus dem Backoffice, gezielt an Hooks gebunden und bedingt angezeigt, ohne dass beim nächsten Update etwas überschrieben werden kann.

Methode 4, ein kleines eigenes Modul mit Asset-Hooks (für Entwickler)

Für Entwickler ist ein kleines Modul, das Assets über PrestaShops eigene Asset-Pipeline registriert, der sauberste und am besten kontrollierbare Ort für eigene Dateien. Es ist vollständig theme-unabhängig, im Theme-Verzeichnis gibt es nichts zu überschreiben, und übersteht daher sowohl Theme-Wechsel als auch Core-Upgrades. Außerdem ermöglicht es bedingtes Laden, das Sie mit custom.css nicht bekommen.

Die Arbeit passiert in einem einzigen Hook: hookActionFrontControllerSetMedia(). Darin rufen Sie registerStylesheet() und registerJavascript() am Controller auf und übergeben eine Asset-ID, den Pfad innerhalb Ihres Moduls und ein Options-Array. Diese Optionen sind der Vorteil gegenüber den älteren Aufrufen addCSS() / addJS() aus der 1.6-Ära: eine priority (höhere Zahlen laden später, wodurch Sie sicherstellen, dass Ihr Skript nach dem Theme-Skript läuft), eine media-Query, eine JS-position von bottom sowie async/defer-Attribute. Ab PrestaShop 1.7 sollten Sie die register*-Methoden bevorzugen; addCSS/addJS verwenden Sie nur noch, wenn Sie einen 1.6-Shop warten.

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]
    );
}

Der addCSS-Query-String-Bug, den Sie kennen sollten

Es gibt eine seit Langem bekannte Stolperfalle: addCSS() mit einem Cache-Busting-Query-String (etwa ?v=1.2.3) kann einen Pfad erzeugen, den PrestaShop so verändert, dass das Stylesheet zwar im Seitenquelltext erscheint, der Browser es aber nie anwendet. Das ist extrem mühsam zu debuggen, weil nichts mit 404 fehlschlägt. Wenn Sie Ihre Assets per Cache-Busting versionieren, verwenden Sie registerStylesheet(); diese Methode behandelt die Versionierung korrekt.

Bedingtes Laden. Nur dort, wo es gebraucht wird

Der eigentliche Grund, warum Entwickler zu einem Modul greifen, ist bedingtes Laden. Im selben Hook können Sie $this->context->controller prüfen und Assets nur dann registrieren, wenn es passt, zum Beispiel mit instanceof ProductController, bevor Sie CSS für Produktseiten hinzufügen, oder mit instanceof OrderController, bevor Sie JavaScript für die Kasse einbinden. Der Vorteil ist konkret: Ihr eigener Code bleibt von den 90% der Seiten fern, die ihn nicht brauchen, sodass Sie ihn nicht bei jedem Seitenaufruf mitbezahlen. Dasselbe Prinzip, schlank laden, spät laden, hält einen angepassten Shop schnell. Es steckt auch hinter kleinen Frontend-Details wie einem Back-to-Top-Button, die als saubere bedingte Assets ausgeliefert werden sollten, statt als Inline-Skript in ein Template geworfen zu werden.

JavaScript braucht mehr Sorgfalt als CSS

CSS wehrt sich selten; JavaScript kann es. Zwei Dinge verursachen die meisten Probleme. Erstens jQuery: PrestaShop 1.7+ liefert im Frontoffice jQuery 3.x aus. Wenn Ihr Skript also von jQuery abhängt, geben Sie ihm eine ausreichend hohe Priorität, damit es nach jQuery geladen wird, sonst sehen Sie beim ersten Rendern „$ is not defined“. Das Backoffice ist eine eigene Welt (ältere Versionen hatten jQuery 1.x, neuere 3.x), prüfen Sie daher den Seitenquelltext, bevor Sie Admin-Skripte gegen eine angenommene Version schreiben.

Zweitens, und das ist die Regel, die viele am liebsten brechen würden: Setzen Sie niemals ein rohes <script>-Tag in ein Smarty-Template. Es wirkt schnell, aber ein Inline-Skript umgeht PrestaShops Asset-Management. Es wird nicht von CCC (Combine, Compress, Cache) verwaltet oder zusammengeführt, und kann mit Content Security Policy kollidieren, wenn ein Shop einen CSP-Header setzt. Liefern Sie JavaScript immer als externe .js-Datei aus, die über den passenden Hook registriert wird. Was moderne Syntax angeht. Arrow Functions, async/await, ES-Module. Ist das in PrestaShop 8 und 9 unproblematisch, weil IE11 dort keine Rolle mehr spielt; wenn Sie noch 1.7-Shops mit Traffic aus alten Browsern unterstützen, müssen Sie gegebenenfalls mit Babel transpilieren.

Wenn eigenes CSS „nicht funktioniert“: Spezifität

Der häufigste Fall von „mein eigenes CSS wird ignoriert“ ist überhaupt kein Update-Problem, es ist Spezifität. Ihre Regel wird korrekt geladen, aber der Selektor des Themes ist spezifischer, deshalb verwendet der Browser die Theme-Regel. Die Lösung, in der empfohlenen Reihenfolge:

• Den Selektor des Themes übernehmen. Öffnen Sie die Entwicklertools, finden Sie den exakten Selektor, den das Theme verwendet, und schreiben Sie Ihren passend dazu. Da custom.css zuletzt lädt, gewinnt ein gleich spezifischer Selektor bereits.
• Einen übergeordneten Selektor für mehr Gewicht hinzufügen. Wenn das Angleichen nicht reicht, begrenzen Sie den Geltungsbereich, #wrapper .btn-primary schlägt ein reines .btn-primary, ohne brachiale Mittel zu verwenden.
• !important nur als echten letzten Ausweg nutzen. Es funktioniert, aber jedes !important, das Sie hinzufügen, macht den nächsten Override schwieriger. Am Ende landen Sie in einem Spezifitäts-Wettrüsten, das Ihr zukünftiges Ich wieder entwirren muss.

Testen: warum „Ich habe es geändert und nichts ist passiert“

Eigene CSS- und JS-Änderungen, die scheinbar nichts bewirken, scheitern fast immer an einer Cache-Schicht, nicht an Ihrem Code. Gehen Sie diese Punkte der Reihe nach durch:

• Leeren Sie den PrestaShop-Cache. Gehen Sie zu Erweiterte Einstellungen → Leistung und klicken Sie nach jeder Änderung auf Cache leeren. Während Sie Templates entwickeln, setzen Sie Kompilierung erzwingen auf Ja, damit Smarty neu rendert.
• Achten Sie auf CCC. Wenn Combine, Compress, Cache aktiviert ist, werden Ihre einzelnen Dateien zu Bundles zusammengeführt. Das kann die Ladereihenfolge verändern. Wenn sich etwas seltsam verhält, deaktivieren Sie CCC vorübergehend, um die Ursache einzugrenzen, und aktivieren Sie es anschließend wieder für den Produktivbetrieb.
• Nutzen Sie den Browser. Der Network-Tab bestätigt, dass Ihre Datei tatsächlich geladen wurde (200, nicht 404); der Elements-Tab zeigt, ob Ihre Regel angewendet oder von einer spezifischeren Regel durchgestrichen wird.
• Leeren Sie das CDN. Wenn Sie Cloudflare oder ein anderes CDN nutzen, leeren Sie es nach Asset-Änderungen. Veraltete Edge-Kopien sind für einen großen Teil der „aber ich habe das doch schon geändert“-Meldungen verantwortlich.

Die Kurzfassung

• Bearbeiten Sie Theme- oder Moduldateien niemals direkt, das nächste Update überschreibt sie ohne Warnung.
• 1–5 kleine CSS-Anpassungen: legen Sie sie in custom.css ab.
• Umfangreiche, fortlaufende Änderungen: erstellen Sie ein Child-Theme.
• Kein Dateizugriff oder schnelle Snippets: verwenden Sie einen HTML-/Code-Block im Backoffice.
• Entwickler, bedingtes Laden: ein kleines Modul mit registerStylesheet() / registerJavascript().
• Liefern Sie JS als externe Dateien aus, laden Sie es am Ende, leeren Sie nach Änderungen alle Caches und sichern Sie Ihre Anpassungen außerhalb des Theme-Verzeichnisses.

PrestaShop anzupassen und Updates zu überstehen, ist kein Widerspruch, es fühlt sich nur so an, wenn Ihr Code am falschen Ort liegt. Wählen Sie für die konkrete Änderung die leichteste update-sichere Methode, und ein Theme-Upgrade wird zu dem, was es sein sollte: ein routinemäßiger Klick, nicht ein Tag voller erneuter Nacharbeit. Wenn Sie eigenen Code lieber aus dem Backoffice verwalten möchten, statt überhaupt Dateien anzufassen, können Sie mit unserem mprhtmlblocks-Modul HTML-, CSS- und JavaScript-Blöcke einzeln einfügen und ein- oder ausschalten, gespeichert in der Datenbank, vom nächsten Update unberührt.

Häufig gestellte Fragen

Ist die custom.css-Datei des Themes wirklich update-sicher?

Nicht vollständig. Da custom.css meist im Theme-Verzeichnis liegt, kann eine Theme-ZIP oder ein Hersteller-Update sie zusammen mit allem anderen ersetzen. Sie ist praktisch, sie lädt zuletzt, sodass Ihre Regeln in der Kaskade gewinnen, , aber behandeln Sie sie als Ort für austauschbare Anpassungen, die Sie notfalls erneut einpflegen können. Für echte Update-Sicherheit legen Sie Regeln in einem Child-Theme oder in einem Code-Block im Backoffice ab, wo der Updater sie nicht erreicht.

Mein eigenes CSS wird geladen, aber der Theme-Stil gewinnt trotzdem. Was ist falsch?

Das ist ein Spezifitätsproblem, kein Update- oder Cache-Problem. Der Selektor des Themes ist spezifischer als Ihrer, deshalb verwendet der Browser die Theme-Regel. Öffnen Sie die Entwicklertools, finden Sie den exakten Selektor des Themes und schreiben Sie Ihren passend dazu, da custom.css zuletzt lädt, gewinnt ein gleichwertiger Selektor bereits. Ergänzen Sie einen einschränkenden Parent wie #wrapper nur dann, wenn das Angleichen nicht reicht, und nutzen Sie !important nur als echten letzten Ausweg.

Kann ich einfach ein <script>-Tag in ein Template einfügen?

Nein. Ein Inline-Skript umgeht PrestaShops Asset-Management, wird also nicht von CCC zusammengeführt, und kann in Shops brechen, die einen Content-Security-Policy-Header setzen. Liefern Sie JavaScript immer als externe .js-Datei aus, die über hookActionFrontControllerSetMedia() mit registerJavascript() registriert wird, oder über einen Code-Block im Backoffice, niemals als rohes Markup in einer .tpl.

Wie lade ich mein CSS oder JS nur auf bestimmten Seiten?

Das ist der Hauptgrund, ein kleines Modul statt custom.css zu verwenden. Prüfen Sie innerhalb von hookActionFrontControllerSetMedia() $this->context->controller und registrieren Sie das Asset nur, wenn es passt, zum Beispiel instanceof ProductController für CSS auf Produktseiten oder instanceof OrderController für JavaScript an der Kasse. Ihr Code bleibt dann von Seiten fern, die ihn nicht brauchen, sodass Sie ihn nicht bei jedem Seitenaufruf mitbezahlen.

Warum wirft mein Skript „$ is not defined“?

Ihr JavaScript läuft, bevor jQuery geladen wurde. PrestaShop 1.7+ liefert im Frontoffice jQuery 3.x aus. Geben Sie Ihrem Skript daher in registerJavascript() eine ausreichend hohe priority, damit es nach jQuery geladen wird. Das Backoffice ist eine eigene Welt. Ältere Versionen hatten jQuery 1.x, , prüfen Sie daher den Seitenquelltext, bevor Sie Admin-Skripte gegen eine angenommene Version schreiben.

Ich habe mein CSS geändert und nichts ist passiert. Wo suche ich?

Fast immer bei einer Cache-Schicht, nicht in Ihrem Code. Gehen Sie der Reihe nach vor: Leeren Sie den PrestaShop-Cache unter Erweiterte Einstellungen → Leistung; deaktivieren Sie CCC (Combine, Compress, Cache) vorübergehend, wenn die Ladereihenfolge falsch wirkt; prüfen Sie im Browser-Network-Tab, dass Ihre Datei mit 200 und nicht mit 404 geladen wurde; und leeren Sie Ihr CDN (Cloudflare und andere), veraltete Edge-Kopien verursachen einen großen Teil der „aber ich habe das doch schon geändert“-Meldungen.

Sollte ich addCSS() und addJS() noch verwenden?

Nur in einem 1.6-Shop. Ab PrestaShop 1.7 sollten Sie registerStylesheet() und registerJavascript() bevorzugen. Sie geben Ihnen Priorität, Media Queries, eine JS-Position am Ende sowie async/defer, und sie behandeln Cache-Busting-Versionierung korrekt. Das alte addCSS() hat einen seit Langem bekannten Bug, bei dem ein ?v=-Query-String den Pfad so beschädigen kann, dass die Datei im Quelltext erscheint, aber nie angewendet wird, ohne dass ein 404 darauf hinweist.

Verwandte Leitfäden

• Child-Themes in PrestaShop: warum Sie niemals das Parent-Theme bearbeiten sollten
• HTML-Blöcke: eigene Inhalte überall in Ihrem PrestaShop-Shop einfügen
• Back-to-Top-Button: ein kleines UX-Detail, das überraschend wichtig ist