[NextJS] "Error occurred prerendering page" 해결 (useSearchParams, ReactQuill 등)

프로젝트 빌드 중에 write 페이지와 post 페이지에서 발생한 prerendering Error를 해결한 과정을 작성합니다.

Next.js는 서버 사이드와 클라이언트 사이드에서 모두 동작하는 프레임워크입니다. Next.js의 SSR(서버 사이드 렌더링) 구조로 인해, 클라이언트 사이드에서만 사용할 수 있는 기능은 클라이언트에서 렌더링이 완료된 후에 사용해야 합니다.

Post 페이지 - useSearchParams 사용 문제

post 페이지에서는 useSearchParams 훅을 사용 중에 문제가 발생했습니다. 이 훅은 클라이언트 사이드에서 사용해야 하는데, SSR 과정에서 사용되어 에러가 발생한 것입니다. 이를 해결하기 위해 React의 Suspense를 이용했습니다. Suspense는 비동기 작업이 완료될 때까지 서버가 페이지를 계속 렌더링하도록 하여, 사전 렌더링 과정에서 발생할 수 있는 비동기 작업 관련 문제를 해결합니다. 이를 통해 컴포넌트가 완전히 로드되기 전에 사용자에게 불완전한 페이지가 제공되는 것을 방지할 수 있습니다.

import { Suspense } from 'react'
import PostViewer from './PostViewer'

function Posts() {
  return (
    <Suspense fallback={<div>Loading...</div>}>
      <PostViewer />
    </Suspense>
  )
}
export default Posts

Write 페이지 - ReactQuill 사용 문제

write 페이지에서는 ReactQuill 라이브러리 사용 중에 문제가 발생했습니다. ReactQuill과 같은 일부 라이브러리는 브라우저 환경에 의존하기 때문에 서버 사이드 렌더링 시 로드하려고 하면 document is not defined와 같은 오류가 발생할 수 있습니다. 이를 해결하기 위해 동적 로딩을 사용하고, ssr: false 옵션을 설정했습니다. 이렇게 하면 해당 컴포넌트는 클라이언트 사이드에서만 로드됩니다.

const ReactQuill = dynamic(() => import('react-quill'), {
  ssr: false,
})

document, window는 클라이언트 측에서만 정의된 전역 변수입니다. document is not defined 및 window is not defined 에러가 발생한다면, 서버에서 해당 객체를 참조하고 있는 것은 아닌지 확인해봐야 합니다.

결론

Next.js의 서버 사이드 렌더링 환경에서 클라이언트 사이드 전용 기능을 사용할 때는 주의가 필요합니다. Suspense를 사용하여 비동기 작업이 완료될 때까지 렌더링을 지연시키거나, 동적 로딩과 ssr: false 옵션을 사용하여 클라이언트 사이드에서만 컴포넌트를 로드함으로써 이러한 문제를 해결할 수 있습니다.