Cache.addAll() — Methode · JavaScript-Referenz

Signatur

Cache.prototype.addAll(requests)

Beschreibung

Cache.addAll() bekommt ein Array von URLs oder Request-Objekten, ruft jede Ressource per fetch() ab und speichert die Anfrage-Antwort-Paare im jeweiligen Cache. Funktional entspricht das einem fetch() für jeden Eintrag und anschließendem cache.put(), allerdings läuft alles atomar ab. Entweder landen alle Antworten im Cache oder keine.

Der typische Einsatz ist das Precaching im install-Ereignis eines Service Workers. Dort speichert man die „App-Shell“ vorab (HTML, CSS, JavaScript, Icons), damit die Anwendung später offline läuft. Das zurückgegebene Promise übergibt man an event.waitUntil(). Die Installation gilt dann erst als erfolgreich, wenn alle Ressourcen im Cache liegen.

Das Promise wird abgelehnt (TypeError), wenn eine Antwort keinen Status im Bereich 200–299 hat (response.ok === false) oder ein Netzwerkfehler auftritt. Schon eine einzige fehlerhafte URL lässt also den ganzen Vorgang scheitern. Bereits vorhandene Einträge mit gleicher Anfrage werden überschrieben.

Parameter

Name	Typ	Default	Beschreibung
$requests Pflicht	Array<string \| Request> \| Iterable<string \| Request>		Liste der Ressourcen, die abgerufen und gespeichert werden sollen. Möglich sind URL-Strings (relativ zur Service-Worker- bzw. Dokument-URL) und `Request`-Objekte.

Rückgabewert

Typ

Promise<undefined>

Beschreibung

Ein Promise, das mit undefined erfüllt wird, sobald alle Antworten gespeichert sind. Bei einem Netzwerkfehler oder einer Antwort ohne 2xx-Status wird es mit einem TypeError abgelehnt. Wird dieselbe Anfrage mehrfach übergeben, erfolgt die Ablehnung mit einem InvalidStateError.

Beispiele

App-Shell im install-Ereignis des Service Workers vorab speichern

// sw.js
const CACHE_NAME = 'app-shell-v1';
const PRECACHE_URLS = [
  '/',
  '/index.html',
  '/styles/main.css',
  '/scripts/app.js',
  '/icons/icon-192.png'
];

self.addEventListener('install', (event) => {
  event.waitUntil(
    (async () => {
      const cache = await caches.open(CACHE_NAME);
      await cache.addAll(PRECACHE_URLS);
      console.log('App-Shell gespeichert');
    })()
  );
});

App-Shell gespeichert

Fehler behandeln: eine ungültige URL verhindert das Speichern aller Einträge

const precache = async () => {
  const cache = await caches.open('demo-v1');
  try {
    await cache.addAll(['/index.html', '/gibt-es-nicht.css']);
  } catch (err) {
    console.error('Precaching fehlgeschlagen:', err.name);
  }
  // Wegen der Atomarität wurde auch /index.html nicht gespeichert
  const keys = await cache.keys();
  console.log('Einträge im Cache:', keys.length);
};

precache();

Precaching fehlgeschlagen: TypeError Einträge im Cache: 0

Request-Objekte mit eigenen Optionen übergeben

const cacheFonts = async () => {
  const cache = await caches.open('fonts-v1');
  const requests = [
    new Request('https://cdn.example.com/fonts/inter.woff2', { mode: 'cors' }),
    new Request('/api/config.json', { cache: 'reload' }) // HTTP-Cache umgehen
  ];
  await cache.addAll(requests);
  const match = await cache.match('/api/config.json');
  console.log('Gespeichert:', match?.ok);
};

cacheFonts();

Gespeichert: true

Optionale Ressourcen getrennt und fehlertolerant speichern

self.addEventListener('install', (event) => {
  event.waitUntil((async () => {
    const cache = await caches.open('app-v2');
    // Kritische Dateien: atomar und verpflichtend
    await cache.addAll(['/', '/app.js', '/app.css']);
    // Optionale Dateien: einzeln, Fehler blockieren die Installation nicht
    const optional = ['/images/hero.jpg', '/videos/intro.mp4'];
    const results = await Promise.allSettled(optional.map((url) => cache.add(url)));
    console.log(results.map((r) => r.status));
  })());
});

["fulfilled", "rejected"]

// Wichtig · Fallstricke

Alles oder nichts: Liefert eine einzige Ressource z. B. 404 oder 500, wird das ganze Promise abgelehnt und kein Eintrag gespeichert. Im install-Ereignis schlägt dann die Installation des Service Workers fehl. Deshalb sollten nur wirklich benötigte Dateien in addAll() stehen. Optionales speichert man besser einzeln mit cache.add() bzw. cache.put().
Opake Antworten: Anfragen mit mode: 'no-cors' an fremde Ursprünge liefern Status 0 und gelten nicht als ok. Damit scheitert addAll(). Für solche Antworten braucht man fetch() + cache.put().
Keine Duplikate: Kommt dieselbe Anfrage mehrfach vor (gleiche URL, Methode und passender Vary-Header), wird mit InvalidStateError abgelehnt.
Nur GET: Nur GET-Anfragen sind erlaubt. Andere Methoden führen zu einem TypeError. Das Schema muss http oder https sein.
HTTP-Cache: addAll() kann veraltete Antworten aus dem HTTP-Cache des Browsers übernehmen. Abhilfe schaffen versionierte URLs (z. B. app.3f2a.js) oder new Request(url, { cache: 'reload' }).
Speicherplatz: Ist das Speicherkontingent erschöpft, wird das Promise mit QuotaExceededError abgelehnt.
Kompatibilität: Die Methode wird von allen modernen Browsern unterstützt, aber nur in sicheren Kontexten (HTTPS oder localhost). Sie steht über caches sowohl im Fenster als auch in Workern zur Verfügung.

Siehe auch

Cache Cache.add() Cache.put() Cache.match() CacheStorage.open() ExtendableEvent.waitUntil() Request