Service Worker für Shopify: Ein praktischer Guide

Das Wichtigste in Kürze

• Service Workers auf Shopify scheitern am Scope. Ein Service Worker kann nur das Verzeichnis kontrollieren, aus dem er ausgeliefert wird, und Shopify stellt Theme-Assets unter /cdn/shop/t/<id>/assets/ bereit, nicht im Root-Verzeichnis des Stores.
• Der Header, der den Scope erweitert, Service-Worker-Allowed, steht auf Shopifys offizieller Liste der Header, die aus App-Proxy-Antworten entfernt werden. Der Standard-Proxy-Workaround gibt dir also keine Root-Kontrolle.
• Der Checkout läuft auf deiner Store-Domain, also würde sich ein Service Worker mit Root-Scope vor die Zahlungsseiten setzen. Das ist eine Grenze, die du nicht überschreiten solltest.
• Ein fehlerhafter Service Worker lässt sich fast nicht mehr entfernen. Er lebt auf dem Gerät des Käufers, liefert weiterhin veraltete Seiten aus und nur ein sich selbst zerstörender Ersatz unter derselben URL kann ihn löschen.
• Die meisten Shopify-Stores sollten das nicht tun. Optimierungen bei Bildern, Skripten und auf Theme-Ebene bringen denselben Geschwindigkeitsvorteil, ohne diese Ausfallrisiken.

Service Workers auf Shopify werden oft zum Thema, wenn jemand über Offline-first-Seiten, Precaching oder Web-Push liest und sich fragt, warum das mit dem eigenen Store nicht geht. Die kurze Antwort ist, dass das Hosting-Modell von Shopify harte Grenzen setzt, von wo aus du die Worker-Datei ausliefern kannst – und dieses Limit bestimmt fast alles andere.

Dieser Guide behandelt, was ein Service Worker ist, welche genauen Shopify-Einschränkungen es gibt und welche Workarounds wirklich funktionieren, die wenigen Use-Cases, die diese Einschränkungen überleben, funktionierenden Code samt Vorbehalten, wie man einen fehlerhaften Worker „tötet“ und warum die meisten Stores besser beraten sind, denselben Aufwand woanders zu investieren.

Warum du uns vertrauen kannst

Wir sind seit über vier Jahren im Shopify-Umfeld tätig und haben mit hunderten von Shopify-Brands an ihren Storefronts gearbeitet. Jacques hat über 15 Jahre Entwicklererfahrung. Wir bauen Fudge, einen AI-Storefront-Editor mit einer Bewertung von 4.9 im Shopify App Store und dem „Built for Shopify“-Status. Wir arbeiten also jeden Tag in der Theme-Ebene und sehen, was die Plattform tatsächlich zulässt.

Was ist ein Service Worker?

Ein Service Worker ist eine JavaScript-Datei, die der Browser im Hintergrund ausführt, getrennt von jeder Seite. Sobald er installiert ist, sitzt er zwischen der Website und dem Netzwerk und kann Anfragen aus einem Cache statt vom Server beantworten.

Es ist kein Script-Tag. Er hat keinen DOM-Zugriff, überlebt Seitenwechsel und läuft weiter, nachdem der Tab geschlossen wurde. Diese Unabhängigkeit macht ihn so nützlich – und gleichzeitig so gefährlich.

Der Lifecycle

Vier Phasen sind entscheidend. Werden sie falsch umgesetzt, liefern Shops veraltete Inhalte an die Kunden aus.

Zwei Details bereiten vielen Probleme.

Der erste Seitenaufruf wird nie kontrolliert. Eine Seite muss von einem kontrollierenden Worker geladen werden, bevor dieser Worker ihre Anfragen sieht. Registrierst du ihn auf der ersten Seite, beginnt das Caching erst auf Seite zwei.¹

Updates werden geprüft, nicht gepusht. Der Browser ruft das Worker-Skript bei Navigationen und funktionalen Events erneut ab und überspringt diesen Check nicht länger als 24 Stunden. Die meisten Browser ignorieren deine Caching-Header für das Skript selbst. Dennoch kannst du ein Update nicht auf ein Gerät zwingen, das die Seite nie wieder besucht.¹

