Cache.put() — Methode · JavaScript-Referenz

Signatur

Cache.prototype.put(request, response)

Beschreibung

Cache.put() legt eine Response unter einem Request (oder einer URL) als Schlüssel im Cache ab. Anders als Cache.add() und Cache.addAll() holt put() nichts selbst aus dem Netz: Du übergibst die Antwort, die gespeichert werden soll. So hast du die volle Kontrolle darüber, was und wann gespeichert wird.

Typische Einsatzorte sind Service Worker mit Caching-Strategien wie „Network first“ oder „Stale-while-revalidate“: Eine Anfrage wird mit fetch() ausgeführt, eine Kopie der Antwort (response.clone()) kommt per put() in den Cache und das Original geht an die Seite. Du kannst auch selbst gebaute Antworten speichern, z. B. new Response(JSON.stringify(data)).

Gibt es schon einen Eintrag mit passendem Schlüssel, wird er überschrieben. Beim Abgleich zählen URL und Methode; der Vary-Header der Antwort wird ebenfalls beachtet. Anders als add() speichert put() auch Antworten mit Fehlerstatus (z. B. 404 oder 500). Prüfe deshalb vorher selbst response.ok.

Parameter

Name	Typ	Default	Beschreibung
$request Pflicht	Request \| string \| URL		Schlüssel des Eintrags. Ein `Request`-Objekt oder eine URL, aus der intern ein `Request` erzeugt wird. Nur Anfragen mit `GET` und dem Schema `http:` oder `https:` sind erlaubt.
$response Pflicht	Response		Die Antwort, die unter dem Schlüssel gespeichert wird. Ihr Body wird beim Speichern gelesen. Die Antwort darf nicht den Status `206` haben und keinen `Vary: *`-Header tragen.

Rückgabewert

Typ

Promise<undefined>

Beschreibung

Ein Promise, das mit undefined erfüllt wird, sobald der Eintrag gespeichert ist. Es wird mit einem TypeError abgelehnt, wenn die Anfrage keine GET-Anfrage ist, das Schema nicht erlaubt ist, die Antwort den Status 206 oder Vary: * hat oder ihr Body schon gelesen wurde. Ist der Speicherplatz voll, wird es mit einer QuotaExceededError-DOMException abgelehnt.

Beispiele

Antwort holen und manuell cachen

const cacheAntwort = async (url) => {
  const cache = await caches.open('api-v1');
  const response = await fetch(url);

  // Fehlerantworten nicht speichern – put() würde sie sonst übernehmen
  if (!response.ok) {
    throw new Error(`HTTP ${response.status}`);
  }

  await cache.put(url, response);
  console.log('Gespeichert:', url);
};

cacheAntwort('/api/produkte.json');

Gespeichert: /api/produkte.json

Service Worker: Network-first mit clone()

// sw.js
const CACHE = 'seiten-v1';

self.addEventListener('fetch', (event) => {
  if (event.request.method !== 'GET') return;

  event.respondWith((async () => {
    const cache = await caches.open(CACHE);
    try {
      const netz = await fetch(event.request);
      if (netz.ok) {
        // Kopie in den Cache, Original an die Seite
        event.waitUntil(cache.put(event.request, netz.clone()));
      }
      return netz;
    } catch {
      // Offline: auf den Cache zurückgreifen
      return (await cache.match(event.request)) ?? Response.error();
    }
  })());
});

Selbst erzeugte Response speichern

const speichereEinstellungen = async (einstellungen) => {
  const cache = await caches.open('app-daten');
  const response = new Response(JSON.stringify(einstellungen), {
    headers: { 'Content-Type': 'application/json' }
  });
  await cache.put('/lokal/einstellungen.json', response);

  const gespeichert = await cache.match('/lokal/einstellungen.json');
  console.log(await gespeichert.json());
};

speichereEinstellungen({ theme: 'dunkel', sprache: 'de' });

{ theme: 'dunkel', sprache: 'de' }

// Wichtig · Fallstricke

Body wird verbraucht: put() liest den Body der Response. Willst du dieselbe Antwort auch zurückgeben, speichere eine Kopie mit response.clone(). Ein schon gelesener Body führt zu einem TypeError.
Keine Statusprüfung: Anders als add()/addAll() speichert put() auch Antworten mit 4xx- und 5xx-Status. Prüfe also vorher response.ok, sonst liegen Fehlerseiten im Cache.
Opake Antworten: Antworten auf no-cors-Anfragen (type: 'opaque') lassen sich speichern. Ihr Status (immer 0) ist aber nicht lesbar, und Browser rechnen sie mit viel Polsterung auf das Speicherkontingent an (in Chrome mehrere MB pro Eintrag).
Einschränkungen: Nur GET-Anfragen, nur http(s), kein Status 206 (Teilinhalte) und kein Vary: *.
Kein automatisches Ablaufen: Einträge bleiben erhalten, bis du sie mit Cache.delete() entfernst oder der Browser den Speicher räumt. Cache-Control-Header werden ignoriert. Plane deshalb eine Versionierung, z. B. über den Cache-Namen.
Kompatibilität: Die Methode ist in allen modernen Browsern verfügbar, im Fenster wie im Worker, aber nur in sicheren Kontexten (HTTPS oder localhost). Im privaten Modus kann der Speicherplatz stark begrenzt sein.

Siehe auch

Cache Cache.add() Cache.match() Cache.delete() Response.clone()