API Cache Storage : gérer le cache de ressources en JavaScript

Qu'est-ce que l'API Cache Storage ?

L'API Cache Storage est une interface JavaScript qui permet de stocker des paires requête/réponse HTTP directement dans le navigateur. Concrètement, vous pouvez y enregistrer une page HTML, une feuille de style, une image ou une réponse JSON — et les relire plus tard sans aucune connexion réseau.

C'est la technologie sur laquelle s'appuient les Service Workers pour faire fonctionner les applications web hors ligne. Mais l'API Cache Storage peut aussi être utilisée directement depuis une page web, sans Service Worker, pour accélérer le chargement de ressources ou pré-charger du contenu.

La différence avec localStorage est importante : localStorage stocke des chaînes de caractères simples, l'API Cache Storage stocke des objets Response HTTP complets — avec leurs en-têtes, leur statut et leur corps. C'est conçu pour les ressources réseau, pas pour les données applicatives.

Trois raisons d'utiliser l'API Cache Storage en 2026 :

• Mode hors ligne : les ressources mises en cache restent accessibles sans connexion.
• Chargement plus rapide : servir une ressource depuis le cache local est toujours plus rapide qu'un aller-retour réseau.
• Contrôle total : contrairement à l'AppCache déprécié, vous décidez exactement quoi mettre en cache, quand, et combien de temps.

Compatibilité navigateurs

L'API Cache Storage est supportée par tous les navigateurs modernes : Chrome 40+, Firefox 39+, Safari 11.1+, Edge 17+. Elle fonctionne aussi bien dans un Service Worker que dans le contexte d'une page web ordinaire. Internet Explorer ne la supporte pas.

Vérifiez toujours la disponibilité avant d'utiliser l'API :

if ('caches' in window) {
  // L'API Cache Storage est disponible
} else {
  // Navigateur trop ancien : prévoir un fallback
  console.log('Cache Storage non supporté.');
}
  

Ouvrir un cache avec caches.open()

Tout commence par caches.open(). Cette méthode ouvre un cache existant ou en crée un nouveau si le nom n'existe pas encore. Elle retourne une promesse qui se résout avec un objet Cache sur lequel on peut ensuite ajouter, lire ou supprimer des ressources.

Le nom du cache est une chaîne libre — par convention on y inclut un numéro de version pour faciliter la gestion des mises à jour.

// Ouvrir (ou créer) un cache nommé 'mon-cache-v1'
caches.open('mon-cache-v1').then(function(cache) {
  console.log('Cache ouvert :', cache);
});
  

Ajouter des ressources au cache

Une fois le cache ouvert, trois méthodes permettent d'y ajouter des ressources.

cache.add() : ajouter une seule ressource

cache.add() prend une URL, fait une requête réseau pour la récupérer, et stocke la réponse dans le cache. Si la requête échoue ou retourne un statut d'erreur, la promesse est rejetée et rien n'est mis en cache.

caches.open('mon-cache-v1').then(function(cache) {
  // Télécharge /style.css et le stocke dans le cache
  cache.add('/style.css').then(function() {
    console.log('style.css mis en cache.');
  });
});
  

cache.addAll() : ajouter plusieurs ressources d'un coup

cache.addAll() prend un tableau d'URL et les met toutes en cache en une seule opération. Si l'une des requêtes échoue, l'ensemble de l'opération échoue — rien n'est mis en cache. C'est la méthode utilisée dans les Service Workers pour pré-cacher les ressources au moment de l'installation.

caches.open('mon-cache-v1').then(function(cache) {
  return cache.addAll([
    '/',
    '/style.css',
    '/app.js',
    '/logo.png',
    '/offline.html'
  ]);
}).then(function() {
  console.log('Toutes les ressources sont en cache.');
}).catch(function(erreur) {
  // Si une seule URL échoue, toutes les autres sont annulées
  console.log('Échec du pré-cache :', erreur);
});
  

cache.put() : stocker une réponse existante

cache.put() est différent : il ne fait pas de requête réseau. Il stocke directement une paire requête/réponse que vous avez déjà. C'est utile quand vous avez intercepté une réponse réseau et voulez la conserver pour une utilisation ultérieure.

// Faire une requête réseau, puis stocker la réponse manuellement
fetch('/donnees.json').then(function(reponse) {
  if (reponse.ok) {
    caches.open('mon-cache-v1').then(function(cache) {
      // On clone la réponse : une réponse ne peut être lue qu'une seule fois
      cache.put('/donnees.json', reponse.clone());
    });
  }
  return reponse;
});
  

Récupérer une ressource du cache

caches.match() cherche une ressource dans tous les caches disponibles et retourne la première correspondance trouvée. Si aucune correspondance n'existe, la promesse se résout avec undefined — elle ne rejette pas.

// Chercher /style.css dans tous les caches
caches.match('/style.css').then(function(reponse) {
  if (reponse) {
    console.log('Ressource trouvée en cache :', reponse);
  } else {
    // Absente du cache : aller chercher sur le réseau
    console.log('Pas en cache, requête réseau nécessaire.');
  }
});
  

Pour chercher dans un cache spécifique plutôt que dans tous les caches, ouvrez d'abord ce cache puis appelez cache.match() sur l'objet retourné :

caches.open('mon-cache-v1').then(function(cache) {
  cache.match('/style.css').then(function(reponse) {
    if (reponse) {
      console.log('Trouvé dans mon-cache-v1');
    }
  });
});
  

Lister les caches disponibles

caches.keys() retourne un tableau avec les noms de tous les caches existants pour cette origine. C'est utile pour inspecter ce qui est stocké ou pour nettoyer les anciennes versions.

caches.keys().then(function(noms) {
  console.log('Caches disponibles :', noms);
  // Exemple de résultat : ['mon-cache-v1', 'mon-cache-v2']
});
  

Supprimer des entrées du cache

Deux niveaux de suppression sont disponibles : supprimer une ressource précise dans un cache, ou supprimer un cache entier.

Supprimer une ressource précise

caches.open('mon-cache-v1').then(function(cache) {
  cache.delete('/style.css').then(function(supprime) {
    if (supprime) {
      console.log('/style.css supprimé du cache.');
    } else {
      console.log('/style.css absent du cache.');
    }
  });
});
  

Supprimer un cache entier

C'est la technique utilisée dans les Service Workers pour nettoyer les anciennes versions du cache lors de l'activation d'une nouvelle version.

// Supprimer le cache 'mon-cache-v1' et toutes ses entrées
caches.delete('mon-cache-v1').then(function(supprime) {
  if (supprime) {
    console.log('Cache mon-cache-v1 supprimé.');
  }
});
  

Récapitulatif des méthodes

Voici un résumé des méthodes de l'API Cache Storage les plus utiles au quotidien :

• caches.open(nom) : ouvre ou crée un cache
• caches.match(requête) : cherche dans tous les caches
• caches.keys() : liste les noms de tous les caches
• caches.delete(nom) : supprime un cache entier
• cache.add(url) : télécharge et met en cache une URL
• cache.addAll([urls]) : télécharge et met en cache plusieurs URL
• cache.put(requête, réponse) : stocke une paire requête/réponse existante
• cache.match(requête) : cherche dans un cache spécifique
• cache.delete(requête) : supprime une entrée précise
• cache.keys() : liste les requêtes stockées dans un cache

Par carabde: le 13 avril 2026