Accessing localStorage in React seems simple, but server-side rendering (SSR) frameworks like Next.js can cause cryptic crashes. Learn why this happens and explore three robust solutions, from a quick useEffect fix to building a reusable custom hook.

That Time a Single Line of Code Crashed Our Entire Next.js App

I still remember the PagerDuty alert at 2:17 AM. A red-hot critical failure on our main marketing site. The Vercel logs were screaming: ReferenceError: localStorage is not defined. We were dead in the water. After a frantic 20-minute hunt, we found the culprit: a junior dev had added a seemingly innocent line to a component to check for a user’s theme preference. It worked perfectly on his machine, but it absolutely nuked our production build. We’ve all been there, and if you haven’t, you will be. This isn’t a “junior dev” problem; it’s a fundamental misunderstanding of the modern React ecosystem.

The Root of All Evil: Server vs. Browser

So, what’s the big deal? Why does localStorage.getItem('theme') sometimes work and sometimes cause a five-alarm fire? The answer is Server-Side Rendering (SSR).

Modern frameworks like Next.js, Remix, and Gatsby run your React code in two places:

1. On the Server: During the build or on a server request, your React components are rendered into a static HTML string. This happens in a Node.js environment, which has no concept of a “browser.” There’s no window, no document, and certainly no localStorage.
2. On the Client (Browser): That pre-rendered HTML is sent to the user’s browser. Then, React “hydrates” it, attaching all the event listeners and making the page interactive. At this point, you’re in a real browser, and window.localStorage is available.

The crash happens when your component’s initial render logic tries to access localStorage. The server tries, fails, and the whole process grinds to a halt. The key is to ensure you only access browser-specific APIs when you’re sure you’re running in the browser.

The Fixes: From Band-Aid to Body Armor

I’ve seen this problem “solved” a dozen different ways. Let’s walk through the three main patterns, from the quick fix to the one we actually use on my team.

Solution 1: The Quick & Dirty `useEffect`

This is the fastest way to get your code working and silence the build errors. The principle is simple: the useEffect hook only runs after the component has mounted on the client side. By then, the browser is fully loaded, and localStorage is guaranteed to exist.

import React, { useState, useEffect } from 'react';

function ThemeToggler() {
  // Start with a default state. This is what the server will render.
  const [theme, setTheme] = useState('light');

  // After the component mounts on the client, this effect runs.
  useEffect(() => {
    const savedTheme = localStorage.getItem('user-theme');
    if (savedTheme) {
      setTheme(savedTheme);
    }
  }, []); // The empty dependency array means this runs only once on mount.

  // ... rest of your component logic
  return <div>Current Theme: {theme}</div>;
}

Darian’s Take: This is a perfectly acceptable fix for a one-off situation. It’s explicit and easy to understand. However, if you find yourself writing this same `useEffect` in three different components, you’re repeating yourself. It’s time to level up.

Solution 2: The Permanent Fix – A Custom Hook

This is the pattern we enforce at TechResolve. We abstract the logic from Solution 1 into a reusable, bulletproof custom hook. This keeps our components clean and centralizes the logic for handling `localStorage` interactions.

Here’s what a good useLocalStorage hook looks like:

import { useState, useEffect } from 'react';

function useLocalStorage(key, initialValue) {
  // State to store our value
  // Pass initial state function to useState so logic is only executed once
  const [storedValue, setStoredValue] = useState(() => {
    // This part still runs on the server, so we need to guard it
    if (typeof window === 'undefined') {
      return initialValue;
    }
    try {
      const item = window.localStorage.getItem(key);
      return item ? JSON.parse(item) : initialValue;
    } catch (error) {
      console.log(error);
      return initialValue;
    }
  });

  // useEffect to update local storage when the state changes
  useEffect(() => {
    try {
      if (typeof window !== 'undefined') {
        window.localStorage.setItem(key, JSON.stringify(storedValue));
      }
    } catch (error) {
      console.log(error);
    }
  }, [key, storedValue]);

  return [storedValue, setStoredValue];
}

// Now your component is beautifully simple:
function UserProfile() {
    const [name, setName] = useLocalStorage('username', 'Guest');

    return (
        <input 
            type="text" 
            value={name} 
            onChange={(e) => setName(e.target.value)} 
        />
    );
}

This is so much cleaner. Our component doesn’t need to know or care about `useEffect` or the existence of the `window` object. It just uses the hook like it would `useState`.

Solution 3: The ‘Nuclear’ Option – State Management with Persistence

Sometimes, the value you’re storing in `localStorage` isn’t just for one component. It’s global application state—user authentication tokens, site-wide settings, etc. In these cases, wiring up custom hooks everywhere can get messy. This is where you bring in the heavy artillery: a state management library with a persistence middleware.

Libraries like Zustand, Redux Toolkit, or Jotai have plugins that handle this for you. Here’s a conceptual example with Zustand, which is my personal favorite for its simplicity.

import { create } from 'zustand';
import { persist, createJSONStorage } from 'zustand/middleware';

export const useAuthStore = create(
  persist(
    (set) => ({
      token: null,
      user: null,
      setToken: (token) => set({ token }),
      // ...other auth actions
    }),
    {
      name: 'auth-storage', // name of the item in the storage (must be unique)
      storage: createJSONStorage(() => localStorage), // (optional) by default, 'localStorage' is used
    }
  )
);

// In any component:
function Header() {
    const token = useAuthStore((state) => state.token);
    // The library handles all the SSR-safe hydration automatically.
    // It's just there.
    return token ? <p>Logged In</p> : <p>Please Log In</p>;
}

Warning: Don’t reach for this just because you need to store one simple value. This is for managing shared, complex state across your application. Using a global state manager for a simple theme toggler is like using a sledgehammer to hang a picture frame.

Which One Should You Use?

As a senior engineer, my job is often about choosing the right tool for the job. Here’s my cheat sheet:

So, next time you see that dreaded localStorage is not defined error, don’t just panic and slap a `typeof window !== ‘undefined’` check on it. Take a breath, understand why it’s happening, and choose the solution that fits the scale of your problem. Your 2 AM self will thank you for it.

Darian Vance

Lead Cloud Architect & DevOps Strategist

With over 12 years in system architecture and automation, Darian specializes in simplifying complex cloud infrastructures. An advocate for open-source solutions, he founded TechResolve to provide engineers with actionable, battle-tested troubleshooting guides and robust software alternatives.

🤖 Frequently Asked Questions