[react-hydration-error] Hydration failed because the server rendered didn't match the client

[이전글 : 디자인 시스템이 뭔지 알고 싶다면 👉 ] 2024.07.11 - [👩🏻‍💻 dev] - 디자인 시스템 101 : 디자인 시스템이란?

👩🏻‍🔧 scss + next monorepo 디자인 시스템을 도입하는 중이다.
다크모드를 추가해주기 위해서 코드를 추가해 줬는데 새로고침을 할 때마다 "Hydration failed because the server rendered didn't match the client"의 에러가 발생했다.
다음에 같은 실수를 해도 헤매지 않고, 혹시나 나처럼 헤매고 계신 분들을 위해 조금이나 도움이 될까 기록을 남겨두고자 한다.
에러는 왜 발생한 건지, 그리고 어떻게 해결했는지 살펴보자!

🕵️ 문제 원인 찾기

이런 에러가 발생하면 next은 아주 친절하게 원인일 요소들, 그리고 해결책들을 안내해 준다.

물론 그중에 하나 혹은 여러 개가 원인이 되어서 에러가 발생한 것일 수 있지만,

하나씩 소거법으로 추려보면 해결 가능할 거 같다.

WHY!?

애플리케이션을 렌더링 하는 도중 서버에서 pre-render 했던 리액트 트리와 브라우저에 처음 렌더되는 리액트 트리가 불일치해서 발생한다.

Hydration이란 리액트가 pre-render 된 서버 쪽의 html을, 상호작용이 가능한 애플리케이션이 되도록 이벤트 핸들러를 추가한 버전으로 변경해 주는 작업이다.

가능성 높은 원인들

잘못된 HTML 태그 중첩
1. <p> 태그를 다른 <p> 태그 안에 중첩할 경우
2. <div>을 <p> 태그 안에 중첩할 경우
3. <ul>이나 <ol>을 <p> 태그 안에 중첩할 경우
4. 상호작용이 가능한 콘텐츠를 중첩할 경우 (예 : <a> 태그 안에 <a> 태그 중첩, <button> 태그 안에 <button> 태그)
렌더 로직으로 typeof window!= 'undefined'를 사용할 경우
브라우저에만 내장된 API (window, localStorage)를 렌더 로직으로 사용할 경우
Date() 생성자와 같은 시간에 의존하는 API를 렌더 로직에 사용할 경우
HTML을 변경하는 브라우저 확장자를 사용할 경우
CSS-in-JS 라이브러리를 잘못 설정한 경우
html 요청을 변경하려는 Edge/CDN 설정 (cloudflare auto minify)이 잘못된 경우

~~1번 확인 결과 : p 태그를 사용 x, 버튼 안에 버튼 x~~

~~2번 로직 사용 x~~

3번 👉 다크/ 라이트 모드를 localstorage에 확인/저장해서 설정 중, 유일하게 가능성이 있음.

~~4번 로직 사용 x~~

~~5번 브라우저 확장자 x~~

~~6번 scss 사용 중이므로 x~~

~~7번 Edge/CDN 설정 x~~

☺️ 해결 방안들

1. useEffect를 사용해서 클라이언트에서만 동작하도록 하기

첫 클라이언트 사이드 렌더와 서버 사이드 렌더 시 컴포넌트 콘텐츠가 동일하도록 해서 hydration 불일치를 방지해 보자.

의도적으로 useEffect 훅을 통해 클라이언트 쪽에서 다른 콘텐츠가 보이도록 만들 수 있다.

import { useState, useEffect } from 'react'
 
export default function App() {
  const [isClient, setIsClient] = useState(false)
 
  useEffect(() => {
    setIsClient(true)
  }, [])
 
  return <h1>{isClient ? 'This is never prerendered' : 'Prerendered'}</h1>
}

리액트 hydration 동안 useEffect가 호출된다.

따라서 window와 같은 브라우저 api를 hydration mismatch 사용 가능하다는 것이다.

2. 특정 컴포넌트에서는 SSR 동작 방지 ⭐️

nextjs는 특정 컴포넌트가 prerender 되는 걸 방지할 수 있다.

import dynamic from 'next/dynamic'
 
const NoSSR = dynamic(() => import('../components/no-ssr'), { ssr: false })
 
export default function Page() {
  return (
    <div>
      <NoSSR />
    </div>
  )
}

3. suppressHydrationWarning 사용

가끔 서버와 클라이언트 사이의 콘텐츠 불일치를 피할 수 없을 수도 있다. (ex. timestamp)

suppressHydrationWarning={true}를 엘리먼트에 추가하여 hydration 불일치 경고가 뜨지 않도록 할 수 있다.

<time datetime="2016-10-25" suppressHydrationWarning />

4. iOS 이슈

ios는 전화번호, 이메일 주소 혹은 콘텐츠의 데이터를 링크로 변경하려고 시도한다.