Mit skipWaiting() und clients.claim() lässt sich die Waiting-Phase abkürzen, auf Kosten der Ausführung neuen Worker-Codes auf Seiten, die von der alten Version gerendert wurden.

Die Shopify-Einschränkung: Scope

Hier ist das ganze Problem in einer einzigen Regel. Ein Service Worker kann nur URLs auf oder unterhalb des Pfads kontrollieren, aus dem er ausgeliefert wird. Ein Worker unter /sw.js kontrolliert die gesamte Website. Ein Worker unter /assets/sw.js kontrolliert /assets/ und sonst nichts. Das Skript muss außerdem Same-Origin mit der Seite sein, sonst wirft die Registrierung einen SecurityError.²

Es gibt ein Hintertürchen in der Spezifikation: Der Server kann beim Worker-Skript einen Service-Worker-Allowed Response-Header mitsenden, um den maximalen Scope zu erweitern.² Behalt diesen Gedanken im Hinterkopf.

Jetzt schauen wir uns an, wo Shopify deine Dateien ablegt.

Theme-Assets sind Same-Origin, aber tief verschachtelt. Shopify liefert Storefront-Theme-Assets von der eigenen Domain des Stores unter einem Pfad wie /cdn/shop/t/4159/assets/theme.js aus, was du durch einen Blick in den Quellcode jedes Live-Stores überprüfen kannst.³ Same-Origin ist eine gute Nachricht. Der Pfad eher nicht. Ein in den assets-Ordner deines Themes hochgeladener Worker erhält den Scope /cdn/shop/t/4159/assets/, was nur deine Theme-Dateien kontrolliert, aber überhaupt keine Store-Seiten.

Content > Files ist noch schlimmer. Dateien, die dort hochgeladen werden, werden von cdn.shopify.com ausgeliefert, einem völlig anderen Origin. Eine Registrierung von dort aus schlägt direkt fehl.

Der Store-Root gehört dir nicht. Fordere /sw.js in irgendeinem Shopify-Store an und du erhältst einen 404-Fehler. Der Online Store erlaubt es Händlern nicht, beliebige Dateien im Domain-Root abzulegen. robots.txt.liquid ist die seltene Ausnahme, und die erzeugt nur die robots.txt.

Und du kannst den Header nicht hinzufügen. Das CDN von Shopify liefert Theme-Assets mit einer langen Cache-Control und ohne Service-Worker-Allowed aus. Du hast keine Möglichkeit, die Response-Header von Dateien zu ändern, die Shopify ausliefert.

Die Scope-Regel in Kombination mit dem Datei-Hosting von Shopify bedeutet, dass der standardmäßige Service Worker mit Root-Scope im Online Store schlichtweg nicht verfügbar ist.

Welche Workarounds funktionieren wirklich?

Hier liegen die meisten Artikel zu diesem Thema falsch und wiederholen oft Ratschläge, die Shopify schon vor Jahren unterbunden hat. Hier ist der ehrliche Status für jeden Weg.

Warum die App-Proxy-Route für den Root-Scope tot ist

Ein App Proxy mappt einen Storefront-Pfad wie /apps/dein-pfad auf einen Server, den du betreibst. Die Präfixe sind auf apps, a, community oder tools beschränkt, der Mount Point ist also nie das Root-Verzeichnis.⁴

Du könntest sw.js über deinen Proxy ausliefern und Service-Worker-Allowed: / mitsenden, um den Scope zu erweitern. Shopify blockiert das. Die App-Proxy-Dokumentation listet die Response-Header auf, die Shopify aus Sicherheitsgründen entfernt, und Service-Worker-Allowed steht auf dieser Liste neben Set-Cookie, Server und X-Powered-By.⁴

Das war eine bewusste Änderung. Händler und App-Entwickler berichten seit 2021, dass dieser Header entfernt wird, was damals eine ganze Welle von Push-Benachrichtigungs- und Client-Side-Caching-Apps funktionslos gemacht hat. Service Worker mit Root-Scope sind kein Versehen, das man einfach umgehen könnte.

