Got it, let's tackle this localStorage issue in Next.js—it’s super common because Next.js uses server-side rendering (SSR), where window and localStorage don’t exist during the server’s render cycle. Let’s break down the fixes with practical examples:

Why This Happens #

When Next.js renders your page on the server (before sending it to the user’s browser), it runs your React code in a Node.js environment. Node.js doesn’t have a window object or localStorage—those are browser-only APIs. If your code tries to access them directly at the component level (outside client-side lifecycle methods), you’ll get that "window is not defined" error.

Solution 1: Use useEffect for Client-Side Only Access #

useEffect runs only after the component has hydrated in the browser—so window is guaranteed to exist here. This is the simplest fix for most cases:

import { useEffect, useState } from 'react';

function UserPreferences() {
  const [theme, setTheme] = useState('light');

  useEffect(() => {
    // Load saved theme from localStorage (client-side only)
    const savedTheme = localStorage.getItem('app-theme');
    if (savedTheme) {
      setTheme(savedTheme);
    }

    // Save theme to localStorage when it changes
    const saveTheme = (newTheme) => {
      localStorage.setItem('app-theme', newTheme);
      setTheme(newTheme);
    };

    // Bind the save function to your UI elements
    const toggleBtn = document.getElementById('theme-toggle');
    const handleToggle = () => saveTheme(theme === 'light' ? 'dark' : 'light');
    toggleBtn.addEventListener('click', handleToggle);

    // Cleanup event listener on unmount
    return () => toggleBtn.removeEventListener('click', handleToggle);
  }, [theme]);

  return (
    <div className={`theme-${theme}`}>
      <button id="theme-toggle">Switch to {theme === 'light' ? 'Dark' : 'Light'} Mode</button>
      <p>Current theme: {theme}</p>
    </div>
  );
}

export default UserPreferences;

Solution 2: Explicitly Check for window Existence #

If you need to access localStorage outside useEffect (like setting an initial state), add a check for typeof window !== 'undefined' to avoid server-side errors:

import { useState } from 'react';

function UserProfile() {
  // Initialize state with localStorage value (or default if server-side)
  const [username, setUsername] = useState(() => {
    if (typeof window !== 'undefined') {
      return localStorage.getItem('username') || 'Guest';
    }
    return 'Guest'; // Fallback for server render
  });

  const handleSaveUsername = (e) => {
    e.preventDefault();
    if (typeof window !== 'undefined') {
      localStorage.setItem('username', username);
      alert('Username saved!');
    }
  };

  return (
    <form onSubmit={handleSaveUsername}>
      <input
        type="text"
        value={username}
        onChange={(e) => setUsername(e.target.value)}
        placeholder="Enter your username"
      />
      <button type="submit">Save Username</button>
      <p>Welcome, {username}!</p>
    </form>
  );
}

export default UserProfile;

Solution 3: Reusable Custom Hook (Best Practice) #

For frequent use, create a custom useLocalStorage hook that handles all the server-side checks and edge cases (like parsing errors) for you:

import { useState } from 'react';

// Custom hook to safely interact with localStorage
function useLocalStorage(key, initialValue) {
  // Get initial value from localStorage (or fallback to initialValue)
  const [storedValue, setStoredValue] = useState(() => {
    if (typeof window === 'undefined') return initialValue;
    
    try {
      const item = localStorage.getItem(key);
      return item ? JSON.parse(item) : initialValue;
    } catch (err) {
      console.error('Failed to load from localStorage:', err);
      return initialValue;
    }
  });

  // Update localStorage and state
  const setValue = (value) => {
    try {
      // Allow value to be a function (like useState)
      const valueToStore = typeof value === 'function' ? value(storedValue) : value;
      setStoredValue(valueToStore);
      
      if (typeof window !== 'undefined') {
        localStorage.setItem(key, JSON.stringify(valueToStore));
      }
    } catch (err) {
      console.error('Failed to save to localStorage:', err);
    }
  };

  return [storedValue, setValue];
}

// Example usage
function ShoppingCart() {
  const [cartItems, setCartItems] = useLocalStorage('cart', []);

  const addToCart = (item) => {
    setCartItems(prevItems => [...prevItems, item]);
  };

  return (
    <div>
      <h2>Shopping Cart ({cartItems.length} items)</h2>
      <button onClick={() => addToCart({ id: 1, name: 'Next.js Guide', price: 29 })}>
        Add Guide to Cart
      </button>
      <ul>
        {cartItems.map(item => (
          <li key={item.id}>{item.name} - ${item.price}</li>
        ))}
      </ul>
    </div>
  );
}

export default ShoppingCart;

Quick Troubleshooting Tip #

If you still get "localStorage is not defined" even after adding checks, double-check where your code is running. Make sure you’re not accessing localStorage in:

• Component top-level code (outside hooks or lifecycle methods)
• Server-only functions like getServerSideProps or getStaticProps

内容的提问来源于stack exchange，提问作者Ali Mohamadi