제목: next/dynamic로 빌드 오류 해결하기

서론

최근 Next.js 프로젝트에서 빌드 시 발생하던 오류를 next/dynamic를 통해 손쉽게 해결한 경험을 공유하고자 합니다. 기존 코드에서는 SSR 시 실행될 수 없는 로직이 포함되어 있어, 빌드가 실패하거나 예상치 못한 에러가 발생했습니다.

문제 상황

1. 빌드 시점 오류
   • async 로직과 서버/클라이언트 전용 코드가 섞여 빌드 오류가 발생
   • 예: “PageNotFoundError: Cannot find module for page: /_error” 또는 “async/await is not yet supported in Client Components” 같은 메시지
2. SSR vs CSR 충돌
   • 특정 로직은 Client Component 전용이어야 하는데, Next.js가 SSR(서버 사이드 렌더링) 중 해당 코드를 실행하려다 실패

해결 방법: next/dynamic

Next.js의 dynamic 함수를 사용하면, 특정 컴포넌트를 클라이언트에서만 로드하도록 설정할 수 있습니다.

특히 ssr: false 옵션을 주면, 빌드 시점(SSR)에는 해당 컴포넌트가 렌더되지 않아 문제되는 코드를 건너뛸 수 있습니다.

import dynamic from 'next/dynamic';

// 문제 있던 컴포넌트를 동적으로 불러오기
const ProblematicComponent = dynamic(
  () => import('@/components/ProblematicComponent'),
  { ssr: false }
);

export default function MyPage() {
  return (
    <main>
      <h1>Dynamic Import Example</h1>
      <ProblematicComponent />
    </main>
  );
}

• ssr: false: 빌드 단계에서는 이 컴포넌트를 무시하고, 브라우저(클라이언트)에서만 실행
• 빌드 시 발생하던 오류를 피할 수 있고, Client Component 전용 코드를 클라이언트에서만 동작하게 만듦

결과

1. 빌드 오류 사라짐
   • SSR 시 실행되던 코드가 클라이언트로 옮겨져 더 이상 충돌 없음
2. 프로젝트 구조 명확
   • 문제 있던 로직을 명시적으로 “클라이언트 전용”이라 선언하여, SSR과 CSR을 구분
3. 유연한 설계
   • 일부 기능(예: Suspense Query, 브라우저 전용 API)이 필요할 때만 동적 로딩