12k
All articles

Écrire des service workers sous forme de modules ES

Convertissez un service worker en module ES : imports statiques, code partagé, options de build, cache des mises à jour et solution de repli pour les anciens navigateurs.

OpenReplay Team
OpenReplay Team
Écrire des service workers sous forme de modules ES

Pour exécuter un service worker en tant que module ES, appelez navigator.serviceWorker.register('/sw.js', { type: 'module' }). Sans cette option, le navigateur charge le fichier comme un script classique, et import et export provoquent alors des erreurs de syntaxe.

La plupart des équipes en arrivent là de la même manière. L’application est entièrement en ESM, construite avec Vite, mais le service worker reste un script classique qui appelle importScripts() sur un fichier de configuration copié à la main, lequel finit par se désynchroniser de l’application. Convertir le worker en module règle ce problème, mais les workers de type module obéissent à des règles différentes, et la prise en charge par les navigateurs n’est devenue complète qu’avec Firefox 147. Cet article traite de la modification de l’enregistrement, du partage de code avec la page, des règles qui font échouer les workers de type module, du comportement des mises à jour, du résultat du build et d’une solution de repli. Pour les bases du cycle de vie, consultez A Practical Guide to Service Workers.

Points clés

  • Passer { type: 'module' } à register() fait du service worker un module ES. Le type par défaut est 'classic'.
  • Appeler importScripts() dans un worker de type module lève une TypeError : chaque appel doit donc être remplacé par un import statique.
  • Le import() dynamique et les import maps ne fonctionnent pas dans les service workers : chaque spécificateur doit donc se résoudre en une URL réelle au moment du build.
  • Les service workers de type module fonctionnent dans Chrome et Edge 91+, Safari 15+ et Firefox 147+.
  • Avec le paramètre par défaut updateViaCache: 'imports', les vérifications de mise à jour peuvent servir les modules importés depuis le cache HTTP : attribuez donc des URL hachées ou des durées de cache courtes aux modules partagés.

Comment convertir un service worker en module ES ?

Convertir un service worker en module ES nécessite deux modifications : passer l’option type lors de l’enregistrement, et remplacer importScripts() par import. D’après la référence MDN de register(), type accepte 'classic' (valeur par défaut) ou 'module'.

Voici la version classique :

// config.js (classic)
self.CACHE_NAME = 'app-v3';

// sw.js (classic)
importScripts('/config.js');
console.log(self.CACHE_NAME);

Et la version module :

// config.js (module)
export const CACHE_NAME = 'app-v3';

// sw.js (module)
import { CACHE_NAME } from './config.js';
console.log(CACHE_NAME);

Les scripts de type module sont chargés via CORS, s’exécutent en mode strict et doivent être servis avec un type MIME JavaScript tel que text/javascript, comme l’explique la page MDN du constructeur Worker() au sujet des workers de type module.

Partager du code entre la page et le worker

La principale raison d’écrire un service worker sous forme de module ES est qu’un même module peut alors servir à la fois à la page et au worker. Placez le nom du cache et la liste de précache dans un seul fichier :

// config.js
export const CACHE_NAME = 'app-v3';
export const PRECACHE_URLS = ['/', '/index.html', '/offline.html'];

Le worker importe ces deux valeurs et utilise les appels standard de la Cache API :

// sw.js
import { CACHE_NAME, PRECACHE_URLS } from './config.js';

self.addEventListener('install', (event) => {
  event.waitUntil(
    caches.open(CACHE_NAME).then((cache) => cache.addAll(PRECACHE_URLS))
  );
});

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

La page importe le même fichier :

// main.js, loaded via <script type="module">
import { CACHE_NAME } from './config.js';

console.debug('Expected cache:', CACHE_NAME);
navigator.serviceWorker.register('/sw.js', { type: 'module' });

Il suffit désormais de modifier la chaîne de version à un seul endroit pour que les deux côtés prennent en compte le changement.

Trois règles qui font échouer les service workers de type module

