localStorage

localStorage とは

localStorage は、ブラウザにキーバリュー形式でデータを永続的に保存する Web Storage API である。セッションをまたいでデータが保持され、明示的に削除するまで消えない。容量はオリジンあたり 5 MiB が目安で、localStorage と sessionStorage を合わせた Web Storage 全体の上限が 10 MiB とされる (2026 年 8 月時点)。localStorage 単体で 10 MiB 使えるわけではない点に注意する。この枠を超える書き込みは QuotaExceededError の例外になるため、保存側は失敗を前提に組む。

sessionStorage との比較

sessionStorage との主な違いを以下に比較する。

観点	localStorage	sessionStorage	Cookie
有効期間	永続 (手動削除まで)	タブを閉じるまで	有効期限まで
容量	5 MiB (Web Storage 全体で 10 MiB)	5 MiB (同じ枠を共有)	4 KB
サーバー送信	なし	なし	毎リクエスト送信
API	同期	同期	document.cookie

基本操作

基本操作のコード例を示す。

// 保存
localStorage.setItem('theme', 'dark');

// 取得
const theme = localStorage.getItem('theme'); // 'dark'

// 削除
localStorage.removeItem('theme');

// 全削除
localStorage.clear();

// オブジェクトの保存 (文字列のみなので JSON 変換が必要)
localStorage.setItem('user', JSON.stringify({ name: 'Alice', age: 30 }));
const user = JSON.parse(localStorage.getItem('user')!);

型安全なラッパー

型安全なラッパーのコード例を示す。

function getStorageItem<T>(key: string, fallback: T): T {
  const item = localStorage.getItem(key);
  if (item === null) return fallback;
  try { return JSON.parse(item) as T; }
  catch { return fallback; }
}

function setStorageItem<T>(key: string, value: T): void {
  try {
    localStorage.setItem(key, JSON.stringify(value));
  } catch {
    // 容量超過 (QuotaExceededError) では保存されない。
    // 設定値の保存なら黙って諦めるのではなく、既存の不要キーを整理するか
    // 保存できなかったことを UI に伝える。
    console.warn(`localStorage への保存に失敗: ${key}`);
  }
}

// 使用
const theme = getStorageItem('theme', 'light');
setStorageItem('theme', 'dark');

適するケース / 適さないケース

適するケース / 適さないケースを以下に示す。

適する用途	適さない用途
テーマ設定 (ダーク/ライト)	認証トークン (XSS で盗まれる)
言語設定	パスワード、個人情報
フォームの下書き	大量データ (→ IndexedDB)
UI の状態 (サイドバーの開閉)	サーバーと同期が必要なデータ

セキュリティ上の注意

localStorage は JavaScript から自由にアクセスできるため、XSS 攻撃で全データが盗まれる。

// ❌ 認証トークンを localStorage に保存しない
localStorage.setItem('token', 'eyJhbGciOiJIUzI1NiJ9...');

// ✅ 認証トークンは HttpOnly Cookie で管理
// (JavaScript からアクセスできない)

ストレージイベント

ストレージイベントのコード例を示す。

// 別タブでの変更を検知
window.addEventListener('storage', (event) => {
  if (event.key === 'theme') {
    applyTheme(event.newValue!); // 別タブでテーマが変わったら同期
  }
});

storage イベントは変更を行ったタブ以外のタブで発火する。タブ間のデータ同期に使える。

理論と実装の両面から学ぶなら関連書籍が参考になる。