localStorage is not defined の直し方 — SSRで落ちる理由と、use client で直らない理由

公開 2026-10-25 ／ 更新 2026-10-25 ／ 文：スブリ

先に結論

localStorage is not defined は、localStorage の使い方の問題ではありません。 ブラウザの外でそのコードが走っているという、場所の問題です。

まず、出ているエラーの文面で原因が分かれます。

直し方は、使う場面で決まります。

なぜサーバーには localStorage が無いのか

素のNodeで確かめる

localStorage はブラウザが提供するものです。 Node.js には、既定では存在しません。手元の Node 24.14.1 で確かめました。

$ node -e "console.log('typeof localStorage =', typeof localStorage)"
typeof localStorage = undefined

$ node -e "localStorage.getItem('x')"
ReferenceError: localStorage is not defined

関連するものも、まとめて存在しません。

だからSSRで落ちます。 サーバーサイドレンダリングは、ページのHTMLをNodeの上で先に作る仕組みです。 そのときコンポーネントの中身はブラウザではなくNodeで実行されます。 そこに localStorage.getItem() があれば、当然落ちます。

同じ理由で、ビルド時・テスト実行時・静的生成時にも落ちます。 「ブラウザでは動くのに、ビルドで落ちる」はこれです。

Nodeにも localStorage はある（条件つき）

ここは意外と知られていません。Node には Web Storage の実装が入っています。 ただし実験的な機能で、フラグが要ります。

Node 24.14.1 の --help にこう出ています。

--experimental-webstorage    experimental Web Storage API
--localstorage-file=...      file used to persist localStorage data

実際に動かすと、こうなりました。

2行目のエラーは、文面まで取りました。

TypeError [ERR_INVALID_ARG_VALUE]: The argument '--localstorage-file'
is an invalid localStorage location. Received ''

localStorage は保存先のファイルが要るのに対して、 sessionStorage はメモリ上なのでファイル指定が要らない、という違いです。 名前のとおりの挙動になっています。

ファイルを指定して動かすと、本当に永続化されました。

$ node --experimental-webstorage --localstorage-file=/tmp/ls.test \
    -e "localStorage.setItem('a','1'); console.log(localStorage.getItem('a'))"
1

$ node --experimental-webstorage --localstorage-file=/tmp/ls.test \
    -e "console.log('別プロセスから', localStorage.getItem('a'))"
別プロセスから 1

別プロセスから読めます。指定したパスに実体のファイルが作られます。 起動時には ExperimentalWarning: Web Storage is an experimental feature and might change at any time が出ます。

use client を付けたのに直らない

公式が書いていること

Next.js の App Router で "use client" を付ければブラウザ専用になる、と思われがちです。 そうではありません。公式ドキュメントの記述はこうです。

クライアントコンポーネントも、サーバーで一度レンダリングされます。 "use client" が意味するのは「ブラウザでしか動かない」ではなく、 「ブラウザでも動く（＝ハイドレーションの対象になる）」です。

だから、コンポーネントの本体やモジュールのトップレベルに localStorage があると、 "use client" があってもサーバー実行時に落ちます。

公式は、ブラウザAPIの扱いについてもこう書いています。

つまり "use client" は必要条件であって、十分条件ではありません。 クライアントコンポーネントにしたうえで、さらに実行のタイミングをずらす必要があります。

ssr: false も、置く場所を間違えると使えない

次によく出てくるのが next/dynamic で ssr: false を指定する方法です。 これも、置く場所を間違えると別のエラーになります。

App Router では、ページやレイアウトは既定で Server Component です。 そこに dynamic(..., { ssr: false }) を書くと通りません。 いったんクライアントコンポーネントを挟んで、その中で書きます。

環境別の切り分け

同じエラーでも、どこで起きているかで触る場所が変わります。 まず「どの工程で落ちたか」を特定してください。

