800バイト以下でCookie操作を終わらせるJS-Cookie

はじめに

document.cookie に直接文字列を書き込んでCookieを扱った経験はありませんか。値のエンコード、expiresやpathの書式、複数の属性をセミコロンで連結する記法……仕様を毎回思い出しながら書くのは地味に骨が折れますし、エンコード漏れによるバグも起きがちです。

JS-Cookieは、そんなブラウザCookie操作を素直なAPIに置き換えてくれるライブラリです。Cookies.set()とCookies.get()だけで、値の作成・読み取り・削除がひと目で分かる形になります。依存ライブラリなし、gzip圧縮後800バイト以下という軽さも魅力です。

とはいえ、読むより触った方が早いと思います。実際にCookieを設定・取得・削除できるフォームを用意したので、先に挙動を見たい方はこちらからどうぞ。

＞＞＞まずはサンプルを確認＜＜＜

JS-Cookieとは

JS-Cookieは、クライアントサイドでCookieを扱うためのシンプルなJavaScript APIです。RFC 6265に準拠しており、ブラウザ間の挙動差を吸収しながら、直感的なメソッドでCookieの読み書きができます。

主な特徴

軽量 - gzip圧縮後800バイト以下で、依存関係なし
シンプルなAPI - set・get・removeの3つを覚えれば基本操作は完結
柔軟な文字対応 - 値のエンコード/デコードを自動で処理し、任意の文字列を受け渡しできる
属性のカスタマイズ - expires・path・domain・secure・sameSiteなどをオブジェクトで指定可能
ESM/AMD/CommonJS対応 - モジュール形式を問わず利用でき、TypeScriptの型定義も揃っている

インストール

npmを使う場合は以下のコマンドでインストールできます。

npm install js-cookie

CDN経由で読み込む場合はjsDelivrなどから直接スクリプトを取得できます。

<script src="https://cdn.jsdelivr.net/npm/js-cookie@3/dist/js.cookie.min.js"></script>

JS-Cookieのサンプルを動かす

下のサンプルでは、Cookies.set(name, value, options)でCookieを保存し、Cookies.get(name)で読み取り、Cookies.remove(name)で削除しています。入力欄にCookie名と値を入れて「保存」を押すと、その場でCookieが作成され、一覧に反映される仕組みです。

要点だけを抜き出すと、次のようなコードになります。

import Cookies from 'js-cookie'

// 保存(7日後に失効、pathはルート)
Cookies.set('username', 'takuma', { expires: 7, path: '/' })

// 読み取り
Cookies.get('username') // => 'takuma'

// 全件取得
Cookies.get() // => { username: 'takuma', ... }

// 削除(set時と同じattributesを指定する必要がある)
Cookies.remove('username', { path: '/' })

実際に動かせるものが下です。名前を空にしたまま保存を試すと、バリデーションで弾かれる挙動も確認できます。

expires: 7の部分を1や30に変えると、有効期限の日数が変わります。またsameSite: 'lax'を'strict'に変更すると、クロスサイト遷移時の送信制御が厳しくなる、という違いも試せます。

基本的な使い方

最もシンプルな形は、値を設定して読み取るだけの使い方です。

import Cookies from 'js-cookie'

// Cookieを作成(オプションなし=セッションCookie)
Cookies.set('name', 'value')

// 読み取り
const name = Cookies.get('name') // => 'value'

// 削除
Cookies.remove('name')

// 存在しないCookieはundefinedが返る
Cookies.get('not-exist') // => undefined

Cookies.get()を引数なしで呼ぶと、そのページから参照できる全Cookieをオブジェクトとしてまとめて取得できます。

実践的なユースケース

有効期限と属性を細かく指定する

同意バナーや「ログイン状態を保持する」チェックボックスのように、Cookieの寿命やスコープを明示的に制御したい場面では、expires・path・secure・sameSiteなどの属性をオブジェクトで渡します。日数指定だけでなくDateオブジェクトも使えます。

expiresに渡すDateを今日の日付から1日後に変えると、次にページを開いたときにはCookieが消えている、という違いを確認できます(このサンドボックス上では即時の失効切れは見えませんが、実ブラウザでは期限どおりに削除されます)。

withAttributesでデフォルト属性を共通化する

アプリ全体で「同じpathとsameSiteを毎回書く」のは冗長です。Cookies.withAttributes()を使うと、指定した属性をデフォルトとして持つ新しいCookiesインスタンスを作れます。以降はそのインスタンスから呼び出すだけで、属性の指定を省略できます。

withAttributesに渡すsameSiteを'strict'から'none'に変えると、クロスサイトでの送信可否が変わります(ただしsameSite: 'none'はsecure: trueとの併用がブラウザ側で必須になる点に注意してください)。

withConverterで値のエンコード方式をカスタマイズする

デフォルトでは値はencodeURIComponent相当でエンコードされますが、JSON化したオブジェクトを保存したい場合など、独自のエンコード/デコード処理を挟みたいことがあります。Cookies.withConverter()を使うと、読み書き時の変換ロジックを差し替えられます。

write関数の中身をJSON.stringify(value).toUpperCase()のように変えると、実際にCookieへ保存される生の値がどう変化するかを確認できます。

まとめ

JS-Cookieは、document.cookieの生の文字列操作を、set・get・removeという3つのメソッドに置き換えてくれるライブラリです。属性指定にはオブジェクトをそのまま渡せるため、有効期限やSameSiteポリシーの設定も直感的に書けます。さらにwithAttributesやwithConverterを使えば、プロジェクトごとの共通ルールをインスタンスとして切り出せるので、Cookie操作のコードが散らからずに済みます。

同意管理やユーザー設定の保存など、Cookieを扱う場面では一度導入を検討してみてください。