| ReferenceError: localStorage is not defined in Next.js: Causes and How to Fix

ReferenceError: localStorage is not defined in Next.js: Causes and How to Fix

February 10, 2025

Solve the "ReferenceError: localStorage is not defined" in Next.js with this guide. Discover common causes and effective fixes to streamline your development process.

What is ReferenceError: localStorage is not defined in Next.js

Understanding ReferenceError: localStorage is not defined

The ReferenceError: localStorage is not defined error typically occurs in Next.js when attempting to use the localStorage API on the server-side. In a Next.js application, there is a clear distinction between server-side and client-side code execution.

Next.js, being a React framework, allows rendering of components on both the server and in the browser. The localStorage is a part of the Web Storage API that is only accessible in the browser environment since it relies on the browser's window object.

When you try to use localStorage in a component during server-side rendering, it can throw this error because the server-side environment doesn’t have access to browser-specific APIs like localStorage.

Key Points About localStorage

Client-Side Only: localStorage is available solely in the client-side context, relying on the window object to function.

Scope of Use: Only attempt to use localStorage within client-side lifecycle methods in React, such as componentDidMount in class components or within useEffect hooks in function components, to ensure it's accessed in the browser.

Practical Context

In a Next.js application, consider a scenario where you might want to store a value in localStorage. This operation must be performed only after the component mounts on the client side, ensuring that you do not encounter issues with server-side rendering.

```javascript

import { useEffect } from 'react';

function MyComponent() {
useEffect(() => {
// This line is safe; it runs only after the component mounts on the client side
localStorage.setItem('myKey', 'myValue');
}, []);

return

Check the console for localStorage operations

;
}

export default MyComponent;

```

The code snippet above demonstrates how to safely use the localStorage API within a functional component in a manner compatible with Next.js, adhering strictly to client-side rendering practices.

Importance of Server and Client Distinction

Recognizing the distinction between where code executes (server vs. client) is critical in avoiding this and similar errors. It enforces the need to carefully control API usage in frameworks like Next.js, which operate in both environments.

Such planning is vital for both the robustness and correctness of web applications, impacting the user experience and functionality when managing state or browser APIs.

What Causes ReferenceError: localStorage is not defined in Next.js

Understanding the ReferenceError: localStorage is not defined in Next.js

Next.js is a server-side rendered application by default: One of the primary causes of encountering the ReferenceError: localStorage is not defined in Next.js is due to its SSR nature. In server-side rendering, the JavaScript code runs on the server, where the localStorage object is unavailable because it is a feature of the browser's Window object. This difference in environment leads to the error.

Accessing localStorage during the initial server-side render: If your Next.js component tries to access localStorage as soon as it is rendered, the operation may happen on the server. Since localStorage is absence on the server side, it causes an error. This typically occurs when you attempt to read or write to localStorage at the top level of your components or during lifecycle events like getInitialProps or getServerSideProps.

Global execution context: In situations where localStorage is accessed globally within a module without a check to determine if the environment is browser-based, you'll likely encounter this error during the server-side execution phase. As module code is executed both on the server and the client, this can consistently trigger problems when localStorage is accessed immediately.

How to Fix ReferenceError: localStorage is not defined in Next.js

Accessing localStorage in Next.js

In Next.js, accessing browser APIs like `localStorage` directly on the server-side will result in a `ReferenceError` because these APIs are not available outside of the browser environment. To fix this, ensure that any code accessing `localStorage` only runs in the browser.

Using useEffect or Component Lifecycle Methods

Use `useEffect` or component lifecycle methods to ensure code accessing `localStorage` runs only on the client-side. With `useEffect`, you can encapsulate the code inside a callback that only runs after the component is mounted.

import { useEffect } from 'react';

function App() {
  useEffect(() => {
    // Code inside this block runs only in the browser
    const storedValue = localStorage.getItem('key');
    console.log(storedValue);
  }, []);

  return <div>Check console</div>;
}

export default App;

Check Window Object for Safe Access

Ensure that the `localStorage` is only accessed after verifying that the `window` object is defined. This approach is useful when dealing with any kind of synchronous code that needs to interact with `localStorage`.

if (typeof window !== 'undefined') {
  // Safe to use browser APIs
  const storedValue = localStorage.getItem('key');
}

Handling Server-side Rendering (SSR)

During server-side rendering, make sure not to execute code that relies on `localStorage`. This can be achieved by conditionally executing code only in the client environment, as shown in previous examples.

Abstract the Storage Logic

Abstract the storage logic into a custom hook or utility function to handle environments in a clean way. By doing this, you can manage all the storage interactions and environment checks in one place.

export const useLocalStorage = (key, initialValue) => {
  const [storedValue, setStoredValue] = useState(() => {
    if (typeof window === 'undefined') {
      return initialValue;
    }

    const item = localStorage.getItem(key);
    return item ? JSON.parse(item) : initialValue;
  });

  const setValue = value => {
    setStoredValue(value);
    if (typeof window !== 'undefined') {
      localStorage.setItem(key, JSON.stringify(value));
    }
  };

  return [storedValue, setValue];
};

By following these strategies, you can effectively manage localStorage interactions in a Next.js project without encountering the ReferenceError: localStorage is not defined.