1. 문제 상황 발생
Quill 에디터 컴포넌트는 Quill 라이브러리를 사용하므로, use client를 선언하여 클라이언트 전용으로 구성하였습니다.
그러나 여전히 document is not defined 오류가 발생하며, 페이지가 정상적으로 렌더링되지 않는 문제가 나타났습니다.
2. 원인 분석
Next.js에서 'use client'를 선언하면 해당 컴포넌트는 클라이언트에서 실행되지만, 컴포넌트 내부의 import 구문은 여전히 서버에서 먼저 실행됩니다.
Quill은 초기 로딩 시점에 내부적으로 window나 document와 같은 브라우저 전용 객체에 접근하는데, 서버 사이드 렌더링(SSR) 환경에는 이러한 객체가 존재하지 않기 때문에 document is not defined와 같은 오류가 발생합니다.
즉, 'use client'만으로는 서버에서의 라이브러리 로딩 자체를 막을 수 없기 때문에, 브라우저 전용 라이브러리인 Quill을 사용할 때는 동적 import와 SSR 비활성화가 필요합니다.
3. 문제 해결
Quill은 브라우저 전용 라이브러리이므로, 서버에서 해당 모듈을 import하지 않도록 해야 합니다. 이를 위해 Next.js의 dynamic import 기능을 사용하고, ssr: false 옵션을 설정하여 서버 사이드 렌더링을 비활성화하면 문제를 해결할 수 있습니다.
import dynamic from 'next/dynamic';
// Quill이 SSR 중 로딩되지 않도록 방지
const RichTextEditor = dynamic(() => import('@/widgets/write/ui/RichTextEditor'), {
ssr: false,
});4. 정리
- Quill은 브라우저 전용 라이브러리이기 때문에, Next.js의 서버 렌더링 환경에서 직접 import하면
document is not defined오류가 발생할 수 있습니다. 'use client'를 선언해도 import 시점은 여전히 서버에서 처리되기 때문에, SSR 오류를 완전히 방지할 수 없습니다.- 이 문제를 해결하기 위해서는
next/dynamic을 사용하여 해당 컴포넌트를 클라이언트에서만 로딩되도록 분리하고,ssr: false옵션을 설정해야 합니다.
📖 출처
프론트엔드 개발자