📝 [NextJS] BailoutToCSR을 아시나요?

안녕하세요!
이번 글에서는 Next.js에서 BailoutToCSR이 무엇인지, 언제 발생하는지, 그리고 이를 확인하는 방법에 대해 설명드리겠습니다.

Next.js를 사용하다 보면 **"Bail out to client-side rendering"**이라는 메시지를 만나게 될 때가 있는데요,
쉽게 만나진 못합니다. 콘솔에 에러가 표시되거나, 앱이 중단되거나 하는 이슈가 아니기 때문이에요. 
그렇지만 Next.js로 프로젝트를 개발하신다면, 이는 꼭 알아야 하는 영역입니다!

Bailout이 무슨 뜻이고, 왜 발생하는지, 어떻게 해결할 수 있는지 함께 알아보겠습니다. 

 

---

1. Bailout이란?

- Bailout의 뜻

Bailout이라는 단어는 원래 "긴급 탈출" 또는 "구제"라는 의미를 가지고 있습니다.
Next.js에서 Bailout이 발생한다는 것은, "서버 렌더링(SSR)에서 문제가 생겨, 클라이언트 사이드 렌더링(CSR)로 강제 전환되었다"는 것을 의미합니다.

즉, 서버에서 렌더링할 수 없는 코드가 포함되었기 때문에, Next.js가 해당 컴포넌트를 클라이언트에서만 실행하도록 변경한 상황입니다.
이것을 Bailout to Client-Side Rendering(BailoutToCSR)이라고 합니다.

---

2. 언제 BailoutToCSR이 실행될까? 

BailoutToCSR은 서버 컴포넌트에서 클라이언트에서만 사용할 수 있는 요소들을 사용했을 때 발생합니다.
대표적인 경우는 다음과 같습니다.

 

🚨 window, document 같은 브라우저 객체 사용

서버 컴포넌트에서는 window, document, localStorage 등 브라우저 객체를 사용할 수 없습니다.
하지만 이를 서버에서 직접 사용하면 BailoutToCSR이 발생하게 됩니다.

📌 문제 코드 (서버 컴포넌트에서 window 사용)

export default function Page() {
	console.log(window.innerWidth); // 🚨 서버에서 window는 존재하지 않음! 
	return <h1>Window Width: {window.innerWidth}</h1>; 
}

 

✔ Next.js는 window를 서버에서 접근할 수 없으므로 CSR로 강제 전환(Bailout)함.

 

🚨 use client 없이 클라이언트 훅(useState, useEffect 등) 사용

Next.js에서는 서버 컴포넌트에서 useState, useEffect 같은 React 훅을 사용할 수 없습니다.
이러한 클라이언트 전용 기능을 서버에서 사용하면, BailoutToCSR이 발생합니다.

📌 문제 코드 (서버 컴포넌트에서 useState 사용)

export default function Page() {
  const [count, setCount] = useState(0); // 🚨 서버에서는 React 훅 사용 불가

  return (
    <div>
      <p>Count: {count}</p>
      <button onClick={() => setCount(count + 1)}>Increase</button>
    </div>
  );
}

 

🚨 Next.js는 서버에서 useState를 사용할 수 없으므로 CSR로 강제 전환됨.

 

🚨 next/dynamic을 사용할 때 SSR 설정이 잘못된 경우

Next.js에서 next/dynamic()을 사용하면 기본적으로 서버에서 렌더링을 시도합니다.
그런데 해당 컴포넌트가 서버에서 실행될 수 없는 코드(window, document 포함)를 사용하면 CSR로 강제 전환됩니다.

📌 문제 코드 (next/dynamic 사용 시 ssr: false 미설정)

import dynamic from "next/dynamic";

const Modal = dynamic(() => import("../components/Modal")); // 🚨 기본적으로 SSR을 시도함

export default function Page() {
  return <Modal />;
}

 

🚨 서버에서 document.body 등을 참조하면 CSR로 전환됨.

---

3. BailoutToCSR을 확인하는 방법

Bailout이 발생한 컴포넌트를 찾으려면 React DevTools를 활용하면 쉽게 확인할 수 있습니다.

(Components 탭에서 BailoutToCSR로 컴포넌트를 검색)

 

 

reason을 보면 이유도 같이 알 수 있습니다. 위 스크린샷에서는 next/dynamic으로 인한 Bailout이 발생했네요.

 

브라우저의 Network 탭에서도 페이지의 document를 클릭 시 Bailout이 발생한 경우 확인할 수 있습니다.

Bail out to client-side rendering: next/dynamic"
data-stck="Switched to client rendering because the server rendering errored:
Error: Bail out to client-side rendering: next/dynamic

 

 

제 경우에는 dynamic을 사용할 때 ssr: false 옵션을 주었는데도 document에서 위 메시지가 나오긴 하네요. 
해결 방법을 찾아보고 추후에 해결이 되면 추가로 내용을 올리도록 하겠습니다!
다만 프로젝트 동작에는 전혀 문제가 없기 때문에 크리티컬한 이슈는 아니라 판단됩니다 :) 

 

마무리

🚀 요약

• BailoutToCSR이란?
  → 서버에서 렌더링할 수 없는 코드가 포함되었을 때 CSR로 강제 전환되는 현상
• 언제 발생하는가?
  → 서버 컴포넌트에서 브라우저 객체(window, document) 사용, React 훅(useState) 사용 등