Service Workers pour Shopify : Le guide pratique

Points à retenir

• Les service workers sur Shopify sont bloqués par le scope. Un service worker ne peut contrôler que le répertoire d’où il est servi, et Shopify sert les assets du thème sous /cdn/shop/t/<id>/assets/, et non à la racine de la boutique.
• L’en-tête qui élargit le scope, Service-Worker-Allowed, figure sur la liste officielle de Shopify des en-têtes supprimés des réponses de l’App Proxy, la solution de contournement standard du proxy ne vous donne donc pas le contrôle sur la racine.
• Le checkout s’exécute sur le domaine de votre boutique, donc un service worker avec un scope à la racine se placerait devant les pages de paiement. C’est une limite à ne pas franchir.
• Un mauvais service worker est presque impossible à supprimer. Il reste sur l’appareil de l’acheteur, continue de servir des pages périmées (stale) et seul un remplaçant autodestructeur à la même URL peut l’effacer.
• La plupart des boutiques Shopify ne devraient pas faire ça. Les optimisations au niveau des images, des scripts et du thème offrent le même gain de vitesse sans aucun de ces risques de panne.

Les service workers sur Shopify reviennent sur le tapis chaque fois que quelqu’un lit un article sur les sites “offline-first” (hors-ligne d’abord), le precaching ou le web push, et se demande pourquoi sa boutique ne peut pas faire pareil. La réponse courte est que le modèle d’hébergement de Shopify impose une limite stricte sur l’endroit d’où vous pouvez servir le fichier du worker, et cette limite dicte presque tout le reste.

Ce guide explique ce qu’est un service worker, la contrainte exacte de Shopify et les solutions de contournement qui fonctionnent vraiment, les quelques cas d’usage qui survivent à cette contrainte, du code fonctionnel avec ses mises en garde, comment tuer un mauvais worker, et pourquoi la plupart des boutiques ont plutôt intérêt à concentrer leurs efforts ailleurs.

Pourquoi vous pouvez nous faire confiance

Nous travaillons dans l’écosystème Shopify depuis plus de quatre ans et avons collaboré avec des centaines de marques Shopify sur leurs vitrines. Jacques a plus de 15 ans d’expérience en développement. Nous créons Fudge, un éditeur de vitrine IA noté 5.0 sur le Shopify App Store avec le statut Built for Shopify, nous travaillons donc chaque jour dans la couche du thème et voyons ce que la plateforme permet réellement.

Qu’est-ce qu’un service worker ?

Un service worker est un fichier JavaScript que le navigateur exécute en arrière-plan, indépendamment de toute page. Une fois installé, il s’intercale entre le site et le réseau et peut répondre aux requêtes depuis un cache au lieu du serveur.

Ce n’est pas une balise script. Il n’a pas accès au DOM, il survit aux navigations de page, et il continue de tourner après la fermeture de l’onglet. C’est cette indépendance qui le rend utile et en même temps dangereux.

Le cycle de vie

Quatre phases comptent. Les rater, c’est ce qui fait que les boutiques servent du contenu périmé aux acheteurs.

Deux détails piègent souvent les gens.

Le premier chargement de page n’est jamais contrôlé. Une page doit être chargée par un worker contrôleur avant que ce worker ne voie ses requêtes. Enregistrez-le sur la page un, et la mise en cache ne commencera qu’à la page deux.¹

Les mises à jour sont vérifiées, pas “poussées” (pushed). Le navigateur récupère à nouveau le script du worker lors de la navigation et des événements fonctionnels, et il ne sautera pas cette vérification pendant plus de 24 heures. La plupart des navigateurs ignorent vos en-têtes de cache sur le script lui-même. Vous ne pouvez toujours pas forcer une mise à jour sur un appareil qui ne revient jamais sur le site.¹

skipWaiting() et clients.claim() raccourcissent la phase d’attente, au prix de l’exécution du nouveau code du worker sur des pages rendues par l’ancienne version.

