nextjs - 💡(How to fix) Fix Blog Starter Example: localStorage SSR Hydration Error with Next.js 15/React 19 [3 comments, 3 participants]

When using the official blog-starter example with Next.js 15.0.2 and React 19, the app fails to start due to a server-side rendering (SSR) hydration error in the theme switcher component. The error message is:

TypeError: localStorage.getItem is not a function
    at src/app/_components/theme-switcher.tsx:63:22

Steps to Reproduce:

1. Clone the official Next.js blog-starter example.
2. Install dependencies (with Next.js 15+ and React 19).
3. Run npm run dev.
4. Observe the error in the terminal and browser.

Root Cause: The theme switcher component uses this code to initialize state:

const [mode, setMode] = useState<ColorSchemePreference>(
  () =>
    ((typeof localStorage !== "undefined" &&
      localStorage.getItem(STORAGE_KEY)) ??
      "system") as ColorSchemePreference,
);

This check is insufficient for SSR and newer React/Next.js versions. On the server, localStorage may be undefined or not have the expected methods, causing the error.

Why This Is a Problem:

• New users cloning the example get a broken experience out of the box.
• The issue is exposed by stricter SSR/hydration checks in React 19 and Next.js 15.
• The pattern is not aligned with current Next.js best practices for client-only APIs.

Suggested Fix: I received the following fix from GitHub Copilot (AI assistant), which I tested and confirmed resolves the issue:

const [mode, setMode] = useState<ColorSchemePreference>(
  () => {
    if (
      typeof window !== "undefined" &&
      typeof localStorage !== "undefined" &&
      localStorage.getItem
    ) {
      return (localStorage.getItem(STORAGE_KEY) ?? "system") as ColorSchemePreference;
    }
    return "system";
  }
);

useEffect(() => {
  if (
    typeof window !== "undefined" &&
    typeof localStorage !== "undefined" &&
    localStorage.setItem
  ) {
    localStorage.setItem(STORAGE_KEY, mode);
  }
  updateDOM();
}, [mode]);

Transparency Note: This fix was recommended by GitHub Copilot in my local environment. I am submitting it here for review and consideration by the maintainers.

Impact:

• Fixes SSR hydration error for new users
• Aligns with best practices for accessing browser APIs in Next.js
• No functional changes, only defensive programming

Environment:

• Next.js: 15.0.2
• React: 19.0.0-rc
• Node: v25.1.0
• OS: macOS

Additional Context:

• The same pattern is used in other Next.js examples (e.g., with-supabase) to avoid SSR issues.
• This issue is not present in older Next.js/React versions due to less strict SSR/hydration behavior.