이런 시도 때문에 hydration 불일치가 발생할 수 있다.

다음과 같이 meta 태그를 추가하면 변경 시도를 차단할 수 있다.

<meta
  name="format-detection"
  content="telephone=no, date=no, email=no, address=no"
/>

이 중에 내가 살펴본 해결책은 2번!

1번 제외 이유 : 첫 렌더링 시 내가 선호하는 모드를 적용한 테마를 사용하고 싶기 때문에 보일 페이지가 같아야 한다는 점에서 조건부를 사용하는 의미가 없어짐

2번 선택 이유 : 훅은 클라이언트 컴포넌트에서만 호출가능하다. 훅을 반드시 써야 하는 컴포넌트의 prerender를 방지하자.

3번 제외 이유: 시간에 의존하는 렌더링이 아닌 내가 선택한 모드에 의존하므로 불가피한 hydration 불일치가 아닐 것 같아서.

4번 제외 이유: 링크, 이메일, 전화번호 등의 데이터를 보여주고 있지 않아서.

🕵️ 해결 코드

앱의 테마에 따라 다크/라이트 모드 스타일을 적용하고자 만든 body 컴포넌트 함수를 살펴보자.

"use client";

import { useAppTheme } from "@tripie/hooks";
import classNames from "classnames";
import { HTMLProps, ReactNode } from "react";
import "./_body.scss";

export interface BodyProps extends HTMLProps<BodyProps> {
  children: ReactNode;
}

const Body = ({ children, className, ...props }: BodyProps) => {
  const { mode } = useAppTheme();
  // mode을 className에 추가하고 토글되는 테마에 따라 스타일 적용
  return <div className={classNames(className, "body", mode)}>{children}</div>;
};
export default Body;

이때 useAppTheme은 커스텀 훅이다. 훅은 클라이언트 컴포넌트에서만 호출가능하다.

여기서 client과 server 간의 내용 불일치가 발생했던 것이다.

nextjs가 제시한 해결책을 따라 다음과 같이 수정해 주자.

<ThemeWrapper>는 <Body> 태그를 prerender 하지 못하도록 import를 해온 컴포넌트다.

코드는 다음과 같다.

import dynamic from "next/dynamic";
import { ReactNode } from "react";

const ThemeWrapper = dynamic(
  () => import("@tripie/design-system/components/body/body"),
  { ssr: false }
);

export default function ThemeProvider({
  children,
}: Readonly<{
  children: ReactNode;
}>) {
  return <ThemeWrapper>{children}</ThemeWrapper>;
}

🍀 마치면서

🤔 모노레포 패키지 안에서 .scss 파일을 import/export 하고 싶은데 한참 헤매다가 아직 방법을 알아내지 못했다..
💪하나씩 해봐야지

📚 References

https://nextjs.org/docs/messages/react-hydration-error

Text content does not match server-rendered HTML

Using App Router Features available in /app

nextjs.org

'👩🏻‍💻 dev' 카테고리의 다른 글

다크 모드 구현 (feat. 유저/os 제어권 넘기기) (0)	2024.07.24
[Sass] 주석(Comments) (0)	2024.07.21
[ turborepo 설정] storybook Chromatic CLI 으로 배포하는 법 (0)	2024.07.16
[spotify-api] VINYLIFY : 스포티파이 api활용한 검색 + 재생 프로젝트(n+1) vercel 배포 vite.config.ts 적용 안되는 문제 (0)	2024.07.15
Parsing error: ESLint was configured to run on `<tsconfigRootDir>/xxx` using `parserOptions.project`: /yyy/tsconfig.lint.json However, that TSConfig does not include this file (0)	2024.07.14

🥕 pyotato's dev farm

[react-hydration-error] Hydration failed because the server rendered didn't match the client

🕵️ 문제 원인 찾기

WHY!?

가능성 높은 원인들

☺️ 해결 방안들

1. useEffect를 사용해서 클라이언트에서만 동작하도록 하기

2. 특정 컴포넌트에서는 SSR 동작 방지 ⭐️

3. suppressHydrationWarning 사용

4. iOS 이슈

🕵️ 해결 코드

🍀 마치면서

📚 References

'👩🏻‍💻 dev' 카테고리의 다른 글

티스토리툴바

[react-hydration-error] Hydration failed because the server rendered didn't match the client

🕵️ 문제 원인 찾기

WHY!?

가능성 높은 원인들

☺️ 해결 방안들

1. useEffect를 사용해서 클라이언트에서만 동작하도록 하기

2. 특정 컴포넌트에서는 SSR 동작 방지 ⭐️

3. suppressHydrationWarning 사용

4. iOS 이슈

🕵️ 해결 코드

🍀 마치면서

📚 References

'👩🏻‍💻 dev' 카테고리의 다른 글

'👩🏻‍💻 dev' Related Articles

티스토리툴바