[React] Next.js에서 GSAP(ScrollTrigger) 사용 시 발생하는 Hydration 오류 해결하기 - Hydration failed because the server rendered HTML didn't match the client.

안녕하세요, hr0513입니다! 🥰

 

Next.js에서 GSAP를 사용할 때 SSR(서버 사이드 렌더링) 때문에 어려움이 좀 있었는데요,

구글링으로도 해결방법을 찾지 못해서 직접 해결한 방법을 공유합니다.

---

오류 발생

useEffect 밖에 gsap.registerPlugin(ScrollTrigger) 을 넣게 되면 아래와 같은 오류가 발생해요.

Hydration failed because the server rendered HTML didn't match the client. As a result this tree will be regenerated on the client. This can happen if a SSR-ed Client Component used

 

---

문제의 원인

Next.js는 초기 페이지를 로드할 때 SSR로 서버에서 렌더링을 수행해요.

GSAP와 같은 클라이언트 사이드 라이브러리는 서버에서 실행되면 제대로 동작하지 않는데요,

특히 ScrollTrigger은 window나 document 객체에 접근해야 해서 클라이언트 환경에서만 사용이 가능합니다.

서버에서 이를 처리하려고 하면 오류가 발생하는 이유가 바로 이것이에요.

---

해결 방법

따라서 Next.js에서 GSAP를 적용하려면

"use client" 선언과 함께 useEffect 내부에 gsap.registerPlugin(ScrollTrigger)를 추가해야 합니다.

useEffect는 컴포넌트가 클라이언트에서 처음 렌더링된 후에 실행되므로, GSAP를 안전하게 사용할 수 있게 됩니다.

"use client";

import { useEffect } from "react";
import gsap from "gsap";
import { ScrollTrigger } from "gsap/ScrollTrigger";

useEffect(() => {
    gsap.registerPlugin(ScrollTrigger);
    ...
}, []);