Votre premier site disponible hors ligne : une stratégie de cache avec service worker que vous pouvez expliquer
Un site qui perd sa connexion ne devrait pas forcément devenir une page vide. Pour un petit outil, une documentation ou une application légère, une interface disponible hors ligne peut rester utile lorsque le réseau ne répond plus.
Les service workers rendent cela possible. Ces scripts d’arrière-plan interceptent les requêtes des pages qu’ils contrôlent et peuvent renvoyer des réponses mises en cache. Ce mécanisme est puissant, mais un cache mal conçu peut aussi afficher des pages périmées ou laisser des données privées sur un appareil partagé.
Ce tutoriel construit un petit site utilisable hors ligne avec une stratégie de cache volontairement limitée. L’objectif est de savoir exactement ce qui est conservé et pourquoi.
Distinguer trois systèmes de stockage
Les service workers utilisent souvent l’API Cache Storage, qui conserve des paires requête/réponse. Elle diffère de localStorage, destiné à de simples paires clé/valeur sous forme de chaînes, et d’IndexedDB, mieux adapté aux données structurées d’une application.
Une répartition utile des responsabilités est la suivante :
- Cache Storage : fichiers publics et versionnés de l’application, comme le HTML, le CSS, le JavaScript ou une page hors ligne.
- IndexedDB : données structurées que l’application enregistre et synchronise volontairement.
- Serveur : données de référence des comptes, autorisations et transactions.
L’article sur localStorage, sessionStorage et les cookies explique pourquoi il ne faut pas placer sans précaution des secrets de session dans le stockage du navigateur. Un cache de service worker n’est pas un coffre-fort privé : mettre une réponse en cache ne la chiffre pas.
Commencer par une petite application
Créez un dossier contenant quatre fichiers :
offline-demo/
index.html
app.css
app.js
sw.js
Utilisez du HTML et des liens ordinaires. La page doit fonctionner en ligne même si l’enregistrement de son service worker échoue :
<!doctype html>
<html lang="en">
<head>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width, initial-scale=1">
<title>Offline Demo</title>
<link rel="stylesheet" href="./app.css">
<script src="./app.js" defer></script>
</head>
<body>
<main>
<h1>Offline Demo</h1>
<p>This page keeps a small app shell available offline.</p>
<p id="status" role="status">Checking offline support...</p>
<p><a href="./index.html">Return to the start page</a></p>
</main>
</body>
</html>
Dans app.css, ajoutez quelques règles de mise en page adaptative :
body {
font: 1rem/1.6 system-ui, sans-serif;
margin: 0;
padding: clamp(1rem, 4vw, 3rem);
color: #17212b;
background: #fff;
}
main { max-width: 44rem; margin-inline: auto; }
a { color: #0754a6; }
Cette présentation est volontairement simple. Le fonctionnement hors ligne ne devrait pas dépendre d’un framework JavaScript complexe ou d’une feuille de style distante.
Enregistrer le service worker
Dans app.js :
const statusMessage = document.querySelector("#status");
if ("serviceWorker" in navigator) {
window.addEventListener("load", async () => {
try {
await navigator.serviceWorker.register("./sw.js");
statusMessage.textContent = "Service worker registered. Check installation in DevTools before testing.";
} catch (error) {
statusMessage.textContent = "Service worker registration failed.";
console.error("Service worker registration failed:", error);
}
});
} else {
statusMessage.textContent = "This browser does not support service workers.";
}
La résolution de la promesse d’enregistrement ne prouve pas que l’installation et la mise en cache initiale sont terminées. Vérifiez dans les outils de développement que le worker est activé avant de tester le mode hors ligne. L’enregistrement ne garantit pas non plus que la page déjà ouverte soit immédiatement contrôlée. Un nouveau service worker prend généralement le contrôle après une navigation ou une actualisation. Il nécessite un contexte sécurisé, comme HTTPS ou l’origine locale particulière http://localhost.
Ne mettre en cache que les fichiers de base
Créez sw.js :
const CACHE_PREFIX = "offline-demo-";
const CACHE_NAME = `${CACHE_PREFIX}v1`;
const SHELL = ["./", "./index.html", "./app.css", "./app.js"]
.map((path) => new URL(path, self.registration.scope).href);
self.addEventListener("install", (event) => {
event.waitUntil(
caches.open(CACHE_NAME).then((cache) => cache.addAll(
SHELL.map((url) => new Request(url, {
cache: "reload",
credentials: "omit"
}))
))
);
});
self.addEventListener("activate", (event) => {
event.waitUntil(
caches.keys().then((names) => Promise.all(
names
.filter((name) => name.startsWith(CACHE_PREFIX) && name !== CACHE_NAME)
.map((name) => caches.delete(name))
))
);
});
self.addEventListener("fetch", (event) => {
const request = event.request;
if (request.method !== "GET") return;
if (!SHELL.includes(request.url)) return;
event.respondWith((async () => {
const cache = await caches.open(CACHE_NAME);
if (request.mode === "navigate") {
try {
return await fetch(request);
} catch {
return (await cache.match(request)) || Response.error();
}
}
return (await cache.match(request)) || fetch(request);
})());
});
L’exemple donne la priorité au réseau pour les navigations et la priorité au cache pour les autres requêtes des fichiers de base. Si le réseau échoue, une navigation vers la page de départ utilise sa propre réponse en cache. Les erreurs HTTP comme 404 ou 500 sont toujours renvoyées par fetch() : elles ne déclenchent pas ce recours au cache. Une connexion lente peut aussi retarder la tentative d’accès au réseau.
La liste autorisée contient quatre URL exactes sur la même origine que le worker, résolues à partir de sa portée d’enregistrement. Les autres pages, API, variantes avec paramètres de requête, méthodes autres que GET et ressources distantes suivent le traitement réseau normal du navigateur. Elles ne sont ni ajoutées au cache ni remplacées par la page de départ. Sur un site de plusieurs pages, prévoyez une réponse hors ligne dédiée au lieu de présenter l’accueil à la place d’un article indisponible.
Les quatre entrées doivent être des fichiers statiques publics, servis sans réponse personnalisée ni redirection vers une connexion. Les requêtes d’installation omettent les informations d’authentification et utilisent cache: "reload" pour éviter de reprendre une ancienne entrée du cache HTTP lors de la création d’une nouvelle version. Un échec de addAll() fait échouer l’installation : examinez les outils de développement avant de considérer le fonctionnement hors ligne comme prêt.
Les lectures utilisent le cache nommé de la version courante, plutôt que caches.match(), qui peut chercher dans les autres caches de l’origine. Cela évite qu’une autre application ou un worker en attente fournisse les réponses de cette version. Le guide MDN des service workers décrit leur cycle de vie. La référence CacheStorage.match() (en anglais) précise la recherche entre caches.
Comprendre le passage à la version deux
Le navigateur peut conserver un service worker actif tant que des pages qu’il contrôle restent ouvertes. Une modification de sw.js lui permet de découvrir un nouveau worker, mais celui-ci peut attendre la fermeture des pages contrôlées avant de s’activer. L’exemple évite volontairement skipWaiting() et clients.claim() pour ne pas remplacer sans préavis la logique utilisée par une session ouverte.
Lorsque les fichiers statiques changent, passez CACHE_NAME de v1 à v2. Pendant l’installation, le nouveau worker récupère les fichiers actualisés. Pendant l’activation, il supprime les anciens caches ayant le même préfixe. Choisissez un préfixe propre à cette application : le stockage est partagé par toute l’origine, et non isolé selon la portée du service worker.
Même sans activation immédiate, un risque de déploiement demeure : une navigation donnant la priorité au réseau peut charger un nouveau HTML alors qu’un ancien worker sert encore son JavaScript et son CSS en cache. Des versions incompatibles peuvent casser la page. Pour une application plus importante, des URL versionnées ou des noms de fichiers contenant une empreinte du contenu constituent une meilleure approche à long terme. Réfléchissez à la présentation des mises à jour avant d’ajouter des raccourcis d’activation.
Tester le fonctionnement hors ligne
Utilisez un serveur local, pas une URL file://. Avec Python installé, lancez cette commande depuis le dossier offline-demo/ :
python3 -m http.server 8000
Ouvrez http://localhost:8000/ et examinez les outils de développement du navigateur :
- Dans Application > Service Workers, ou la rubrique équivalente, attendez l’activation, puis actualisez et vérifiez que la page est contrôlée.
- Dans Application > Cache Storage, vérifiez que seules les entrées prévues existent.
- Activez la simulation de perte de connexion du navigateur et rechargez la page.
- Vérifiez que l’interface reste utilisable sans police distante, script de mesure d’audience ni appel d’API.
- Revenez en ligne, modifiez la feuille de style et changez la version du cache dans
sw.js. Déclenchez une mise à jour dans les outils de développement ou revisitez la page. Observez le nouveau worker en attente pendant que l’ancien contrôle un onglet ouvert. Fermez tous les onglets de la démonstration et rouvrez-la pour permettre l’activation ; une simple actualisation peut ne pas libérer l’ancien worker. - Désenregistrez le worker et effacez les données du site, puis vérifiez que la page fonctionne toujours normalement en ligne.
Le guide d’inspection des requêtes réseau aide à trouver le panneau Réseau et à examiner l’origine des réponses. Pour diagnostiquer leur fraîcheur, distinguez ce cache explicite du cache HTTP et de ses règles Cache-Control et ETag. Le constructeur de commandes cURL aide à examiner les réponses HTTP d’un serveur distant ; cURL n’exécute pas et ne teste pas un service worker de navigateur.
Les pièges qui apparaissent après la mise en ligne
Conserver du HTML authentifié. Évitez de mettre en cache des pages de compte, confirmations de commande ou réponses d’API privées dans des caches aux noms partagés. Cache Storage est associé à une origine et accessible aux scripts qui s’y exécutent ; il ne constitue pas un contrôle d’accès.
Conserver implicitement des ressources distantes. Une stratégie donnant la priorité au cache pour toutes les requêtes peut retenir des scripts tiers ou des réponses qui n’étaient pas destinés à une réutilisation hors ligne. Gardez une liste autorisée explicite.
Traiter la connexion comme un simple booléen. navigator.onLine n’est qu’un indice. Une requête peut échouer alors que le navigateur se déclare connecté, ou un réseau local peut exister sans accès à Internet. Gérez les échecs au niveau des requêtes.
Oublier les limites du stockage. Un navigateur peut évincer les données d’un site lorsqu’il manque de place. Le mode hors ligne doit gérer leur absence ; un stockage permanent n’est pas garanti.
Croire qu’un manifeste PWA suffit au mode hors ligne. Le manifeste décrit l’identité de l’application et des comportements liés à son installation. Il n’implémente pas la stratégie de cache. L’article sur le brouillon de travail Web App Manifest complète ce sujet, mais ces fonctions remplissent des rôles différents.
Présenter des données hors ligne comme des données à jour. Si l’interface affiche des informations en cache, indiquez leur ancienneté ou leur état. Pour des données financières, médicales ou liées à des autorisations, ne présentez pas silencieusement une valeur périmée comme actuelle.
Quand ajouter la modification hors ligne
Les pages en lecture seule et les petits outils constituent un bon début. La modification hors ligne nécessite davantage : une base locale durable, une file d’attente explicite, une résolution des conflits, des nouvelles tentatives, un état de synchronisation visible et une gestion de la déconnexion du compte. Une écriture en attente n’est pas confirmée par le serveur simplement parce que le formulaire l’a acceptée localement.
Pour une interaction complexe avec une API, un diagramme d’états créé dans l’éditeur Mermaid peut distinguer les étapes “enregistré localement”, “en attente de synchronisation”, “confirmé par le serveur” et “conflit à examiner”.
Commencez par l’exemple de quatre fichiers et vérifiez ses entrées Cache Storage. Élargissez la liste autorisée seulement pour répondre à un besoin hors ligne précis.