React & Next.js

Next.js에서 document is not defined 에러 해결하는 방법

0

Next.js와 같은 프레임워크를 사용할 때 서버 사이드 렌더링(SSR) 환경에서 발생하는 `document is not defined` 에러는 많은 개발자들이 직면하는 공통적인 문제입니다. 이 문제를 해결하는 방법을 이해하는 것은 원활한 개발 경험을 유지하고, 애플리케이션의 성능과 안정성을 보장하는 데 매우 중요합니다. 이 기사에서는 `document is not defined` 에러의 원인과 이를 효과적으로 해결하는 방법에 대해 자세히 알아보겠습니다.

document is not defined 에러의 원인

`document is not defined` 에러는 주로 서버 사이드에서 클라이언트 사이드 전용 객체인 `document`를 참조할 때 발생합니다. Next.js는 기본적으로 서버 사이드 렌더링을 지원하기 때문에, 클라이언트 사이드 전용 코드를 서버 사이드에서 실행하려고 할 때 이 에러가 발생할 수 있습니다.

주요 원인

  • 서버 사이드 렌더링 환경: 서버 사이드에서는 `document` 객체가 존재하지 않습니다. 이는 브라우저 전용 객체로, 브라우저 환경에서만 사용할 수 있습니다.
  • 클라이언트 전용 코드 실행: 클라이언트 사이드에서만 실행되어야 하는 코드를 SSR 환경에서 실행하려고 할 때 발생합니다.

에러 해결 방법

다행히도 `document is not defined` 에러는 몇 가지 간단한 방법으로 해결할 수 있습니다. 다음은 대표적인 해결 방법들입니다.

1. useEffect 사용

`useEffect` 훅을 사용하여 클라이언트 사이드에서만 실행되도록 코드를 작성합니다. `useEffect`는 컴포넌트가 마운트된 후에 실행되기 때문에 서버 사이드에서는 실행되지 않습니다.

import { useEffect } from 'react';

const MyComponent = () => {
  useEffect(() => {
    console.log(document.title);
  }, []);

  return <div>My Component</div>;
};

export default MyComponent;

2. 조건부 렌더링

서버 사이드와 클라이언트를 구분하여 조건부 렌더링을 사용합니다. 이를 통해 서버 사이드 렌더링 중에는 `document` 객체에 접근하지 않도록 합니다.

const MyComponent = () => {
  if (typeof window === 'undefined') {
    return null;
  }
  return <div>{document.title}</div>;
};

export default MyComponent;

3. Dynamic Import 사용

Next.js의 `dynamic` 함수를 사용하여 클라이언트 사이드에서만 로드되는 컴포넌트를 동적으로 가져옵니다.

import dynamic from 'next/dynamic';

const MyComponent = dynamic(() => import('../components/MyComponent'), {
  ssr: false,
});

const Page = () => (
  <div>
    <MyComponent />
  </div>
);

export default Page;

4. 클라이언트 사이드 전용 로직

클라이언트 사이드에서만 동작하는 특정 로직을 `useEffect`를 사용하여 클라이언트 전용으로 만듭니다.

import { useEffect, useState } from 'react';

const MyComponent = () => {
  const [someState, setSomeState] = useState(null);

  useEffect(() => {
    if (typeof window !== 'undefined') {
      const someValue = document.getElementById('some-id').textContent;
      setSomeState(someValue);
    }
  }, []);

  return <div>{someState}</div>;
};

export default MyComponent;

안정적인 개발을 위한 Node.js LTS 버전 사용하기

Node.js는 정기적으로 새로운 버전을 출시하며, LTS(Long-Term Support) 버전은 장기간의 안정성과 지원을 보장합니다. 개발 환경에서 LTS 버전을 사용하는 것은 예상치 못한 문제를 줄이는 데 도움이 됩니다. 이는 특히 서버 사이드 렌더링을 사용하는 Next.js 애플리케이션에서 더욱 중요합니다.

결론

Next.js에서 `document is not defined` 에러는 주로 서버 사이드 렌더링 환경에서 클라이언트 전용 코드를 실행하려고 할 때 발생합니다. 이를 해결하기 위해서는 `useEffect` 훅, 조건부 렌더링, 동적 임포트 등을 사용하여 클라이언트 사이드 전용 코드를 분리하는 것이 중요합니다. 또한, Node.js의 LTS 버전을 사용하여 안정성과 호환성을 유지하는 것이 좋습니다. Next.js와 같은 프레임워크를 사용할 때는 항상 최신 문서와 호환성 정보를 확인하여 문제를 예방하는 것이 중요합니다.

이와 같은 방법을 통해 `document is not defined` 에러를 효과적으로 해결하고, 안정적인 애플리케이션을 개발할 수 있습니다.

답글 남기기