Skip to main content

How to Resolve the "ReferenceError: localStorage is not defined" Error in JavaScript

The ReferenceError: localStorage is not defined is a common error that occurs when you try to access the localStorage object in a non-browser environment, most frequently in Node.js or during Server-Side Rendering (SSR) in a framework like Next.js.

This error happens because localStorage is a browser-specific API. It is part of the window object, which only exists in a web browser's runtime environment. This guide will explain why this error occurs and show you the correct ways to interact with localStorage in different contexts.

The Core Problem: localStorage is a Browser-Only API​

JavaScript can run in various environments, but the localStorage object is specifically part of the Web Storage API, which is implemented by web browsers to allow websites to store data on a user's computer.

  • In the Browser: localStorage is a property of the global window object and is always available.
  • In Node.js: There is no window object and no concept of browser storage. The runtime environment is a server, so localStorage does not exist.

The problem: when you write code that tries to access localStorage and then run that code in a Node.js environment, the runtime has no idea what localStorage is and throws a ReferenceError.

// my-script.js

// This line assumes the browser's localStorage API exists.
localStorage.setItem('myKey', 'myValue');

// ⛔️ When run with `node my-script.js`, this throws:
// ReferenceError: localStorage is not defined

Solution 1 (Universal Code): Checking for the Browser Environment​

If you are writing code that might run in both a browser and a server environment (e.g., in a Next.js component), you must check if you are in a browser before trying to access localStorage. The most reliable way to do this is to check for the existence of the window object.

Solution:

// This check ensures the code inside only runs in a browser.
if (typeof window !== 'undefined') {
  console.log('You are on the browser, so you can use localStorage!');
  localStorage.setItem('myKey', 'myValue');
} else {
  console.log('You are on the server, so you cannot use localStorage.');
}
note

This is the standard and most robust way to create "isomorphic" or "universal" code that can safely run in any environment without crashing.

Solution 2 (React/Next.js): Using the useEffect Hook​

In frameworks like React and Next.js, components often render on the server first, where localStorage is not available. This is a very common source of the error.

Example fo the problem in React:

// ⛔️ This will crash during Server-Side Rendering (SSR).
// The code runs on the server before the browser has a chance to render.
const initialValue = localStorage.getItem('myValue');

function MyComponent() {
  const [value, setValue] = useState(initialValue);
  // ...
}

Solution: the useEffect hook is guaranteed to run only on the client side, after the component has mounted in the browser. This is the perfect place to safely access browser-only APIs like localStorage.

import { useState, useEffect } from 'react';

function MyComponent() {
  const [value, setValue] = useState('');

  // This code will only run in the browser.
  useEffect(() => {
    const storedValue = localStorage.getItem('myValue');
    if (storedValue) {
      setValue(storedValue);
    }
  }, []); // The empty dependency array ensures this runs only once on mount.

  // Event handlers also run only on the client.
  const handleClick = () => {
    localStorage.setItem('myKey', 'newValue');
  };

  return <button onClick={handleClick}>Save Value</button>;
}
note

By moving all localStorage access into useEffect hooks or into event handlers, you ensure your component can be safely rendered on the server.

Alternatives to localStorage in Node.js​

If your goal is to store persistent data in a Node.js application, localStorage is not an option. You should use server-side storage solutions instead, such as:

  • Writing to a file: Use the built-in fs (File System) module to save data to a JSON or text file.
  • A database: Use a database like SQLite, PostgreSQL, or a key-value store like Redis.
  • In-memory stores: For simple, non-persistent storage, you can use a global variable or a Map.

Conclusion​

The ReferenceError: localStorage is not defined error is a clear indicator that your code is attempting to access a browser-only API in a server-side environment.

  • The root cause is that localStorage is a property of the window object and does not exist in Node.js.
  • For universal code, the best solution is to check for the browser environment with typeof window !== 'undefined'.
  • In React/Next.js, the standard and correct solution is to move any localStorage access into a useEffect hook or an event handler, as these are guaranteed to run only on the client.

Table of Contents