Next.js런타임

window is not defined — Next.js 서버 렌더에서 브라우저 객체 접근

ReferenceError: window is not defined

한 줄 해결: 서버(Node.js)에는 window·document 가 없는데 렌더·모듈 최상단에서 접근해 발생하며, 브라우저 전용 코드를 useEffect나 ssr:false 안으로 옮기면 됩니다.

이런 증상일 때

next build 또는 SSR 중 "window is not defined"(또는 document/localStorage/navigator)로 빌드가 실패하거나 서버 렌더가 깨집니다. 클라이언트에서는 잘 되던 코드가 서버 렌더 단계에서 터집니다.

useEffect 안으로 이동

window 접근은 마운트 이후에만 일어나도록 useEffect 로 감쌉니다. useEffect 는 클라이언트에서만 실행됩니다.

useEffect(() => {
  const w = window.innerWidth
}, [])

typeof 가드

모듈 최상단이라면 typeof window 로 환경을 확인한 뒤 접근합니다.

if (typeof window !== 'undefined') { /* 브라우저 전용 */ }

ssr:false 동적 import

window 의존 라이브러리/컴포넌트는 SSR 을 꺼서 클라이언트에서만 로드합니다.

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

💡 예방: 브라우저 전용 라이브러리는 컴포넌트 레벨에서 동적 import 하거나 use client 경계 안에서만 쓰세요.

Next.jswindowSSRdocumentReferenceError