La contrainte de Shopify : le scope

Voici tout le problème résumé en une seule règle. Un service worker ne peut contrôler que les URL situées sur ou sous le chemin d’où il est servi. Un worker sur /sw.js contrôle tout le site. Un worker sur /assets/sw.js contrôle /assets/ et rien d’autre. Le script doit également être de la même origine (same-origin) que la page, sinon l’enregistrement renvoie une SecurityError.²

Il y a une échappatoire dans la spec : le serveur peut envoyer un en-tête de réponse Service-Worker-Allowed sur le script du worker pour élargir le scope maximum.² Gardez ça en tête.

Maintenant, regardez où Shopify place vos fichiers.

Les assets du thème sont de la même origine mais profondément imbriqués. Shopify sert les assets du thème de la vitrine depuis le propre domaine de la boutique sous un chemin comme /cdn/shop/t/4159/assets/theme.js, ce que vous pouvez confirmer en affichant le code source de n’importe quelle boutique en ligne.³ La même origine est une bonne nouvelle. Le chemin ne l’est pas. Un worker uploadé dans le dossier assets de votre thème obtient un scope de /cdn/shop/t/4159/assets/, ce qui contrôle les fichiers de votre thème et absolument aucune page de la boutique.

Contenu > Fichiers est encore pire. Les fichiers qui y sont uploadés sont servis depuis cdn.shopify.com, une origine complètement différente. L’enregistrement depuis là-bas échoue d’emblée.

La racine de la boutique ne vous appartient pas. Demandez /sw.js sur n’importe quelle boutique Shopify et vous obtiendrez une erreur 404. La Boutique en ligne ne permet pas aux marchands de placer des fichiers arbitraires à la racine du domaine. robots.txt.liquid est la rare exception, et il ne produit que robots.txt.

Et vous ne pouvez pas ajouter l’en-tête. Le CDN de Shopify sert les assets du thème avec un long Cache-Control et aucun Service-Worker-Allowed. Vous n’avez aucun moyen de modifier les en-têtes de réponse sur les fichiers que Shopify sert.

La règle du scope combinée à l’hébergement de fichiers de Shopify signifie que le service worker standard avec un scope à la racine n’est tout simplement pas disponible sur la Boutique en ligne.

Quelles solutions de contournement fonctionnent vraiment ?

C’est là que la plupart des articles sur le sujet se trompent, généralement en répétant des conseils que Shopify a bloqués il y a des années. Voici l’état réel de chaque méthode.

Pourquoi la méthode de l’App Proxy est morte pour le scope racine

Un App Proxy mappe un chemin de vitrine comme /apps/votre-chemin vers un serveur que vous gérez. Les préfixes sont limités à apps, a, community ou tools, le point de montage n’est donc jamais la racine.⁴

Vous pourriez servir sw.js depuis votre proxy et envoyer Service-Worker-Allowed: / pour élargir son scope. Shopify le bloque. La documentation de l’App Proxy liste les en-têtes de réponse que Shopify supprime pour des raisons de sécurité, et Service-Worker-Allowed figure sur cette liste aux côtés de Set-Cookie, Server et X-Powered-By.⁴

C’était un changement délibéré. Les marchands et les développeurs d’applications signalent la suppression de cet en-tête depuis 2021, ce qui a cassé une vague d’applications de notifications push et de cache côté client à l’époque. Les service workers à la racine ne sont pas un oubli que vous pouvez contourner en argumentant.

Ce qui fonctionne encore, c’est un service worker enregistré sur le sous-chemin du proxy, contrôlant /apps/votre-chemin/. Pas besoin d’en-tête spécial, car ce scope est déjà au niveau ou en dessous de l’emplacement propre du script. Il ne peut pas mettre en cache les pages produits. Il peut en revanche toujours recevoir des messages push, ce sur quoi nous reviendrons plus bas.

Pourquoi la méthode du reverse proxy est une mauvaise idée

