Next.js SSR 입문 (Hydration, Suspense, 코드 스플리팅)
PHP로 몇 년간 웹 개발을 했던 저는 Next.js를 처음 공부할 때 솔직히 방심했습니다. “서버에서 HTML 만들어서 보내는 거잖아, 이미 아는 개념이네”라고 생각했거든요. 그런데 막상 Hydration과 Suspense를 만나고 나서야 제가 얼마나 안이하게 생각했는지 깨달았습니다. PHP의 SSR과 Next.js의 SSR은 겉모습만 비슷할 뿐, 그 안에서 일어나는 일이 꽤 다릅니다.
PHP도 SSR인데, Next.js는 뭐가 다를까
PHP로 게시판이나 쇼핑몰을 개발하던 시절을 떠올려보면, 흐름은 단순했습니다. 브라우저가 요청을 보내면 서버에서 PHP 코드가 실행되고, 데이터베이스 조회 결과를 섞어 HTML을 만든 뒤 브라우저에 전달하는 방식이었습니다. 사용자가 다른 페이지로 이동하면 서버에 새 요청이 가고, 그 과정이 반복됐습니다. AJAX를 얹으면 부분 갱신도 가능했지만, 기본 뼈대는 요청-응답-새 HTML의 연속이었죠.
Next.js도 서버에서 HTML을 생성한다는 점에서는 PHP와 닮아 있습니다. 하지만 결정적인 차이가 있습니다. Next.js는 React 기반이기 때문에, 브라우저에 HTML을 전달한 뒤에도 React가 그 위에서 동작해야 합니다. PHP는 HTML을 보내고 나면 서버의 역할이 사실상 끝나지만, Next.js는 HTML이 브라우저에 도착한 이후에도 할 일이 남아 있습니다. 이 차이를 이해하지 못하면 Hydration이 왜 필요한지 감이 잡히질 않습니다.
SSR(Server-Side Rendering)이란 서버에서 HTML을 미리 생성해 브라우저에 전달하는 렌더링 방식을 말합니다. 초기 화면을 빠르게 표시할 수 있고, 검색 엔진이 콘텐츠를 인식하는 데도 유리하다는 장점이 있습니다. PHP의 렌더링 방식도 넓은 의미에서는 SSR에 해당하지만, React 기반 SSR과는 이후 단계에서 완전히 다른 길을 걷습니다.
두 방식의 핵심 차이를 정리하면 다음과 같습니다.
- PHP SSR: 서버에서 HTML 생성 → 브라우저에 전달 → 완료. 이후 상호작용은 별도 JavaScript로 처리
- Next.js SSR: 서버에서 HTML 생성 → 브라우저에 전달 → React가 해당 HTML과 연결(Hydration) → 이벤트와 상태 관리 활성화
- PHP는 페이지 이동 시 서버에 새 요청, Next.js는 클라이언트 사이드 라우팅으로 페이지 전환 가능
- Next.js는 서버 컴포넌트와 클라이언트 컴포넌트를 구분해 렌더링 전략을 세밀하게 조정 가능
Hydration, 단순한 연결이 아닙니다
처음 Hydration이라는 단어를 접했을 때, “아, SSR로 만든 HTML에 JavaScript 기능을 붙이는 거구나” 정도로만 이해했습니다. 틀린 말은 아니지만, 이 설명만으로는 실제로 문제가 생겼을 때 원인을 찾기가 어렵습니다. 제가 직접 겪어보니 Hydration에서 가장 중요한 포인트는 따로 있었습니다.
Hydration(하이드레이션)이란 서버에서 생성된 HTML에 클라이언트의 React가 연결되어 이벤트 처리, 상태 관리 등 동적 기능이 활성화되는 과정을 뜻합니다. 이 과정이 완료되기 전까지 버튼을 클릭해도 반응이 없는 상태가 발생할 수 있는데, 이를 가리켜 TTI(Time to Interactive), 즉 사용자가 실제로 페이지와 상호작용할 수 있는 시점이 늦어지는 문제라고 표현합니다.
그런데 Hydration에서 더 까다로운 문제는 Hydration Mismatch(하이드레이션 불일치)입니다. 서버에서 생성한 HTML과 브라우저에서 React가 처음 렌더링한 결과가 다를 때 발생하는 오류입니다. 예를 들어 서버에서 현재 날짜를 기준으로 HTML을 만들었는데, 클라이언트에서 렌더링할 때 시간이 조금 달라졌다면 두 결과가 어긋납니다. 이 오류는 콘솔에서 경고로 확인할 수 있는데, 처음 마주쳤을 때 원인을 찾는 데 꽤 시간을 썼습니다. React 공식 문서의 hydrateRoot 설명을 읽고 나서야 서버와 클라이언트의 초기 렌더링 결과가 반드시 일치해야 한다는 원칙이 명확하게 이해됐습니다.
PHP 시절에는 이런 고민을 할 필요가 없었습니다. 서버가 HTML을 보내면 그게 전부였으니까요. 그런데 Next.js에서는 서버에서 무엇을 만들었는지만큼이나, 클라이언트에서 React가 그것을 어떻게 받아서 이어가는지도 중요합니다. 이 사실을 이해하고 나니 SSR을 단순히 “서버에서 HTML 만들기”로 정의했던 제 첫 인상이 얼마나 단순한 것이었는지 실감했습니다.
Suspense는 로딩 스피너가 아닙니다
Suspense를 처음 봤을 때 솔직히 이런 생각이 들었습니다. “그냥 로딩 중 화면 보여주는 거 아닌가?” 그런데 실제로 Next.js 프로젝트에서 useSearchParams를 사용하다가 빌드 오류를 만나고 나서야, Suspense가 그보다 훨씬 중요한 역할을 한다는 걸 체감했습니다.
Suspense(서스펜스)란 React에서 특정 컴포넌트가 렌더링 준비가 되지 않은 상태일 때, 해당 영역 대신 대체 UI를 보여주는 렌더링 경계(Rendering Boundary)를 설정하는 기능입니다. 단순히 로딩 화면을 표시하는 것을 넘어, 서버에서 데이터를 기다리는 동안 페이지의 준비된 부분부터 먼저 전달하는 스트리밍 렌더링(Streaming Rendering)에도 활용됩니다. 스트리밍 렌더링이란 페이지 전체가 완성될 때까지 기다리지 않고, 준비된 조각부터 순차적으로 브라우저에 전송하는 방식을 말합니다.
제가 겪었던 useSearchParams 빌드 오류 사례가 이 개념을 이해하는 데 도움이 됐습니다. URL의 쿼리스트링(Query String), 즉 주소 뒤에 붙는 ?key=value 형태의 파라미터를 읽기 위해 useSearchParams 훅을 사용했는데, 정적으로 사전 렌더링되는 경로에서 이 훅을 쓰면 Next.js가 빌드 시 오류를 냅니다. 해결 방법은 해당 컴포넌트를 Suspense로 감싸서 클라이언트 렌더링이 필요한 영역을 명시적으로 분리하는 것이었습니다. Suspense가 없었다면 정적 렌더링과 동적 렌더링이 충돌하는 상황을 컴포넌트 단위로 정리할 방법이 없었을 겁니다.
또 한 가지 주의할 점이 있습니다. 이미 화면에 표시된 콘텐츠가 Suspense의 fallback, 즉 로딩 표시로 다시 교체되면 사용자 입장에서는 혼란스럽습니다. React 공식 문서의 startTransition을 살펴보면, 이런 상황을 방지하기 위해 상태 전환을 트랜지션(Transition)으로 처리하는 방법을 설명하고 있습니다. 트랜지션이란 긴급하지 않은 UI 업데이트를 별도로 표시해, React가 우선순위를 조정하며 렌더링할 수 있게 하는 개념입니다. Suspense를 제대로 활용하려면 이 부분까지 함께 이해하는 것이 좋습니다.
코드 스플리팅, 무조건 쓰는 게 정답은 아닙니다
Next.js를 공부하면서 코드 스플리팅(Code Splitting)이라는 개념도 함께 만났습니다. 코드 스플리팅이란 JavaScript 번들 파일을 여러 조각으로 나눠 필요한 시점에만 불러오는 기법으로, 초기 로딩 속도를 줄이는 데 효과적입니다. React에서는 React.lazy와 Suspense를 조합해 컴포넌트 단위로 이를 구현할 수 있고, Next.js에서는 next/dynamic이라는 전용 기능을 제공합니다.
next/dynamic은 React.lazy와 유사하지만, Next.js 환경에 맞게 최적화된 동적 임포트(Dynamic Import) 기능입니다. 동적 임포트란 컴포넌트를 처음부터 불러오지 않고 실제로 필요한 시점에 비동기로 가져오는 방식을 말합니다. ssr: false 옵션을 지정하면 서버 렌더링 없이 클라이언트에서만 해당 컴포넌트를 불러올 수도 있는데, 이 옵션은 클라이언트 컴포넌트에서만 사용 가능하다는 점을 주의해야 합니다. 처음에 서버 컴포넌트에서 사용하려다 오류를 만났는데, 이 제약 조건을 미리 알았다면 시간을 아꼈을 겁니다.
그런데 제가 공부하면서 느낀 점은, 코드 스플리팅을 모든 컴포넌트에 적용하는 것이 항상 좋은 선택은 아니라는 겁니다. Next.js는 페이지 단위의 자동 코드 스플리팅을 기본으로 제공합니다. 즉, 특별히 설정하지 않아도 각 페이지의 코드가 별도 번들로 분리됩니다. 여기에 컴포넌트마다 동적 임포트를 남발하면 오히려 네트워크 요청이 늘어나 역효과가 날 수 있습니다.
@loadable/component 같은 별도 라이브러리도 존재하지만, Next.js 프로젝트에서 특별한 이유 없이 도입할 필요는 없다고 봅니다. next/dynamic과 React.lazy, 그리고 Suspense의 역할 차이를 먼저 이해하고, 실제로 무거운 컴포넌트가 어디에 있는지 파악한 다음에 적용 여부를 결정하는 것이 제 경험상 더 합리적인 순서였습니다.
자주 묻는 질문
Q. PHP 개발자가 Next.js로 전환할 때 가장 먼저 이해해야 할 개념은 무엇인가요?
A. Hydration을 가장 먼저 이해하는 것이 좋습니다. PHP는 서버에서 HTML을 생성하고 나면 역할이 끝나지만, Next.js는 그 이후 클라이언트에서 React가 HTML과 연결되는 과정이 추가됩니다. 이 차이를 모르면 서버 컴포넌트와 클라이언트 컴포넌트를 왜 구분하는지, Hydration Mismatch 오류가 왜 발생하는지 이해하기 어렵습니다.
Q. Next.js에서 useSearchParams를 사용할 때 왜 Suspense가 필요한가요?
A. useSearchParams는 클라이언트에서 URL 쿼리스트링을 읽는 훅입니다. 정적으로 사전 렌더링되는 경로에서 이 훅을 사용하면 Next.js 빌드 시 오류가 발생할 수 있습니다. Suspense로 감싸면 클라이언트 렌더링이 필요한 영역을 명시적으로 분리할 수 있어, 정적 렌더링과 동적 렌더링이 충돌하는 문제를 해결할 수 있습니다. 단, 동적 렌더링 경로에서는 Suspense 없이도 사용 가능한 경우가 있습니다.
Q. next/dynamic과 React.lazy의 차이는 무엇인가요?
A. 둘 다 컴포넌트를 필요한 시점에 불러오는 동적 임포트를 구현하지만, next/dynamic은 Next.js 환경에 맞게 설계되어 loading 옵션으로 로딩 UI를 직접 지정하거나, ssr: false로 서버 렌더링을 비활성화하는 기능을 추가로 제공합니다. 일반 React 프로젝트에서는 React.lazy와 Suspense 조합이 표준이지만, Next.js에서는 next/dynamic을 우선적으로 검토하는 것이 편리합니다.
Q. Suspense의 fallback이 반복적으로 나타나면 어떻게 해결하나요?
A. 이미 표시된 콘텐츠가 다시 로딩 화면으로 교체되는 현상은 사용자 경험을 저해합니다. React의 startTransition 또는 useTransition 훅을 활용하면 상태 변경을 트랜지션으로 처리해 예상치 못한 fallback 노출을 줄일 수 있습니다. 상태 전환이 긴급하지 않다고 React에 알려주는 방식으로, 기존 콘텐츠를 유지하면서 새 UI가 준비될 때까지 기다리게 됩니다.
Q. 코드 스플리팅을 모든 컴포넌트에 적용해야 하나요?
A. 그렇지 않습니다. Next.js는 페이지 단위의 자동 코드 스플리팅을 기본으로 제공하기 때문에, 별도 설정 없이도 각 페이지 코드가 분리됩니다. 동적 임포트는 실제로 번들 크기가 크거나 초기 로딩에 불필요한 컴포넌트에 한해 선택적으로 적용하는 것이 좋습니다. 무분별하게 적용하면 네트워크 요청이 증가해 오히려 성능이 나빠질 수 있습니다.
PHP에서 Next.js로 넘어오면서 저는 “이미 아는 개념”이라는 선입견이 오히려 공부를 늦췄다고 생각합니다. SSR이라는 단어 하나가 같아도, PHP와 Next.js 안에서 일어나는 일은 다릅니다. Hydration, Suspense, 코드 스플리팅 모두 왜 필요한지 이해하고 나면 Next.js의 구조가 훨씬 자연스럽게 읽힙니다. 지금 Next.js를 시작하는 분이라면, 기능을 먼저 외우기보다 렌더링 흐름 전체를 한 번 천천히 따라가 보는 것을 권합니다.
—
참고: https://ko.legacy.reactjs.org/docs/react-api.html#reactsuspense
https://react.dev/reference/react-dom/client/hydrateRoot
https://react.dev/reference/react/startTransition