Service Worker für Shopify: Ein praktischer Guide

Die wichtigsten Erkenntnisse

• Service Worker auf Shopify werden durch den Scope blockiert. 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 Store-Root.
• Der Header, der den Scope erweitert (Service-Worker-Allowed), steht auf Shopifys dokumentierter Liste von Headern, 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 ein Service Worker mit Root-Scope vor den Zahlungsseiten sitzen. Das ist eine Grenze, die du nicht überschreiten solltest.
• Ein fehlerhafter Service Worker ist fast nicht mehr zu entfernen. Er verbleibt auf dem Gerät des Käufers, liefert weiterhin veraltete Seiten aus, und nur ein sich selbst zerstörender Ersatz unter derselben URL löscht ihn.
• Die meisten Shopify-Stores sollten das nicht tun. Optimierungen bei Bildern, Skripten und auf Theme-Ebene bringen denselben Geschwindigkeitsgewinn – ganz ohne diese Ausfallrisiken.

Service Worker auf Shopify sind immer dann ein Thema, wenn jemand von Offline-First-Seiten, Precaching oder Web-Push liest und sich fragt, warum sein Store das nicht auch kann. Die kurze Antwort lautet: Das Hosting-Modell von Shopify setzt ein hartes Limit, von wo aus du die Worker-Datei ausliefern kannst, und dieses Limit entscheidet fast alles andere.

Dieser Guide behandelt, was ein Service Worker ist, die genaue Shopify-Einschränkung und welche Workarounds real sind, die wenigen Use Cases, die diese Einschränkung überleben, funktionierenden Code mit den entsprechenden Vorbehalten, wie man einen schlechten Worker entfernt und warum die meisten Stores besser dran 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 Entwicklungserfahrung. Wir bauen Fudge, einen AI-Storefront-Editor mit einem 5,0-Rating im Shopify App Store und “Built for Shopify”-Status, wir arbeiten also jeden Tag in der Theme-Ebene und sehen, was die Plattform wirklich 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. Wenn du hier etwas falsch machst, lieferst du veralteten Content an deine Käufer aus.

Zwei Details werden oft übersehen.

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

Updates werden geprüft, nicht gepusht. Der Browser ruft das Worker-Skript bei Navigationen und funktionalen Events neu ab und überspringt diesen Check für maximal 24 Stunden. Die meisten Browser ignorieren deine Caching-Header auf dem Skript selbst. Du kannst trotzdem kein Update auf ein Gerät zwingen, das nie wieder vorbeikommt.¹

skipWaiting() und clients.claim() überspringen die Waiting-Phase, allerdings zu dem Preis, dass neuer Worker-Code auf Seiten ausgeführt wird, 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 irren sich die meisten Artikel zu diesem Thema, weil sie oft Ratschläge wiederholen, die Shopify schon vor Jahren abgestellt 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 geladen wurde.
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("Registration failed:", err));
  });
}

Achtung: In einem Standard-Online-Store schlägt das fehl, da /sw.js einen 404-Fehler liefert. Ein Aufruf von /sw.js auf deiner eigenen Domain ist der schnellste Weg, das zu überprüfen, bevor du irgendetwas anderes schreibst. Wenn du dies zusammen mit anderen Skripten hinzufügst, zeigt dir unser Guide zum Thema Eigenes JavaScript in Shopify hinzufügen, wo Theme-Code am besten platziert wird.

Ein minimaler Fetch-Handler

Cache-First für versionierte Assets, Network-First für Dokumente und die ausdrückliche Weigerung, alles Transaktionale anzufassen.

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

// Never intercept these. Cart, account, checkout and app routes stay 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;

  // Versioned theme assets are immutable, so cache-first is safe.
  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;
  }

  // Documents go to the network first. The cache is an offline fallback only.
  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"))
        )
    );
  }
});

Vorbehalte, die wichtiger sind als der Code:

• NEVER_HANDLE ist dein Sicherheitsnetz. Warenkorb, Account und Checkout-Pfade müssen jedes Mal den Server erreichen. Ein gecachter Warenkorb bedeutet direkt ein Support-Ticket. Ein gecachter Checkout-Schritt ist noch viel schlimmer.
• Niemals Cache-First für ein HTML-Dokument. Preise, Bestände und Promotions ändern sich. Eine gecachte Produktseite zeigt dem Käufer den Preis von gestern, während er sich die Anzeige von heute ansieht.
• Erhöhe die VERSION bei jeder Änderung. Der Activate-Handler verhindert, dass sich alte Caches auf den Geräten der Käufer ansammeln.
• Teste gegen einen echten Store, nicht gegen ein Template. Themes und Apps bringen ihre eigenen 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 Methode zum Entfernen ist es, die Worker-Datei unter exakt derselben URL durch eine zu ersetzen, deren einziger Job 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 jeden Cache und deregistriert ihn, anschließend lädt jeder offene Tab neu, und zwar ohne Controller. Entferne außerdem den Registrierungsaufruf aus deinem Theme, damit er sich nicht erneut registriert.

Er läuft erst beim nächsten Besuch des Käufers. Der Browser prüft das Skript innerhalb von 24 Stunden nach 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