feat: add useLocalStorage hook with SSR support (#2615)

devmgn · claude · web-flow · commit 296e9f6928ce · 2026-03-15T20:23:01.000+09:00
Add a useSyncExternalStore-based useLocalStorage hook with:
- Module-scope cache for reduced localStorage access
- Key-scoped listeners for same-tab synchronization
- Cross-tab sync via StorageEvent
- SSR safety via getServerSnapshot
- Error handling for QuotaExceededError and corrupted JSON

Also remove outdated type-fest reference from AGENTS.md.

Co-authored-by: Claude Opus 4.6 (1M context) &lt;noreply@anthropic.com&gt;
diff --git a/AGENTS.md b/AGENTS.md
@@ -8,7 +8,7 @@ This file provides guidance to AI coding agents when working with code in this r
 
 - **Next.js 16** with App Router, React 19, Turbopack, React Compiler (see `next.config.ts`)
   - Node.js 24, pnpm 10 (exact versions in package.json)
-- **TypeScript** with strict type checking (type-fest for advanced utilities)
+- **TypeScript** with strict type checking
 - **Tailwind CSS v4** with @tailwindcss/postcss
 - **TanStack Query** with queryOptions helper
 - **React Hook Form + Zod v4** with @hookform/resolvers
diff --git a/src/app/(sandbox)/dummy/page.tsx b/src/app/(sandbox)/dummy/page.tsx
@@ -9,6 +9,7 @@ import { SvgIcon } from "../../../components/SvgIcon";
 import { useDebouncedCallback } from "../../../hooks/useDebouncedCallback";
 import { useDisclosure } from "../../../hooks/useDisclosure";
 import { useIsComposing } from "../../../hooks/useIsComposing";
+import { useLocalStorage } from "../../../hooks/useLocalStorage";
 import { useMediaQuery } from "../../../hooks/useMediaQuery";
 import { asyncDebounce } from "../../../utils/asyncDebounce";
 import { createCustomEvent } from "../../../utils/createCustomEvent";
@@ -22,6 +23,7 @@ export default function Page() {
     // noop
   }, 1000);
   useIsComposing();