Was immer noch funktioniert, ist ein Service Worker, der im Proxy-Unterpfad registriert ist und /apps/dein-pfad/ kontrolliert. Kein spezieller Header nötig, denn dieser Scope liegt bereits auf oder unterhalb des Speicherorts des Skripts. Er kann keine Produktseiten cachen. Er kann jedoch weiterhin Push-Nachrichten empfangen, worauf wir weiter unten zurückkommen.

Warum die Reverse-Proxy-Route eine schlechte Idee ist

Du kannst im Prinzip ein CDN oder einen Edge Worker vor deine Domain setzen und /sw.js selbst ausliefern. Die eigene Dokumentation von Shopify zur Domain-Fehlerbehebung besagt jedoch, dass Setups wie Cloudflare DNS-Proxying und Orange-to-Orange nicht unterstützt werden und warnt, dass diese kaputtgehen können, wenn sich auf einer der beiden Seiten etwas ändert.⁵ Einen nicht unterstützten Proxy vor einen Store zu schalten, um eine optionale Caching-Schicht zu aktivieren, ist ein schlechter Deal.

Headless ist die einzige saubere Antwort

Wenn du eine Custom Storefront betreibst, egal ob das Hydrogen auf Oxygen ist oder dein eigenes Frontend gegen die Storefront API, hast du die Kontrolle über den Server, der auf den Root-Pfad antwortet. Du kannst /sw.js mit beliebigen Headern ausliefern und mit dem Scope / registrieren. Jede Einschränkung in diesem Abschnitt bezieht sich auf das Hosting des Online Stores, nicht auf Shopify als Commerce-Backend.

Was kann ein Service Worker auf einem Shopify-Store realistischerweise tun?

Nimm für einen Moment an, du hättest das Scope-Problem gelöst. Es gibt vier Use Cases. Sie sind nicht alle gleichermaßen sinnvoll.

Caching von statischen Assets und Schriftarten. Der echte Mehrwert. Versionierte Theme-Assets und selbstgehostete Schriftarten sind unveränderlich, also ist eine Cache-First-Regel sicher und bietet wiederkehrenden Besuchern fast sofortige Ladezeiten. Der Haken ist, dass das CDN von Shopify Theme-Assets bereits mit einer einjährigen Cache-Control ausliefert, der HTTP-Cache des Browsers erledigt diese Arbeit also ohnehin schon. Der zusätzliche Gewinn ist kleiner, als es den Anschein hat.

Eine Offline-Fallback-Seite. Günstig und risikoarm. Statt der Fehlerseite des Browsers sieht ein Käufer, der sein Signal verliert, eine gebrandete Seite deines Shops. Sie verkauft nichts, aber es ist ein nettes Detail für das Nutzererlebnis.

Background Sync für ein Formular. Eine Offline-Newsletter-Anmeldung oder das Einreichen einer Bewertung wird erneut versucht, sobald die Verbindung wieder da ist. Nützlich in Märkten mit wirklich schlechter Verbindung, andernorts eher sinnlos. Der Support ist nicht in allen Browsern gegeben, betrachte es also als eine Zusatzfunktion, unter der ein normaler Submit-Pfad liegt.

Push-Benachrichtigungen. Eine Push-Subscription ist an die Registrierung des Service Workers geknüpft, nicht an seinen Scope. Ein Worker auf einem engen Pfad kann also immer noch Pushes empfangen. Die echten Hürden liegen woanders: Du brauchst einen Permission-Prompt, den die Käufer überwiegend ablehnen, iOS liefert Web-Pushes nur an Seiten aus, die der Nutzer zu seinem Home-Screen hinzugefügt hat, und die meisten Händler nutzen am Ende doch eine Push-App aus dem App Store, anstatt das selbst zu bauen. Schau dir das Live-Listing der Push-Apps auf ihre aktuellen Pläne an, bevor du dich festlegst.

