CookieStore.set() — Methode · JavaScript-Referenz

Signatur

CookieStore.prototype.set(name, value) | CookieStore.prototype.set(options)

Beschreibung

Die Methode set() der CookieStore-Schnittstelle ist der moderne, asynchrone Ersatz für das Schreiben über document.cookie. Statt einen Cookie-String mühsam zusammenzusetzen, übergibt man entweder Name und Wert oder ein strukturiertes Optionsobjekt mit expires, domain, path, sameSite und partitioned.

Der Aufruf gibt ein Promise zurück, das erfüllt wird, sobald das Cookie tatsächlich gesetzt wurde. Schlägt das Setzen fehl, etwa wegen eines ungültigen Namens, einer unpassenden Domain oder weil der Browser Cookies blockiert, wird das Promise mit einem TypeError bzw. SecurityError abgelehnt. Damit lassen sich Fehler zuverlässig erkennen. Bei document.cookie scheitert das Setzen dagegen stillschweigend.

Die API gibt es im Fenster-Kontext über window.cookieStore und in Service Workern über self.cookieStore. So können auch Service Worker Cookies verwalten, die keinen Zugriff auf document haben. Jede Änderung löst im Fenster das Ereignis change am CookieStore aus, im Service Worker (nach Anmeldung) das Ereignis cookiechange.

Über set() gesetzte Cookies sind immer Secure und niemals HttpOnly. Das Flag HttpOnly kann nur der Server per Set-Cookie-Header setzen.

Parameter

Name	Typ	Beschreibung
$name	string	Name des Cookies (Kurzform mit zwei Argumenten).
$value	string	Wert des Cookies (Kurzform). Wird zusammen mit `name` übergeben.
$options	Object	Alternative zur Kurzform: Objekt mit folgenden Feldern: `name` (`string`, Pflicht): Name des Cookies. `value` (`string`, Pflicht): Wert des Cookies. `expires` (`number \| null`): Ablaufzeitpunkt als Zeitstempel in Millisekunden. `null` (Standard) erzeugt ein Sitzungs-Cookie. `domain` (`string \| null`): Domain, für die das Cookie gilt. Standard: `null` (nur aktueller Host). `path` (`string`): Pfad. Standard: `"/"`. `sameSite` (`"strict" \| "lax" \| "none"`): Standard: `"strict"`. `partitioned` (`boolean`): Partitioniertes Cookie (CHIPS). Standard: `false`.

Rückgabewert

Typ

Promise<undefined>

Beschreibung

Ein Promise, das mit undefined erfüllt wird, sobald das Cookie gesetzt ist. Bei ungültigen Angaben wird es mit einem TypeError abgelehnt, bei blockiertem Zugriff mit einem SecurityError.

Beispiele

Einfaches Cookie mit Name und Wert setzen

const speichereTheme = async (theme) => {
  try {
    await cookieStore.set('theme', theme);
    const cookie = await cookieStore.get('theme');
    console.log(`Gespeichert: ${cookie.name}=${cookie.value}`);
  } catch (err) {
    console.error('Cookie konnte nicht gesetzt werden:', err);
  }
};

speichereTheme('dark');

Gespeichert: theme=dark

Cookie mit Ablaufdatum, Pfad und SameSite über options-Objekt

const DREISSIG_TAGE = 30 * 24 * 60 * 60 * 1000;

const merkeSprache = async (sprache) => {
  await cookieStore.set({
    name: 'lang',
    value: sprache,
    expires: Date.now() + DREISSIG_TAGE,
    path: '/',
    sameSite: 'lax'
  });
  const { name, value, expires, sameSite } = await cookieStore.get('lang');
  console.log(name, value, new Date(expires).toISOString(), sameSite);
};

merkeSprache('de');

lang de 2025-… lax

Auf Änderungen reagieren (change-Ereignis)

cookieStore.addEventListener('change', (event) => {
  for (const c of event.changed) {
    console.log(`Geändert: ${c.name}=${c.value}`);
  }
  for (const c of event.deleted) {
    console.log(`Gelöscht: ${c.name}`);
  }
});

await cookieStore.set('warenkorb', '3');

Geändert: warenkorb=3

Cookie im Service Worker setzen

// sw.js
self.addEventListener('fetch', (event) => {
  const url = new URL(event.request.url);
  if (url.pathname === '/login-erfolgreich') {
    event.waitUntil(
      self.cookieStore.set({
        name: 'eingeloggt',
        value: '1',
        sameSite: 'strict'
      })
    );
  }
});

// Wichtig · Fallstricke

Browser-Kompatibilität: Chromium-Browser unterstützen die API seit Version 87. Safari folgt ab 18.4, Firefox ab 140. Vor dem Einsatz eine Merkmalserkennung (if ('cookieStore' in self)) durchführen und bei Bedarf auf document.cookie zurückfallen.
Nur sichere Kontexte: Die API ist nur unter HTTPS verfügbar (oder unter localhost). Gesetzte Cookies sind automatisch Secure.
Kein HttpOnly: Über JavaScript lassen sich keine HttpOnly-Cookies setzen. Sitzungs- und Authentifizierungs-Token sollten deshalb vom Server per Set-Cookie gesetzt werden, damit sie bei einer XSS-Lücke nicht ausgelesen werden können.
expires ist ein Zeitstempel: Erwartet wird eine Zahl in Millisekunden (z. B. Date.now() + …), kein Datumsstring. max-age gibt es nicht.
Löschen: Zum Entfernen besser cookieStore.delete() verwenden. Ein Ablaufdatum in der Vergangenheit funktioniert zwar auch, ist aber umständlicher.
Domain-Regeln: domain muss zum aktuellen Host passen oder eine übergeordnete Domain sein, sonst wird das Promise abgelehnt. Die Kombination aus Name, Domain und Pfad bestimmt, ob ein bestehendes Cookie überschrieben oder ein zweites angelegt wird.
Größenlimits: Name und Wert zusammen dürfen etwa 4096 Byte nicht überschreiten. Zu große Cookies führen zu einem TypeError.
Fehler immer mit try/catch bzw. .catch() abfangen, etwa wenn der Nutzer Cookies blockiert.

Siehe auch

CookieStore CookieStore.get() CookieStore.getAll() CookieStore.delete() Document.cookie CookieChangeEvent