+  useLocalStorage("dummy", "");
   useMediaQuery("(min-width: 768px)");
   asyncDebounce(() => {
     // noop
diff --git a/src/hooks/useLocalStorage/index.ts b/src/hooks/useLocalStorage/index.ts
@@ -0,0 +1 @@
+export { useLocalStorage } from "./useLocalStorage";
diff --git a/src/hooks/useLocalStorage/useLocalStorage.stories.tsx b/src/hooks/useLocalStorage/useLocalStorage.stories.tsx
@@ -0,0 +1,70 @@
+import type { Meta, StoryObj } from "@storybook/nextjs-vite";
+import { useId, useRef } from "react";
+import { expect, userEvent } from "storybook/test";
+import { useLocalStorage } from "./useLocalStorage";
+import { Button } from "../../components/Button";
+import { Input } from "../../components/Input";
+
+function UseLocalStorageDemo() {
+  const [value, setValue, removeValue] = useLocalStorage(
+    "storybook-demo",
+    "initial",
+  );
+  const inputRef = useRef<HTMLInputElement>(null);
+  const valueId = useId();
+  const inputId = useId();
+
+  return (
+    <div className="flex flex-col gap-4">
+      <div className="flex gap-2">
+        <label htmlFor={valueId}>Current Value: </label>
+        <Input id={valueId} readOnly value={value} />
+      </div>
+      <div className="flex gap-2">
+        <label htmlFor={inputId}>New Value: </label>
+        <Input ref={inputRef} id={inputId} defaultValue="hello" />
+      </div>
+      <div className="flex gap-2">
+        <Button
+          onClick={() => {
+            if (inputRef.current) {
+              setValue(inputRef.current.value);
+            }
+          }}
+        >
+          Save
+        </Button>
+        <Button onClick={removeValue}>Remove</Button>
+      </div>
+    </div>
+  );
+}
+
+const meta = {
+  parameters: {
+    layout: "centered",
+  },
+  render: () => <UseLocalStorageDemo />,
+} satisfies Meta;
+
+export default meta;
+type Story = StoryObj;
+
+export const Default: Story = {};
+
+export const InteractionTest: Story = {
+  play: async ({ canvas }) => {
+    const [currentValue, newValueInput] = canvas.getAllByRole("textbox");
+    await expect(currentValue).toHaveValue("initial");
+
+    await userEvent.clear(newValueInput);
+    await userEvent.type(newValueInput, "saved-value");
+
+    const [saveButton, removeButton] = canvas.getAllByRole("button");
+    await userEvent.click(saveButton);
+    await expect(currentValue).toHaveValue("saved-value");
+
+    await userEvent.click(removeButton);
+    await expect(currentValue).toHaveValue("initial");
+  },
+};
diff --git a/src/hooks/useLocalStorage/useLocalStorage.test.ts b/src/hooks/useLocalStorage/useLocalStorage.test.ts
@@ -0,0 +1,284 @@
+import { act, renderHook } from "@testing-library/react";
+import { useLocalStorage } from "./useLocalStorage";
+
+function createMockStorage() {
+  const store = new Map<string, string>();
+  return {
+    getItem: vi.fn((key: string) => store.get(key) ?? null),
+    setItem: vi.fn((key: string, value: string) => {
+      store.set(key, value);
+    }),
+    removeItem: vi.fn((key: string) => {
+      store.delete(key);
+    }),
+  };
+}
+
+function uniqueKey() {
+  return `test-key-${Math.random().toString(36).slice(2)}`;
+}
+
+describe(useLocalStorage, () => {
+  let mockStorage: ReturnType<typeof createMockStorage>;
+
+  beforeEach(() => {
+    mockStorage = createMockStorage();
+    vi.stubGlobal("localStorage", mockStorage);
+  });
+
+  afterEach(() => {
+    vi.restoreAllMocks();
+  });
+
+  describe("基本動作", () => {
+    it("初期値を返すこと", () => {
+      const key = uniqueKey();
+      const { result } = renderHook(() => useLocalStorage(key, "default"));
+      expect(result.current[0]).toBe("default");
+    });
+
+    it("localStorageの既存値を読み取ること", () => {
+      const key = uniqueKey();
+      mockStorage.setItem(key, JSON.stringify("stored"));
+      const { result } = renderHook(() => useLocalStorage(key, "default"));
+      expect(result.current[0]).toBe("stored");
+    });
+
+    it("setValueで値を更新できること", () => {
+      const key = uniqueKey();
+      const { result } = renderHook(() => useLocalStorage(key, "default"));
+
+      act(() => {
+        result.current[1]("updated");
+      });
+
+      expect(result.current[0]).toBe("updated");
+      expect(mockStorage.setItem).toHaveBeenCalledWith(
+        key,
+        JSON.stringify("updated"),
+      );
+    });
+
+    it("関数型更新をサポートすること", () => {
+      const key = uniqueKey();
+      const { result } = renderHook(() => useLocalStorage(key, 0));
+
+      act(() => {
+        result.current[1]((prev) => prev + 1);
+      });
+
+      expect(result.current[0]).toBe(1);
+
+      act(() => {
+        result.current[1]((prev) => prev + 10);
+      });
+
+      expect(result.current[0]).toBe(11);
+    });
+
+    it("removeValueで値を削除して初期値に戻ること", () => {
+      const key = uniqueKey();
+      const { result } = renderHook(() => useLocalStorage(key, "default"));
+
+      act(() => {
+        result.current[1]("stored");
+      });
+      expect(result.current[0]).toBe("stored");
+
+      act(() => {
+        result.current[2]();
+      });
+
+      expect(result.current[0]).toBe("default");
+      expect(mockStorage.removeItem).toHaveBeenCalledWith(key);
+    });
+  });
+
+  describe("シリアライズ", () => {
+    it("オブジェクトを正しく保存・読み取りできること", () => {
+      const key = uniqueKey();
+      const obj = { name: "test", count: 42 };
+      const { result } = renderHook(() =>
+        useLocalStorage(key, { name: "", count: 0 }),
+      );
+
+      act(() => {
+        result.current[1](obj);
+      });
+
+      expect(result.current[0]).toStrictEqual(obj);
+    });
+
+    it("配列を正しく保存・読み取りできること", () => {
+      const key = uniqueKey();
+      const arr = [1, 2, 3];
+      const { result } = renderHook(() => useLocalStorage<number[]>(key, []));
+
+      act(() => {
+        result.current[1](arr);
+      });
+
+      expect(result.current[0]).toStrictEqual(arr);
+    });
+
+    it("数値を正しく処理すること", () => {
+      const key = uniqueKey();
+      const { result } = renderHook(() => useLocalStorage(key, 0));
+
+      act(() => {
+        result.current[1](42);
+      });
+
+      expect(result.current[0]).toBe(42);
+    });
+
+    it("nullを正しく処理すること", () => {
+      const key = uniqueKey();
+      const { result } = renderHook(() =>
+        useLocalStorage<string | null>(key, null),
+      );
+
+      expect(result.current[0]).toBeNull();
+
+      act(() => {
+        result.current[1]("value");
+      });
+      expect(result.current[0]).toBe("value");
+
+      act(() => {
+        result.current[1](null);
+      });
+      expect(result.current[0]).toBeNull();
+    });
+  });
+
+  describe("エラーハンドリング", () => {
+    it("localStorage利用不可時に初期値を返すこと", () => {
+      const key = uniqueKey();
+      mockStorage.getItem.mockImplementation(() => {
+        throw new Error("localStorage unavailable");
+      });
+
+      const { result } = renderHook(() => useLocalStorage(key, "fallback"));
+      expect(result.current[0]).toBe("fallback");
+    });
+
+    it("破損JSONの場合に初期値を返すこと", () => {
+      const key = uniqueKey();
+      mockStorage.setItem(key, "invalid-json{{{");
+
+      const { result } = renderHook(() => useLocalStorage(key, "fallback"));
+      expect(result.current[0]).toBe("fallback");
+    });
+
+    it("QuotaExceededError時にconsole.warnを出力し状態を変更しないこと", () => {
+      const key = uniqueKey();
+      const warnSpy = vi.spyOn(console, "warn").mockImplementation(() => {});
+      const { result } = renderHook(() => useLocalStorage(key, "default"));
+
+      mockStorage.setItem.mockImplementation(() => {
+        throw new DOMException("quota exceeded", "QuotaExceededError");
+      });
+
+      act(() => {
+        result.current[1]("large-value");
+      });
+
+      expect(warnSpy).toHaveBeenCalledOnce();
+      expect(result.current[0]).toBe("default");
+      // localStorage に書き込まれていないことを確認
+      expect(mockStorage.getItem(key)).toBeNull();
+    });
+  });
+
+  describe("タブ間同期", () => {
+    it("storageイベントで値が更新されること", () => {
+      const key = uniqueKey();
+      const { result } = renderHook(() => useLocalStorage(key, "default"));
+
+      act(() => {
+        window.dispatchEvent(
+          new StorageEvent("storage", {
+            key,
+            newValue: JSON.stringify("from-other-tab"),
+          }),
+        );
+      });
+
+      expect(result.current[0]).toBe("from-other-tab");
+    });
+
+    it("storageイベントで削除を検知すること", () => {
+      const key = uniqueKey();
+      const { result } = renderHook(() => useLocalStorage(key, "default"));
+
+      act(() => {
+        result.current[1]("stored");
+      });
+      expect(result.current[0]).toBe("stored");
+
+      act(() => {
+        mockStorage.removeItem(key);
+        window.dispatchEvent(
+          new StorageEvent("storage", {
+            key,
+            newValue: null,
+          }),
+        );
+      });
+
+      expect(result.current[0]).toBe("default");
+    });
+
+    it("無関係なキーのstorageイベントを無視すること", () => {
+      const key = uniqueKey();
+      const { result } = renderHook(() => useLocalStorage(key, "default"));
+
+      act(() => {
+        window.dispatchEvent(
+          new StorageEvent("storage", {
+            key: "other-key",
+            newValue: JSON.stringify("other-value"),
+          }),
+        );
+      });
+
+      expect(result.current[0]).toBe("default");
+    });
+  });
+
+  describe("同一タブ同期", () => {
+    it("同じキーの複数インスタンスが同期すること", () => {
+      const key = uniqueKey();
+      const { result: result1 } = renderHook(() =>
+        useLocalStorage(key, "default"),
+      );
+      const { result: result2 } = renderHook(() =>
+        useLocalStorage(key, "default"),
+      );
+
+      act(() => {
+        result1.current[1]("synced");
+      });
+
+      expect(result1.current[0]).toBe("synced");
+      expect(result2.current[0]).toBe("synced");
+    });
+  });
+
+  describe("クリーンアップ", () => {
+    it("アンマウント時にリスナーが解除されること", () => {
+      const key = uniqueKey();
+      const addSpy = vi.spyOn(window, "addEventListener");
+      const removeSpy = vi.spyOn(window, "removeEventListener");
+
+      const { unmount } = renderHook(() => useLocalStorage(key, "default"));
+
+      expect(addSpy).toHaveBeenCalledWith("storage", expect.any(Function));
+
+      unmount();
+
+      expect(removeSpy).toHaveBeenCalledWith("storage", expect.any(Function));
+    });
+  });
+});
diff --git a/src/hooks/useLocalStorage/useLocalStorage.ts b/src/hooks/useLocalStorage/useLocalStorage.ts

Original file line number	Diff line number	Diff line change
`@@ -0,0 +1 @@`
	`1`	`+export { useLocalStorage } from "./useLocalStorage";`