Für das mobile Publikum, auf das diese Use Cases abzielen, liegen die echten Gewinne meist woanders. Schau dir unseren Guide zum Thema Shopify Mobile Speed an, für Änderungen, die die mobilen Zahlen wirklich verbessern.

Der Code und seine Vorbehalte

Wenn du Headless unterwegs bist oder eine Staging-Umgebung hast, bei der dir der Root gehört, ist dies das absolut notwendige Paar an Dateien.

Registrierung

// In deinem Layout, nachdem die Seite vollständig geladen ist.
if ('serviceWorker' in navigator) {
    window.addEventListener('load', () => {
        navigator.serviceWorker
            .register('/sw.js', {scope: '/'})
            .then((reg) => console.log('Service Worker Scope:', reg.scope))
            .catch((err) => console.error('Registrierung fehlgeschlagen:', err))
    })
}

Achtung: In einem normalen Online Store schlägt das fehl, da /sw.js einen 404-Fehler zurückgibt. Ein Request auf /sw.js über deine eigene Domain ist der schnellste Weg, das zu bestätigen, bevor du irgendetwas anderes programmierst. Wenn du das zusammen mit anderen Skripten hinzufügst, zeigt dir unser Guide zum Hinzufügen von Custom JavaScript in Shopify, wo Theme-Code hingehört.

Ein minimaler Fetch-Handler

Cache-First für versionierte Assets, Network-First für Dokumente und eine ausdrückliche Weigerung, transaktionale Prozesse anzutasten.

const VERSION = 'v1'
const ASSET_CACHE = `assets-${VERSION}`
const PAGE_CACHE = `pages-${VERSION}`