Trois règles sont à l’origine de la plupart des échecs lors de la conversion d’un service worker classique en module ES.

  1. Pas de importScripts(). Les étapes de importScripts() définies dans la spécification HTML lèvent une TypeError lorsque le type du scope global est "module", et la référence MDN de importScripts() oriente les workers de type module vers import. Si votre worker charge une bibliothèque via importScripts(), il vous faut une version ESM de cette bibliothèque.
  2. Pas de import() dynamique. La page MDN ServiceWorker indique que la spécification interdit le import() dynamique dans les service workers et que son appel lève une exception. Chargez dès le départ, par un import statique, tout code dont vous avez besoin de manière conditionnelle.
  3. Pas d’import maps. Les import maps ne s’appliquent pas dans les service workers, et leur prise en charge dans les workers n’en est encore qu’au stade de proposition ouverte (whatwg/html #8173). Chaque spécificateur doit être une URL relative ou absolue. Un nom nu comme 'idb' ne sera pas résolu en tant que spécificateur de module : une étape de build doit donc le réécrire ou l’intégrer directement (inline).

Impact des modules importés sur les mises à jour du service worker

Dans un service worker de type module, les modules importés font partie de la vérification de mise à jour. Une modification d’un fichier importé statiquement, comme config.js, peut déclencher le processus de mise à jour même si sw.js n’a pas changé, de la même manière que pour les dépendances chargées via importScripts(), comme le souligne l’annonce par Chrome des service workers de type module.

L’option updateViaCache détermine si ces vérifications peuvent utiliser le cache HTTP :

ValeurScript principalModules importés
'imports' (par défaut)Toujours depuis le réseauCache HTTP autorisé
'all'Cache HTTP autoriséCache HTTP autorisé
'none'Toujours depuis le réseauToujours depuis le réseau

Avec la valeur par défaut, un module partagé servi depuis une URL non hachée avec un max-age long peut rester obsolète d’une vérification de mise à jour à l’autre. Vous pouvez servir les modules partagés depuis des URL hachées selon leur contenu, leur attribuer des durées de cache courtes, ou effectuer l’enregistrement avec updateViaCache: 'none'. Des replays de sessions montrant des utilisateurs encore sur l’ancienne interface après un déploiement, ou des requêtes vers des assets hachés qui n’existent plus, trahissent souvent ce type de bug de mise à jour. L’article Debugging service workers explique comment vérifier quelle version du worker est aux commandes.

Outils de build : ESM non bundlé ou fichier unique

Vite traite un service worker comme n’importe quel autre fichier de sortie : il doit être émis comme un point d’entrée distinct, à une URL stable et non hachée telle que /sw.js. Si l’URL change à chaque build, l’enregistrement pointe à chaque fois vers un script différent. Le répertoire public de Vite copie les fichiers sans les traiter, ce qui convient à un worker écrit à la main mais ne résout pas ses imports.

Il existe deux façons de construire un service worker de type module :

  • ESM non bundlé. sw.js et ses modules partagés sont livrés sous forme de fichiers distincts avec des spécificateurs d’URL, et l’enregistrement se fait avec type: 'module'. Chaque import correspond à une requête distincte et est couvert par la vérification de mise à jour.
  • Un fichier unique bundlé. Le bundler intègre tout, y compris les packages référencés par des spécificateurs nus, dans un seul script. Si ce résultat ne contient aucune instruction import, il s’exécute aussi comme worker classique, ce qui en fait votre solution de repli.

Solution de repli pour les navigateurs sans prise en charge des modules

Les quatre principaux moteurs prennent en charge les service workers de type module, d’après les données MDN browser-compat-data sur caniuse :

NavigateurPremière version prenant en charge type: 'module'
Chrome91
Edge91
Safari (macOS et iOS)15
Firefox147, d’après les notes de version de Firefox 147

Un build classique n’est nécessaire que pour les navigateurs plus anciens : Chrome et Edge 90 et antérieurs, Safari 14.1 et antérieurs, et Firefox 146 et antérieurs. Aucune API standard ne permet de détecter la prise en charge des modules, comme le montre la demande de détection de fonctionnalité w3c/ServiceWorker #1582. Un navigateur plus ancien ne rejette pas l’option type d’emblée : il télécharge le script, échoue à l’évaluer, puis register() est rejetée. Vous pouvez intercepter ce rejet :

async function registerSW() {
  if (!('serviceWorker' in navigator)) return;
  try {
    return await navigator.serviceWorker.register('/sw.js', { type: 'module' });
  } catch (err) {
    console.warn('Module service worker failed, falling back to classic:', err);
    return navigator.serviceWorker.register('/sw-classic.js');
  }
}

Cette solution de repli basée sur try/catch présente deux inconvénients. Les navigateurs plus anciens téléchargent le script module pour rien. Et le catch masque aussi les véritables erreurs du worker de type module dans les navigateurs compatibles : journalisez donc l’erreur avant de basculer sur la solution de repli.

Conclusion

Convertir un service worker en module se résume à l’option type et à trois règles : uniquement des imports statiques, pas de importScripts() et pas de spécificateurs nus. Pour commencer, regroupez dans un module partagé unique les constantes que votre worker et votre page dupliquent, effectuez l’enregistrement avec { type: 'module' }, et vérifiez la manière dont ce module est mis en cache afin qu’une modification parvienne bien aux utilisateurs via la vérification de mise à jour.

FAQ

Peut-on utiliser le top-level await dans un service worker de type module ?

Non. Le top-level await est interdit dans les service workers, car l'évaluation initiale doit se terminer de manière synchrone afin que les listeners tels que install et fetch soient attachés à temps. Chromium rejette l'enregistrement avec une TypeError. Cela s'applique également lorsque le await se trouve dans un module importé statiquement, car il rend asynchrone l'ensemble du graphe de modules. Déplacez l'initialisation asynchrone dans un gestionnaire install ou activate encapsulé dans event.waitUntil().

Le passage d'un service worker existant du type classic au type module, à la même URL, déclenche-t-il une mise à jour ?

Oui. La spécification Service Workers considère un changement de type de worker comme une mise à jour, même si l'URL du script et son contenu sont identiques. Appeler register('/sw.js', { type: 'module' }) sur un enregistrement classique existant installe un nouveau worker, qui suit ensuite le cycle de vie normal d'attente et d'activation. Un appel à register() avec la même URL, le même type et la même valeur updateViaCache se résout sans rien récupérer.

Un service worker de type module peut-il importer des modules depuis un CDN ou une autre origine ?

Oui, si l'autre origine l'autorise. Les imports de modules sont récupérés via CORS : un module cross-origin doit donc être servi avec un en-tête Access-Control-Allow-Origin qui autorise votre origine. Sinon, l'import échoue et register() est rejetée. Les appels classiques à importScripts() n'en ont pas besoin, car ils chargent les scripts en mode no-cors. Le script du service worker lui-même doit toujours être de même origine que la page qui l'enregistre.

Understand every bug

Uncover frustrations, understand bugs and fix slowdowns like never before with OpenReplay — self-hosted, with full data ownership.

Star on GitHub

We use cookies to improve your experience. By using our site, you accept cookies.