Vous pouvez, en principe, placer un CDN ou un edge worker devant votre domaine et servir /sw.js vous-même. La propre documentation de dépannage de domaine de Shopify indique qu’elle ne supporte pas les configurations telles que le proxy DNS Cloudflare (Orange-to-Orange), et avertit qu’elles peuvent se casser lorsque l’un des côtés change.⁵ Mettre un proxy non supporté devant une boutique pour activer une couche de cache optionnelle est un mauvais calcul.

Le Headless est la seule réponse propre

Si vous gérez une vitrine sur mesure (custom storefront), que ce soit Hydrogen sur Oxygen ou votre propre front-end interrogeant la Storefront API, vous contrôlez le serveur qui répond au chemin racine. Vous pouvez servir /sw.js avec tous les en-têtes que vous voulez et l’enregistrer avec le scope /. Chaque contrainte de cette section est une contrainte de l’hébergement de la Boutique en ligne, pas de Shopify en tant que backend e-commerce.

Que peut faire un service worker de façon réaliste sur une boutique Shopify ?

Supposons un instant que vous ayez résolu le problème de scope. Quatre cas d’usage se présentent. Ils ne se valent pas tous.

La mise en cache d’assets statiques et de polices. Le vrai bon cas d’usage. Les assets versionnés du thème et les polices auto-hébergées sont immuables, donc une règle cache-first est sûre et offre aux visiteurs récurrents des chargements presque instantanés. Le hic, c’est que le CDN de Shopify sert déjà les assets du thème avec un Cache-Control d’un an, donc le cache HTTP du navigateur fait déjà la plus grande partie de ce travail. Le gain incrémental est plus faible qu’il n’y paraît.

Une page de fallback hors-ligne. Pas cher et sans risque. Au lieu de la page d’erreur du navigateur, un acheteur qui perd le réseau voit votre page personnalisée. Ça ne vend rien. C’est juste pour faire propre.

La synchronisation en arrière-plan pour un formulaire. Une inscription à la newsletter ou la soumission d’un avis faite hors-ligne est réessayée lorsque la connexion revient. Utile dans les marchés à connectivité vraiment mauvaise, presque inutile ailleurs. Le support n’est pas universel sur tous les navigateurs, traitez-le donc comme une amélioration (enhancement) avec un chemin de soumission normal en dessous.

Les notifications push. Un abonnement push est attaché à l’enregistrement du service worker, pas à son scope, de sorte qu’un worker sur un chemin restreint peut toujours recevoir des push. Les vrais bloqueurs sont ailleurs : vous avez besoin d’une demande d’autorisation que les acheteurs refusent massivement, iOS ne délivre les web push qu’aux sites que l’utilisateur a ajoutés à l’écran d’accueil, et la plupart des marchands finissent par utiliser une application de push de l’App Store plutôt que de développer ça. Vérifiez bien les abonnements actuels de n’importe quelle application push avant de vous engager.

Pour l’audience mobile visée par ces cas d’usage, les gains sont généralement ailleurs. Consultez notre guide sur la vitesse mobile sur Shopify pour voir les changements qui font réellement bouger les métriques mobiles.

Le code, avec ses mises en garde

Si vous êtes en headless, ou si vous avez un environnement de staging où vous contrôlez la racine, voici la paire de fichiers minimum viable.

Enregistrement

// Dans votre layout, une fois la page stabilisée.
if ("serviceWorker" in navigator) {
  window.addEventListener("load", () => {
    navigator.serviceWorker
      .register("/sw.js", { scope: "/" })
      .then((reg) => console.log("Scope du service worker :", reg.scope))
      .catch((err) => console.error("Échec de l'enregistrement :", err));
  });
}

Mise en garde : sur une Boutique en ligne standard cela échoue, car /sw.js renvoie une 404. Demander /sw.js sur votre propre domaine est le moyen le plus rapide de le confirmer avant d’écrire quoi que ce soit d’autre. Si vous ajoutez ceci en plus d’autres scripts, notre guide sur l’ajout de JavaScript personnalisé sur Shopify explique où doit se trouver le code du thème.

