hydration mismatch

[sgoldenbird]

📌 배운 내용

Next.js의 SSR 환경에서 useWatch()와 같은 클라이언트 전용 훅을 안전하게 사용하는 방법의 중요성을 깨달았습니다.
서버와 클라이언트 간의 상태 불일치(hydration mismatch)를 방지하기 위해 초기값 처리를 신중하게 해야 합니다.

---

🔍 배경 / 문제 상황

Next.js와 같은 SSR(서버 사이드 렌더링) 프레임워크는 서버에서 HTML을 선 렌더링한 뒤, 클라이언트에서 JavaScript가 이를 이어받아 상호작용 기능을 부여하는 hydration 과정을 거칩니다.

하지만 React Hook 중 useWatch()처럼 내부적으로 useEffect를 사용하는 훅은 브라우저 환경에서만 동작합니다.
따라서 다음과 같은 문제가 발생할 수 있습니다.

• 서버 렌더링 시점: useWatch()의 값은 undefined 또는 초기값으로 설정됩니다.
• 클라이언트 하이드레이션 시점: 클라이언트에서 useWatch()가 정상적으로 동작하며, 서버에서 렌더링된 값과 다른 새로운 값으로 상태가 변경됩니다.

이러한 서버와 클라이언트 간의 DOM 또는 상태 불일치는 hydration mismatch를 유발하며, 이는 다음과 같은 문제를 야기합니다.

• ⚠️ 콘솔 경고: Warning: Text content did not match...
• 💥 렌더 불안정성: 일부 컴포넌트가 재렌더링되거나 비정상 동작
• 🧭 UX 저하: 깜빡임, 위치 이동, 입력 초기화 등의 문제

---

✅ 핵심 정리 / 해결 방법

하이드레이션 불일치를 방지하기 위한 주요 해결책은 다음과 같습니다.

1. 초기값 처리 가드 전략

useWatch()의 값이 아직 확정되지 않은 초기 렌더링 단계에서 UI를 조건부로 렌더링하여 불일치 가능성을 원천 차단합니다.

const watchedValue = useWatch({ control, name: 'fieldName' });

if (watchedValue === undefined) {
  // SSR 단계에서는 값이 없으므로 null을 반환하여 불필요한 DOM 생성을 방지합니다.
 // 클라이언트에서 값이 채워진 후에만 UI를 렌더링합니다.
  return null;
}

return <div>{watchedValue}</div>;

2. useEffect 기반 안전 렌더링

useState와 useEffect를 조합하여 클라이언트에서만 상태를 업데이트하고 렌더링을 시작하도록 설계합니다.

const watchedValue = useWatch({ control, name: 'fieldName' });
const [value, setValue] = useState<string>();

useEffect(() => {
// 클라이언트에서 컴포넌트가 마운트된 후에만 상태를 업데이트합니다.
  setValue(watchedValue);
}, [watchedValue]);

return value ? <div>{value}</div> : null;

3. 클라이언트 전용 컴포넌트 분리

"use client" 지시어를 사용하여 컴포넌트 전체를 클라이언트 전용으로 만들고, 이 컴포넌트가 서버에서 렌더링되지 않도록 합니다.

---

🧠 느낀점 또는 생각 메모

SSR 환경에서는 모든 React 훅이 동일하게 동작하지 않음을 체감했습니다.
특히 상태 기반으로 UI를 출력할 때는 SSR과 클라이언트 간의 렌더링 차이를 항상 염두에 두고 설계해야 합니다.
useWatch, useFormContext와 같은 훅은 브라우저에서만 작동하므로, 위와 같은 방법으로 안전하게 사용해야 합니다.

---

📚 래퍼런스

• React Hook Form Docs - useWatch
• Next.js Docs - Hydration Errors
• React Docs - Hydration