document.cookieより優秀？Cookieを簡単・安全に扱えるCookie Store APIの使い方

2025年6月、WebでCookieを簡単かつ型安全に扱えるCookie Store APIのCookieStoreインターフェースのBaselineステータスが、「Newly available」（最新のすべての主要ブラウザーで利用可能）に到達しました。

この記事では、Cookie Store APIのメリットから使い方まで解説します。

なお、Newly availableに到達したのは、Cookieの基本的な操作に必要なCookieStoreインターフェースのみであり、記事執筆時点でCookie Store API全体のBaselineステータスは「Limited availability」（一部の主要ブラウザーで利用不可）となっていることに注意してください。

既存のdocument.cookieの問題点

これまで、WebでCookieを読み書きする際には、Documentのcookieプロパティ（document.cookie）を使用していました。

たとえば、次のようにしてCookieを読み書きできます。

1
// すべてのCookieを読み取る
2
const cookies = document.cookie;
3

4
// 新しいCookieを追加する
5
document.cookie = newCookie;

document.cookieは、実際のCookieの値に直接アクセスするプロパティではなく、Cookieの値を間接的に読み取り・書き込みするゲッターとセッターです。

つまり、document.cookie = newCookie;はcookieプロパティにnewCookieを直接代入しているのではなく、セッターを介して値を操作しているということです。

これにより、document.cookieがnewCookieで上書きされるのではなく、既存のCookieに追加されるのです。

さて、従来のこの手法にはいくつかの問題点がありました。

第一に、document.cookieは同期的なため、Cookieの更新が完了するまで、シングルスレッドにおいてループをブロックしてしまいます。

これは、とくに大規模なアプリケーションでパフォーマンスを悪化させる可能性があります。

第二に、documentに依存しているため、サービスワーカーのようにdocumentにアクセスできない環境では利用できません。

第三に、より深刻な問題として、Cookieを設定する際に単一の文字列でキー、値、オプションを指定するため、構造化されておらずスペルミスなどの懸念があります。

現在ではJavaScriptを直接書くのではなく、TypeScriptを使うことが増えていますが、たとえばオプション名のスペルを間違えていても、TypeScriptはエラーを出しません。

Cookie Store APIのメリットと使い方

そこで登場するのが、これらの問題を解決したCookie Store APIです。

Cookie Store APIは非同期で動作し、サービスワーカーでも利用できます。

また、オプションは構造化されており、これまでよりも型安全にCookieを扱えます。

では、Cookie Store APIはどのように使うのでしょうか。

まずは、オプションが構造化されていることがわかりやすい、Cookieの作成時の例を示します。

1
await cookieStore
2
    .set({
3
        name: "nameOfCookie",
4
        value: "cookieValue",
5
        expires: Date.now() + (24 * 60 * 60 * 1000),
6
        domain: "example.com",
7
    });
8

9
console.log("Cookie has been created.");

この例ではTop-level awaitを使用しているため、Top-level awaitを使えない環境では非同期関数でラップするか、awaitを削除して.then()を使用する必要があることに注意してください。

単一の文字列でCookieを追加する従来の方法と異なり、引数のオブジェクトのプロパティによって、Cookieの値やオプションを指定していることがわかります。

これにより、たとえばTypeScriptを使っている場合にオプションの名前を間違えると型エラーが出るため、ミスに気づけます。

Cookie Store APIでは、次のようなコードで既存のCookieを取得・削除できます。

1
// 既存のCookieを取得
2
const cookie = await cookieStore.get("nameOfCookie");
3

4
// 既存のCookieを削除
5
await cookieStore.delete("nameOfCookie");

ちなみに、document.cookieで設定したCookieをCookie Store APIから扱ったり、逆にCookie Store APIで設定したCookieをdocument.cookieから扱ったりもできます。

また、changeイベントにより、Cookieの変更を検出できます。

1
cookieStore.addEventListener("change", () => {
2
  console.log("Cookies have been changed.");
3
});

Cookie Store APIのデメリットと注意点

前述のように、Cookie Store APIによるCookieの操作は非同期で実行されます。

そのため、（基本的に非同期で困ることはないと思いますが）何らかの理由で同期的に処理する必要がある場合にはデメリットになります。

また、安全なコンテキストでのみ使用できることにも注意が必要です。

安全なコンテキストは簡単に言うと、HTTPSを利用しているかローカルホストのWebページのことです。

Webページがiframeとして読み込まれている場合には、その祖先まで含めてHTTPSを利用している必要があります。

とはいえ、現在はほとんどのWebサイトがHTTPSに対応しているので、この点についてもあまり困ることはないでしょう。

記事執筆時点でもっとも注意が必要なのは、すべてのブラウザーがCookie Store APIをサポートしているわけではないということです。

主要なブラウザーの最新のバージョンでは、Cookie Store APIによるCookieの追加・変更・削除などの基本的な操作に対応していますが、Webサイトでどれくらい古いバージョンまでサポートするかの方針や、使いたい機能によっては問題が生じる可能性があります。

参考リンク

• Document: cookie プロパティ - Web API | MDN
• Cookie Store API - Web API | MDN
• Cookie Store API