テストで落ちている場合だけは、対処が逆方向です。 コードを直すのではなく、テスト環境にブラウザのふりをさせます（jsdom）。 ここをコード側で直そうとすると、本番に不要な分岐が増えていきます。

直し方は4つ

① マウント後に読む

一番素直で、ほとんどの場合これで足ります。 画面に出す値なら、これを使ってください。

'use client';
import { useState, useEffect } from 'react';

export default function Theme() {
  // サーバーでもクライアントでも、初期値は同じにする
  const [theme, setTheme] = useState('light');

  useEffect(() => {
    // ここはブラウザでしか走らない
    const saved = localStorage.getItem('theme');
    if (saved) setTheme(saved);
  }, []);

  return <p>いまのテーマ: {theme}</p>;
}

Vue / Nuxt なら onMounted です。

<script setup>
import { ref, onMounted } from 'vue';

const theme = ref('light');

onMounted(() => {
  const saved = localStorage.getItem('theme');
  if (saved) theme.value = saved;
});
</script>

② typeof で守る

コンポーネントではなく、共通の関数やユーティリティの中で触っている場合です。 呼び出し元がサーバーかブラウザか分からないので、関数側で守ります。

export function getStored(key) {
  // typeof なら、未定義の変数でも ReferenceError にならない
  if (typeof window === 'undefined') return null;
  try {
    return localStorage.getItem(key);
  } catch {
    // プライベートモード等で落ちることがある
    return null;
  }
}

typeof を使うのが要点です。 if (window === undefined) と書くと、 その比較の時点で ReferenceError になります。 typeof は未定義の変数に対しても安全に "undefined" を返します。

③ サーバーで描かせない

コンポーネント全体がブラウザ専用のときは、サーバーで描くのをやめます。

// Next.js：Client Component の中に書く（Server Component では通らない）
'use client';
import dynamic from 'next/dynamic';

const ComponentC = dynamic(() => import('../components/C'), { ssr: false });

Nuxt には専用のコンポーネントがあります。公式の説明では、既定スロットの中身はサーバーのビルドから除外されます。

<template>
  <div>
    <Sidebar />
    <ClientOnly fallback-tag="span" fallback="Loading comments...">
      <Comment />
    </ClientOnly>
  </div>
</template>

fallback を書けるのが利点です。 サーバー側では代わりの内容を出せるので、ブラウザでマウントされるまでの見た目を自分で決められます。

どれを使うか

③ は効きますが、使いすぎないでください。 ページの大部分を ssr: false にすると、SSRを使っている意味がなくなります。 まず ① で済まないかを考えてください。

本当の落とし穴：hydration mismatch

何が起きるか

useEffect で囲んでエラーが消えた、で終わりにすると次の問題を踏みます。 サーバーが描いたHTMLと、ブラウザが描いた内容が食い違う状態です。

React公式の説明は、かなり強い言い方です。

「イベントハンドラが正しく紐づかない」が怖いところです。 画面は出ているのにボタンが効かない、という症状になります。 エラーは出ていないので、原因に辿りつくのに時間がかかります。

localStorage でこれが起きるのは、こういう書き方をしたときです。

// これは hydration mismatch になる
const [theme] = useState(
  // サーバーでは実行できず、ブラウザでは値が入る
  typeof window !== 'undefined' ? localStorage.getItem('theme') : 'light'
);

エラーは出ません。typeof で守っているので落ちません。 しかしサーバーは 'light' で描き、ブラウザは保存値で描くので、 初回のHTMLと一致しません。

公式が示している直し方

React公式が挙げているのは、状態変数で描き分ける方法です。

'use client';
import { useState, useEffect } from 'react';

export default function Theme() {
  const [theme, setTheme] = useState('light');   // サーバーと同じ初期値
  const [mounted, setMounted] = useState(false);

  useEffect(() => {
    setTheme(localStorage.getItem('theme') ?? 'light');
    setMounted(true);
  }, []);

  // マウント前はサーバーと同じものを返す＝一致する
  if (!mounted) return <p>いまのテーマ: light</p>;

  return <p>いまのテーマ: {theme}</p>;
}