Un gestionnaire fetch minimal

Cache-first pour les assets versionnés, network-first pour les documents, et un refus explicite de toucher à quoi que ce soit de transactionnel.

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

// Ne jamais intercepter ces routes. Le panier, le compte, le checkout et les apps restent en direct.
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;

  // Les assets du thème versionnés sont immuables, le cache-first est donc sûr.
  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;
  }

  // Les documents passent par le réseau d'abord. Le cache n'est qu'un fallback hors-ligne.
  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"))
        )
    );
  }
});

Des mises en garde qui comptent plus que le code :

• NEVER_HANDLE est le garde-fou. Les chemins du panier, du compte et du checkout doivent atteindre le serveur à chaque fois. Retourner un panier mis en cache équivaut à un ticket de support. Retourner une étape de checkout mise en cache est encore pire.
• Ne faites jamais de cache-first sur un document HTML. Les prix, les stocks et les promotions changent. Une page produit en cache affichera le prix d’hier à un acheteur qui regarde la publicité d’aujourd’hui.
• Incrémentez VERSION à chaque changement. C’est le gestionnaire activate qui empêche les anciens caches de s’accumuler sur les appareils des acheteurs.
• Testez sur une vraie boutique, pas sur un template. Les thèmes et les applications introduisent leurs propres modèles de requêtes (fetch), et Shopify ajoute des routes que vous n’avez pas écrites.

Les risques, expliqués clairement

C’est la section à lire deux fois.

Du contenu périmé (stale) est servi aux vrais acheteurs. Le mode d’échec n’est pas “le site est lent”. C’est un acheteur qui voit un produit épuisé comme disponible, ou une bannière de promo qui s’est terminée il y a une semaine, car son appareil sert une copie en cache. Vous ne le verrez pas dans votre propre navigateur.

Le checkout est sur votre domaine. Depuis que Shopify a déplacé le checkout hors de checkout.shopify.com, les paiements se font sur le domaine de la boutique que le client visite.⁶ Un worker scopé à la racine se trouverait sur le chemin des requêtes pour les pages de paiement. Ne mettez pas de code de mise en cache personnalisé devant le checkout. Shopify verrouille le checkout pour des raisons de normes PCI, c’est aussi pourquoi l’analytics doit passer par l’API Web Pixels sandboxée plutôt que par des scripts arbitraires. Traitez cette limite comme absolue.

L’état du panier se casse de façons difficiles à reproduire. Les routes du panier retournent du JSON qui change à chaque interaction. Mettez en cache une réponse et l’ajout au panier commence à mentir sur son contenu.

Un mauvais worker est presque impossible à supprimer. C’est le risque qui sépare les service workers de toute autre erreur front-end. Le worker vit sur l’appareil de l’acheteur. Vous ne pouvez pas l’atteindre, vous ne pouvez pas le voir, et faire un rollback de votre thème n’y touche pas. Il continuera à servir ce qu’il a mis en cache jusqu’à ce que ce navigateur spécifique récupère un remplaçant depuis l’URL exacte d’où le worker a été enregistré.

Les chemins d’assets de Shopify empirent les choses. Le segment /cdn/shop/t/<id>/ est lié au thème. Publiez un autre thème et l’URL du script de l’ancien worker peut cesser de répondre. Selon la spec, un échec de mise à jour annule la mise à jour et laisse le worker existant en place, votre kill switch (bouton d’arrêt) n’a donc nulle part où vivre.

Vous superposez un cache sur un cache. Shopify exécute déjà un CDN adossé à Cloudflare devant votre vitrine et versionne automatiquement les URL des assets.³ Un cache fait maison par-dessus ajoute un deuxième problème d’invalidation sans supprimer le premier. Pour savoir où se situent les véritables failles de performance, consultez notre état des performances Shopify en 2026.

