(해결 완료) Hydration failed because the initial UI does not match what was rendered on the server.

Posted May 11, 2024 Updated May 11, 2024

By saemii 5 min read

📌시작하며

이 글은 아래의 오류를 해결하고, 작성하는 포스팅입니다.

(해결 안됨) Hydration failed because the initial UI does not match what was rendered on the server.

⛔문제상황

문제상황을 복기해보자면, Header.tsx 컴포넌트에서, localStorage와 Tailwind를 이용해 light/dark mode를 구현하는 도중 해당 오류가 발생했다.

Error: Hydration failed because the initial UI does not match what was rendered on the server. Warning: Expected server HTML to contain a matching <path> in <svg>. See more info here: https://nextjs.org/docs/messages/react-hydration-error

렌더링 시점 문제라는 것은 파악해서, useEffect나 useLayoutEffect 등을 이용해 나름 해결을 시도하였으나 해결하지 못했었는데, 아예 코드를 다시 작성해 해결할 수 있었다.😎

❌기존 작성 코드 흐름

  
const initialTheme: ThemeType =
  typeof window !== "undefined"
    ? (localStorage.getItem("theme") as ThemeType) || "light"
    : "light"
const [theme, setTheme] = useState<ThemeType>(initialTheme)

useEffect(() => {
  if (typeof window !== "undefined") {
    localStorage.setItem("theme", theme)
    if (theme === "dark") {
      const htmlElement = document.querySelector("html") as HTMLElement
      htmlElement.classList.add("dark")
    } else {
      const htmlElement = document.querySelector("html") as HTMLElement
      htmlElement.classList.remove("dark")
    }
  }
}, [theme])

initialTheme: 코드가 클라이언트 측에서 실행되는지 확인한 다음, 로컬 스토리지에서 이전에 저장된 테마를 가져온다. 만약, 저장된 테마가 없다면 기본값으로 “light” 테마를 설정하고 state에 초기값으로 지정한다.
useEffect: theme 상태가 변경될 때 호출된다. 코드가 클라이언트 측에서 실행되는지 확인하고, 테마가 변경될 때마다 로컬 스토리지에 새로운 테마를 저장한다. 이때, dark 모드 인 경우 최상위 <html>요소에 dark 클래스를 추가해 tailwind의 darkmode를 적용한다.

🤔이 코드도 계속 발생하던 오류를 해결하지 못해 골머리를 앓았는데, 결국 해결 방법은 기존 코드를 조금씩 고치는게 아니라 다시 작성하는 거였다!😎

⭕개선한 코드 흐름

  
// theme 값 가져오기
const [theme, setTheme] = useState<ThemeType>("light")

//theme 설정 함수들
const setLightTheme = () => {
  localStorage.setItem("theme", "light")
  setTheme("light")
  const htmlElement = document.querySelector("html") as HTMLElement
  htmlElement.classList.remove("dark")
}

const setDarkTheme = () => {
  localStorage.setItem("theme", "dark")
  setTheme("dark")
  const htmlElement = document.querySelector("html") as HTMLElement
  htmlElement.classList.add("dark")
}

useEffect(() => {
  const storedTheme = localStorage.getItem("theme") as ThemeType

  if (storedTheme) {
    if (storedTheme === "dark") {
      setDarkTheme()
    } else if (storedTheme === "light") {
      setLightTheme()
    }
  } else {
    setLightTheme()
  }
}, [])

useState: 기존에 initialTheme를 확인하고 state 초기값으로 설정하지 않고, 처음에는 초기 테마를 “light”로 설정해주었다.
useEffect: 컴포넌트가 마운트될 때 실행된다. 로컬 스토리지에서 이전에 저장된 테마를 가져오고, 저장된 값이 없는 경우 기본값 ‘light’를 사용하고, 있으면 각각의 테마 함수를 실행한다.
setLightTheme / setDarkTheme: 각각의 테마를 설정한다. 최상위 <html>태그에 dark class를 넣거나 제거하여 Tailwind의 darkmode가 적용되도록 한다.
- 기존의 코드에서는 이 부분을 useEffect로 theme가 바뀔때마다 실행되게 했지만, 이 코드에서는 dark/light 아이콘을 클릭하면 각 아이콘에 해당하는 함수가 실행되도록 변경했다.

✅공식문서를 읽고 복기

공식문서를 읽으면서 해당 에러를 다시 복기했는데, 잘못 이해한 부분이 있던 것을 깨달았고, 이 부분도 수정해주었다.😅

해당 오류가 발생할 수 있는 상황

렌더링 로직에서 typeof window !== 'undefined'을 체크할 때
브라우저 전용 API인 window나 localStorage를 사용할 때

처음 이해할 땐 1번을 사용하면 이 에러를 없앨 수 있는 것으로 오해했었다…🥲 이후 이 부분을 삭제 해주 었고, 브라우저 전용 API인 localStorage는 useEffect에서 마운트 된 이후에 접근할 수 있도록 코드를 개선하며, 이 에러를 해결 할 수 있었다.

Error

This post is licensed under CC BY 4.0 by the author.