要点は「最初の描画をサーバーと完全に一致させる」ことです。 保存値を使うのは、そのあとです。

suppressHydrationWarning を使っていい場面

Reactには警告を抑える手段もあります。ただし公式は、使いどころを限定しています。

初期値をどう設計するか

ここまでの直し方には共通の弱点があります。 マウントされるまでの一瞬、保存値ではない表示が出ます。 ダークテーマの保存値があるのに、一瞬だけ明るい画面が出る、というやつです。

3行目が答えになることが多いです。 localStorage はサーバーから見えません。 「サーバーが最初のHTMLを描くときに必要な値」を localStorage に置くこと自体が、設計の選択として合っていません。 初期表示に効く値は Cookie、それ以外は localStorage、という分け方が素直です。

AIに任せるときの注意

判定の目安です。答えが "use client" を足すだけで終わっていたら、足りていません。 useEffect か typeof か ssr: false のどれかが入っているかを見てください。

よくある質問

"use client" を付けたのに直りません

クライアントコンポーネントもサーバーでプリレンダリングされます（公式の記述）。 "use client" は必要条件であって十分条件ではありません。 useEffect の中に移すか、typeof で守ってください。

dynamic の ssr: false でエラーが出ます

Server Component の中に書いていませんか。 公式が「ssr: false は Server Components ではサポートされていない」と明記しています（詳しく）。 Client Component の中に移してください。

ブラウザでは動くのにビルドで落ちます

ビルド時にもコンポーネントはNodeで実行されるからです（詳しく）。 開発サーバーで気づかず、本番ビルドで初めて出ることがあります。

テストでだけ落ちます

テスト環境が node のままです。jsdom に変えてください（表5）。 ここをコード側の分岐で直すと、本番に不要な条件が増えます。

エラーは消えたのにボタンが効きません

hydration mismatch です。 React公式が「不一致を無視すると、イベントハンドラが正しく紐づかない問題につながる」と書いています（詳しく）。 最初の描画をサーバーと一致させてください。

suppressHydrationWarning で消してもいいですか

localStorage の値なら、やめたほうがいいです。 一致させられるものだからです（表8）。 公式も「使いすぎるべきではない。通常の不一致検出を無効にしてしまう」としています。

一瞬だけ違う表示が出ます

マウントされるまでは保存値を読めないためです。 テーマや言語のように初期表示に効く値は、Cookieに移すのが本筋です（表9）。 サーバーはリクエストでCookieを読めるので、最初から正しく描けます。

Node で localStorage を使うことはできますか

できます。--experimental-webstorage と --localstorage-file が要ります（表4）。 ただしSSRのエラーを直す手段ではありません。 全アクセスで同じファイルを共有してしまいます。

window === undefined ではだめですか

だめです。その比較の時点で ReferenceError になります（表6）。 typeof window === 'undefined' と書いてください。

まとめ

• localStorage is not defined は使い方の問題ではなく、場所の問題。ブラウザの外で走っている。
• 素のNode 24では localStorage も window も document も sessionStorage もすべて undefined（実測）。
• "use client" では直らない。クライアントコンポーネントもサーバーでプリレンダリングされる（Next.js公式）。
• ssr: false は Server Component では使えない。Client Component の中に移す（Next.js公式）。
• 直し方は、① マウント後に読む ② typeof で守る ③ サーバーで描かせない。まず ① を考える。
• window === undefined と書くとその行で落ちる。必ず typeof。
• エラーが消えても終わりではない。hydration mismatch はイベントハンドラが紐づかない形で出る（React公式）。
• 最初の描画をサーバーと完全に一致させる。suppressHydrationWarning で蓋をしない。
• 初期表示に効く値は Cookie に移す。localStorage はサーバーから見えない。
• Nodeにも Web Storage はあるがフラグ2つが要り、SSRの解決策にはならない。