Comment désenregistrer un mauvais service worker

S’il y en a déjà un en ligne, suivez ces étapes dans l’ordre.

1. Confirmer ce qui est installé

Dans les DevTools de Chrome, ouvrez Application > Service Workers pour voir l’enregistrement, son scope et l’URL de son script. Application > Storage > Cache Storage montre ce qu’il a mis en cache. Notez l’URL exacte du script. Tout ce qui suit en dépend.

2. Déployer un worker auto-destructeur

La seule suppression fiable consiste à remplacer le fichier du worker à la même URL par un autre dont le seul rôle est de s’effacer lui-même.

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() l’active immédiatement, le gestionnaire activate vide chaque cache et le désenregistre, puis chaque onglet ouvert se recharge sans contrôleur. Retirez également l’appel d’enregistrement de votre thème afin que rien ne se réenregistre.

Cela ne s’exécute que lors de la prochaine visite de l’acheteur. Le navigateur vérifiera le script dans les 24 heures d’activité, mais un appareil qui ne revient jamais gardera l’ancien worker pour toujours. Il n’y a pas de purge côté serveur.

3. Savoir ce que Clear-Site-Data peut et ne peut pas faire

L’en-tête de réponse Clear-Site-Data: "storage" désenregistre les service workers pour l’origine.⁷ C’est la solution propre sur un site où vous contrôlez les en-têtes de réponse. Sur la Boutique en ligne Shopify, ce n’est pas le cas, ceci n’est donc disponible que pour les vitrines headless.

4. Pour un acheteur individuel

Le support peut guider une personne à travers les DevTools Application > Storage > Clear site data, ou une fenêtre de navigation privée. C’est un palliatif pour gérer une plainte, pas une vraie solution.

La plupart des boutiques ne devraient pas faire ça. Voici quoi faire à la place.

Le verdict est sans appel. Sur la Boutique en ligne Shopify, un service worker utile n’est pas réalisable dans le respect des règles de la plateforme, et la version qui est réalisable ne vaut pas le risque. Le scope vous confine à un répertoire qui ne contrôle rien, l’en-tête qui le corrigerait est supprimé, et la méthode du reverse proxy n’est pas supportée. Créez-en un quand même et vous êtes à une erreur près d’afficher des prix périmés que vous ne pourrez pas rappeler.

Les vitrines headless sont un sujet différent. Si vous contrôlez la racine, les règles web normales s’appliquent et le code ci-dessus est un bon point de départ.

Pour tous ceux sur la Boutique en ligne, le même effort consacré au thème rapporte plus :

• Supprimez les scripts d’applications que vous n’utilisez pas. Le JavaScript tiers est le coût contrôlable le plus important sur la plupart des boutiques, et supprimer un script est bien plus efficace que de le mettre en cache.
• Corrigez d’abord les images. Un bon dimensionnement, des formats modernes et le chargement eager de l’image hero. Notre guide Shopify lazy load images explique l’ordre d’importance.
• Retirez les ressources qui bloquent le rendu et minifiez ce qui reste. Consultez comment minifier le CSS et le JavaScript sur Shopify pour savoir ce que Shopify gère déjà et ce qu’il ne fait pas.
• Allégez le thème lui-même. La séquence complète est dans comment accélérer un thème Shopify.

Chacune de ces actions est réversible depuis l’admin. Aucune d’entre elles ne peut bloquer un acheteur sur une copie en cache de votre boutique.

Cette réversibilité est la raison pour laquelle nous avons créé Fudge pour écrire du code de thème natif plutôt que d’injecter une surcouche (runtime layer). Les changements atterrissent sous forme de Liquid, CSS et JavaScript dans votre thème, vous pouvez donc les lire, les annuler (roll back) et les conserver après avoir cessé de nous payer. Il en va de même pour tout ce que vous construisez avec l’éditeur de boutique Shopify.

FAQ