// Diese niemals abfangen. Warenkorb, Kundenkonto, Checkout und App-Routen bleiben live.
const NEVER_HANDLE = [/^\/checkouts?\//, /^\/cart/, /^\/account/, /^\/apps\//, /^\/wpm/]

self.addEventListener('install', (event) => {
    event.waitUntil(caches.open(PAGE_CACHE).then((c) => c.add('/offline')))
})

self.addEventListener('activate', (event) => {
    event.waitUntil(
        caches
            .keys()
            .then((keys) => Promise.all(keys.filter((k) => !k.endsWith(VERSION)).map((k) => caches.delete(k)))),
    )
})

self.addEventListener('fetch', (event) => {
    const req = event.request
    const url = new URL(req.url)

    if (req.method !== 'GET') return
    if (url.origin !== self.location.origin) return
    if (NEVER_HANDLE.some((re) => re.test(url.pathname))) return

    // Versionierte Theme-Assets sind unveränderlich, daher ist Cache-First sicher.
    if (url.pathname.startsWith('/cdn/shop/t/')) {
        event.respondWith(
            caches.match(req).then((hit) => {
                if (hit) return hit
                return fetch(req).then((res) => {
                    if (res.ok) {
                        const copy = res.clone()
                        caches.open(ASSET_CACHE).then((c) => c.put(req, copy))
                    }
                    return res
                })
            }),
        )
        return
    }

    // Dokumente gehen zuerst ans Netzwerk. Der Cache ist nur ein Offline-Fallback.
    if (req.mode === 'navigate') {
        event.respondWith(
            fetch(req)
                .then((res) => {
                    const copy = res.clone()
                    caches.open(PAGE_CACHE).then((c) => c.put(req, copy))
                    return res
                })
                .catch(() => caches.match(req).then((hit) => hit || caches.match('/offline'))),
        )
    }
})

Dinge, die du beachten musst (wichtiger als der Code):

• NEVER_HANDLE ist das Sicherheitsgeländer. Warenkorb, Kundenkonto und Checkout-Pfade müssen immer den Server erreichen. Einen gecachten Warenkorb zurückzugeben, bedeutet ein Support-Ticket. Ein gecachter Checkout-Schritt ist noch schlimmer.
• Niemals Cache-First für ein HTML-Dokument nutzen. Preise, Lagerbestand und Aktionen ändern sich. Eine gecachte Produktseite zeigt dem Käufer, der sich die Werbung von heute ansieht, den Preis von gestern.
• Erhöhe die VERSION bei jeder Änderung. Der Activate-Handler verhindert, dass sich alte Caches auf den Geräten der Kunden ansammeln.
• Teste mit einem echten Shop, nicht mit einem Template. Themes und Apps bringen eigene Fetch-Muster mit, und Shopify fügt Routen hinzu, die du nicht geschrieben hast.

Die Risiken im Klartext

Diesen Abschnitt solltest du zweimal lesen.

Veralteter Content wird an echte Käufer ausgeliefert. Der Fehlerfall ist nicht „die Website ist langsam“. Er besteht darin, dass ein Käufer ein ausverkauftes Produkt als verfügbar sieht oder einen Sale-Banner, der vor einer Woche ausgelaufen ist, weil sein Gerät eine gecachte Kopie lädt. In deinem eigenen Browser wirst du das nicht sehen.

Der Checkout liegt auf deiner Domain. Seit Shopify den Checkout von checkout.shopify.com wegbewegt hat, finden Checkouts auf der Shop-Domain statt, auf der der Kunde surft.⁶ Ein Worker mit Root-Scope würde also im Request-Pfad der Zahlungsseiten sitzen. Setze keinen Custom-Caching-Code vor den Checkout. Shopify riegelt den Checkout aus PCI-Gründen ab, was auch der Grund ist, warum Analytics über die Sandboxed Web Pixels API laufen muss, anstatt über beliebige Skripte. Betrachte diese Grenze hier als absolut.

Der Warenkorb-Status geht auf unvorhersehbare Weise kaputt. Warenkorb-Routen liefern JSON zurück, das sich bei jeder Interaktion ändert. Cache nur eine Antwort, und Add-to-Cart fängt an, über seinen Inhalt zu lügen.

Ein fehlerhafter Worker ist fast nicht mehr zu entfernen. Das ist das Risiko, das Service Worker von jedem anderen Frontend-Fehler unterscheidet. Der Worker verbleibt auf dem Gerät des Käufers. Du erreichst ihn nicht, du siehst ihn nicht, und ein Rollback deines Themes ändert daran gar nichts. Er liefert so lange aus, was er gecacht hat, bis genau dieser Browser einen Ersatz von exakt der URL abruft, unter der der Worker ursprünglich registriert wurde.

Die Asset-Pfade von Shopify machen das noch schlimmer. Das Segment /cdn/shop/t/<id>/ ist an das Theme gebunden. Veröffentlichst du ein anderes Theme, kann die Skript-URL des alten Workers plötzlich ins Leere laufen. Laut Spezifikation bricht ein fehlgeschlagener Update-Fetch das Update ab und lässt den existierenden Worker weiterlaufen – dein Kill-Switch hat also keinen Ort mehr, an dem er leben kann.

Du legst einen Cache über einen Cache. Shopify betreibt bereits ein Cloudflare-gestütztes CDN vor deiner Storefront und versioniert Asset-URLs automatisch.³ Ein handgeschriebener Cache obendrauf fügt ein zweites Invalidierungs-Problem hinzu, ohne das erste zu beseitigen. Wo die wirklichen Performance-Probleme liegen, erfährst du in unserem Beitrag Status der Shopify-Performance 2026.

Wie man einen fehlerhaften Service Worker entfernt

Wenn bereits einer live ist, arbeite diese Schritte der Reihe nach ab.

1. Überprüfen, was installiert ist

Öffne in den Chrome DevTools Application > Service Workers, um die Registrierung, den Scope und die Skript-URL zu sehen. Unter Application > Storage > Cache Storage siehst du, was gecacht wurde. Notiere dir die genaue Skript-URL. Alles Weitere hängt davon ab.

2. Einen selbstzerstörenden Worker ausliefern

Die einzige zuverlässige Entfernung ist es, die Worker-Datei unter genau derselben URL durch eine zu ersetzen, deren einzige Aufgabe es ist, sich selbst zu löschen.

self.addEventListener('install', () => self.skipWaiting())

self.addEventListener('activate', (event) => {
    event.waitUntil(
        (async () => {
            const keys = await caches.keys()
            await Promise.all(keys.map((key) => caches.delete(key)))
            await self.registration.unregister()
            const clients = await self.clients.matchAll({type: 'window'})
            clients.forEach((client) => client.navigate(client.url))
        })(),
    )
})

skipWaiting() aktiviert ihn sofort, der Activate-Handler leert alle Caches und meldet den Worker ab (unregister), anschließend lädt sich jeder offene Tab ohne Controller neu. Entferne auch den Registrierungsaufruf aus deinem Theme, damit er sich nicht erneut registriert.

Er wird nur beim nächsten Besuch des Kunden ausgeführt. Der Browser überprüft das Skript innerhalb von 24 Stunden nach der Aktivität, aber ein Gerät, das nie wiederkommt, behält den alten Worker für immer. Es gibt keinen serverseitigen Purge.

3. Verstehen, was Clear-Site-Data kann und was nicht

Der Response-Header Clear-Site-Data: "storage" entfernt Service Worker für den Origin.⁷ Es ist die saubere Lösung für eine Website, bei der du die Response-Header kontrollierst. Im Shopify Online Store hast du diese Kontrolle nicht, das steht also nur Headless-Storefronts zur Verfügung.

4. Für einen einzelnen Käufer

Der Support kann eine einzelne Person durch die DevTools via Application > Storage > Clear site data oder in ein privates Fenster leiten. Das ist eine Notfallmaßnahme bei Beschwerden, aber kein echter Fix.

Die meisten Stores sollten das nicht tun. Hier ist, was du stattdessen tun solltest.

Das Fazit ist eindeutig. Im Shopify Online Store ist ein nützlicher Service Worker innerhalb der Plattformregeln nicht realisierbar, und die Version, die machbar ist, ist das Risiko nicht wert. Der Scope beschränkt dich auf ein Verzeichnis, das nichts kontrolliert, der Header, der das beheben würde, wird entfernt, und die Reverse-Proxy-Route wird nicht unterstützt. Wenn du trotzdem einen baust, bist du nur einen Fehler davon entfernt, veraltete Preise anzuzeigen, die du nicht mehr rückgängig machen kannst.

Headless-Storefronts sind ein anderes Thema. Wenn dir der Root gehört, gelten die normalen Web-Regeln und der Code oben ist ein vernünftiger Startpunkt.

Für alle auf dem Online Store bringt derselbe Aufwand im Theme deutlich mehr:

• Schmeiß ungenutzte App-Skripte raus. Third-Party-JavaScript ist der größte kontrollierbare Kostenfaktor in den meisten Stores, und ein Skript zu entfernen ist immer besser, als es zu cachen.
• Optimiere zuerst die Bilder. Richtige Größen, moderne Formate und ein Eager-Loaded Hero-Image. Unser Guide zu Shopify Lazy Load Images behandelt die Reihenfolge, auf die es ankommt.
• Entferne Render-Blocking-Ressourcen und minifiere den Rest. Sieh dir an, wie man CSS und JavaScript in Shopify minifiziert, um zu verstehen, was Shopify bereits übernimmt und was nicht.
• Verschlanke das Theme selbst. Den gesamten Ablauf findest du unter Wie man ein Shopify Theme schneller macht.

Jede dieser Maßnahmen ist über das Admin-Panel reversibel. Keine von ihnen lässt einen Käufer auf einer gecachten Version deines Stores stranden.

Diese Reversibilität ist auch der Grund, warum wir Fudge so gebaut haben, dass es nativen Theme-Code schreibt, anstatt einen Runtime-Layer einzufügen. Änderungen landen als Liquid, CSS und JavaScript direkt in deinem Theme. So kannst du sie lesen, zurückrollen und behalten, auch wenn du aufhörst, uns zu bezahlen. Dasselbe gilt für alles andere, was du mit dem Shopify Store Editor baust.

FAQ