Cache.add() — Methode · JavaScript-Referenz

Signatur

Cache.prototype.add(request)

Beschreibung

Die Methode add() des Cache-Interfaces nimmt eine URL oder ein Request-Objekt entgegen, ruft die Ressource über das Netzwerk ab und legt das Paar aus Anfrage und Antwort im jeweiligen Cache ab. Funktional entspricht sie ungefähr diesem Ablauf: fetch(request) ausführen, bei einem Status außerhalb von 200–299 abbrechen und sonst cache.put(request, response) aufrufen.

Typischerweise wird add() im install-Ereignis eines Service Workers eingesetzt, um einzelne Ressourcen vorab zu cachen (Precaching), damit die Anwendung auch offline funktioniert. Für mehrere Ressourcen auf einmal gibt es Cache.addAll(). Diese Methode ist atomar: Scheitert eine einzige Anfrage, wird gar nichts gespeichert.

Wichtig: add() legt nur erfolgreiche Antworten ab. Wenn der Server mit 404 oder 500 antwortet, wird das Promise mit einem TypeError abgelehnt. Einen bereits vorhandenen Eintrag zur selben Anfrage überschreibt add(). Die Methode ist auch außerhalb von Service Workers über window.caches nutzbar, allerdings nur in sicheren Kontexten (HTTPS oder localhost).

Parameter

Name	Typ	Default	Beschreibung
$request Pflicht	string \| URL \| Request		Die Ressource, die abgerufen und gespeichert werden soll. Das kann eine URL (als String oder `URL`-Objekt) oder ein fertiges `Request`-Objekt sein. Relative URLs werden relativ zur Basis-URL des Skripts aufgelöst.

Rückgabewert

Typ

Promise<undefined>

Beschreibung

Ein Promise, das mit undefined erfüllt wird, sobald die Antwort im Cache liegt. Abgelehnt wird es mit einem TypeError, wenn die URL-Schema nicht http/https ist, die Anfrage-Methode nicht GET ist, der Antwortstatus außerhalb von 200–299 liegt oder ein Netzwerkfehler auftritt.

Beispiele

Offline-Seite im install-Ereignis eines Service Workers vorab cachen

// sw.js
const CACHE_NAME = 'app-v1';

self.addEventListener('install', (event) => {
  event.waitUntil(
    (async () => {
      const cache = await caches.open(CACHE_NAME);
      await cache.add('/offline.html');
      console.log('Offline-Seite gecacht');
    })()
  );
});

Offline-Seite gecacht

Fehlerbehandlung bei nicht erfolgreicher Antwort

const cacheResource = async (url) => {
  const cache = await caches.open('assets-v1');
  try {
    await cache.add(url);
    console.log(`Gespeichert: ${url}`);
  } catch (err) {
    // z. B. bei 404, 500 oder Netzwerkfehler
    console.warn(`Konnte ${url} nicht cachen:`, err.name);
  }
};

await cacheResource('/styles/main.css');
await cacheResource('/gibt-es-nicht.js');

Gespeichert: /styles/main.css Konnte /gibt-es-nicht.js nicht cachen: TypeError

Request-Objekt mit eigenen Optionen hinzufügen und prüfen

const cache = await caches.open('api-v1');

const request = new Request('/api/config.json', {
  credentials: 'same-origin',
  cache: 'no-store' // HTTP-Cache umgehen, frische Version holen
});

await cache.add(request);

const cached = await cache.match('/api/config.json');
console.log(cached ? `Im Cache, Status ${cached.status}` : 'Nicht gefunden');

Im Cache, Status 200

Äquivalent mit fetch() und put() – für Fälle mit eigener Logik

const cache = await caches.open('assets-v1');
const url = '/images/logo.svg';

// entspricht cache.add(url), aber mit Einfluss auf die Antwort
const response = await fetch(url);
if (!response.ok) {
  throw new TypeError(`Fehlerhafte Antwort: ${response.status}`);
}
await cache.put(url, response);
console.log('Logo gespeichert');

Logo gespeichert

// Wichtig · Fallstricke

Nur 2xx-Antworten: Ältere Browser (z. B. Chrome vor Version 46) speicherten auch Fehlerantworten. Heute lehnt add() alle Statuscodes außerhalb von 200–299 mit einem TypeError ab. Wer Fehlerseiten oder opake Antworten cachen will, nimmt fetch() plus put().
Nur GET und http(s): POST-Anfragen oder Schemata wie chrome-extension: oder data: führen zu einem TypeError.
Cross-Origin: Ressourcen anderer Herkunft ohne CORS-Header liefern opake Antworten (Status 0). add() scheitert an diesen, weil 0 kein 2xx-Status ist.
Überschreiben: Ein vorhandener Eintrag mit passender Anfrage wird ersetzt. Die Header in Vary werden beim Abgleich berücksichtigt.
HTTP-Cache: Die Anfrage läuft über den normalen Browser-Cache. Veraltete Dateien vermeidet man mit new Request(url, { cache: 'reload' }) oder mit versionierten URLs.
Speicherplatz: Bei vollem Speicher wird das Promise mit QuotaExceededError abgelehnt. Den verfügbaren Platz zeigt navigator.storage.estimate().
Kompatibilität: Wird von allen modernen Browsern unterstützt, aber nur in sicheren Kontexten (HTTPS oder localhost). In manchen privaten Browsermodi ist caches nicht verfügbar oder beschränkt.

Siehe auch

Cache.addAll() Cache.put() Cache.match() Cache.delete() CacheStorage.open() Cache Request