출처 : ethanniser.dev - A Clock That Doesn't Snap (2025.08.17)

상태가 영 별로다. 고쳐보자.

Hydration은 신경 쓰고 싶지 않은 것 중 하나인데, 예상치 못한 순간에 늘 문제를 일으킨다.

정적으로 사전 렌더링(prerender)된 후 hydration되는 시계를 보여주겠다. 많은 개발자 블로그에서 흔히 볼 수 있는 것이다¹:

왜 이런 일이 벌어질까?

두 가지 요인이 결합된 결과다:

정적으로(또는 부분적으로²) 사전 생성된 페이지를 불러올 때
"요청 시점" 정보에 의존하는 UI 컴포넌트를 사용할 때

빌드할 때 페이지를 미리 렌더링하면, UI의 그 자리를 뭔가로 채워야 한다. 문제는 "제대로 된" UI를 보여주려면 요청 시점의 정보가 필요한데 우리한텐 그게 없다는 것이다. 해결책은 종종 UI의 해당 부분을 비워두는 것이다. 또는 더 나쁜 경우로, 이 예시에서처럼 페이지가 렌더링되었던 시점의 오래된 데이터를 표시하는 것이다.

문제는 우리가 정말로 페이지를 정적으로 생성하기를 원한다는 것이다! CDN에서 바로 가져다 쓰면 속도가 훨씬 빠르고, 첫 응답 시간(TTFB)과 첫 화면 표시 속도(FCP)에서 차이가 크다.

그렇다면 이걸 포기하고 페이지를 SSR한다고 해보자. 이렇게 하면 대부분의 경우 문제가 해결되지만, 사실 모든 경우는 아니다. SSR은 요청 시점 데이터(전체 URL, 헤더, 쿠키 등)에 접근할 수 있지만 클라이언트 전용 데이터(로컬/세션 스토리지, 브라우저 정보 등)는 접근할 수 없다. 여전히 막막하다는 뜻이다.

이 정도는 받아들이고, 빈 화면이 살짝 깜빡이는 건 괜찮다고 생각할 수도 있지만, 나는 싫다. CDN 캐시된 TTFB도 갖고 싶고 깜빡임 없는 완벽한 첫 렌더링도 필요하다.

JavaScript 손자병법이라고? 받아들이지 않겠다!

좋다, 이 글 맨 위의 GIF를 봤을 것이다. 해결 방법이 있다.

솔직히 말하면 가장 우아한 방법은 아니지만, 작동은 한다: 인라인 스크립트 태그를 사용하는 거다.

생각해보면, 페이지를 사전 렌더링하지 않을 수는 없으니 HTML은 어차피 낡은 상태로 내려올 수밖에 없다. React 쪽에서 뭘 해볼 수도 없다. 그런 건 전부 hydration 이후에 일어나는데, 그때는 이미 오래된 상태가 사라진 뒤고 첫 번째 가시적 페인트(first visible paint)가 훨씬 지난 시점이다.

하지만 인라인 스크립트 태그라면... 이건 HTML에서 해당 요소 바로 뒤에 붙일 수 있고, 필요한 동적 상태를 읽어서 요소를 올바른 값으로 설정할 수 있다. 브라우저가 워낙 빨리 파싱하고 실행해버려서 사용자는 초기 상태를 아예 못 본다.

완벽하다! 좀 무섭긴 한데, 일단 그건 넘어가자.

예시를 보자:

function Clock() { 
  const [time, setTime] = useState(() => new Date());
  
  useEffect(() => { 
    const timer = setInterval(() => { 
      setTime(new Date()); 
    }, 10); 
    return () => clearInterval(timer); 
  }, []);
  
  const secondRotation = time.getSeconds() * 6 + time.getMilliseconds() * 0.006;
  
  return (
    <div>
      <svg width="200" height="200" viewBox="0 0 100 100">
        {/* 시계판 */}
        <circle
          cx="50"
          cy="50"
          r="45"
          fill="white"
          stroke="black"
          strokeWidth="2"
        />

        {/* 중심점 */}
        <circle cx="50" cy="50" r="2" fill="black" />

        {/* 초침 */}
        <line
          x1="50"
          y1="50"
          x2="50"
          y2="10"
          stroke="red"
          strokeWidth="1"
          transform={`rotate(${secondRotation}, 50, 50)`}
          style={{
            transition: "transform 0.1s linear",
          }}
          id="second-hand"
        />
      </svg>
    </div>
  );
}

시간을 추적하는 상태가 있고, JavaScript로 계산된 회전값으로 10밀리초마다 애니메이션되는 svg 바늘이 있다. 사전 렌더링되면 hydration 전까지 오래된 초기 상태를 갖게 되고, 초침이 현재 시간으로 크게 튀면서 움직이는 전형적인 컴포넌트다.

id="second-hand"를 주목하자. 곧 중요해진다.

다음으로 두 번째 컴포넌트를 만든다:

function InlineScript() { 
  return ( 
    <script dangerouslySetInnerHTML={{ 
      __html: `(${(() => { 
        const secondHand = document.getElementById("second-hand"); 
        if (!secondHand) { 
          console.error("초침을 찾을 수 없음"); 
          return; 
        } 
        const time = new Date(); 
        // Clock 컴포넌트와 동일한 로직 사용
        const secondRotation = time.getSeconds() * 6 + time.getMilliseconds() * 0.006; 
        secondHand.setAttribute("transform", `rotate(${secondRotation}, 50, 50)`); 
      }).toString()})()` 
    }} /> 
  );
}

"IIFE + 화살표 함수 toString" 방식은 문자열을 직접 쓰는 것과 달리 함수를 작성할 때 TypeScript 지원을 완전히 받을 수 있는 멋진 트릭이다. 근데 착각은 금물이다. 이건 결국 문자열로 변환돼서 인라인으로 들어간다. 전역 변수 말고는 이 블록 밖의 뭐든 참조할 수 없다.

스크립트에서 요소를 id로 가져온 다음, 컴포넌트에서 사용하는 것과 똑같은 로직으로 회전 속성의 상태를 계산하고 설정한다.

그런 다음 컴포넌트와 스크립트 태그를 차례로 렌더링한다:

export default function Page() { 
  return ( 
    <> 
      <Clock /> 
      <InlineScript /> 
    </> 
  );
}

끝이다. 더 이상 큰 튐 현상이 없다. 스크립트 태그가 첫 페인트 전에 실행되므로 사용자는 사전 렌더링된 페이지의 깨진 초기 상태를 절대 보지 못한다. 좋다!

여기서 주목할 게 몇 가지 있다.

첫째, 코드에 눈에 보이는 깜빡임은 없지만 <line> 요소에서 React hydration 에러가 여전히 발생한다. 인라인 스크립트 태그 실행과 React 실행 사이에 약간의 시간차가 있어서 secondRotation 값이 정확히 같지 않기 때문이다.

이를 피하려면 React useState 초기화 함수를 사용해서 DOM에서 초기 상태를 읽으면 된다. 이 기법은 React가 올바른 상태로 "시작"하도록 하는 사전 hydration 꼼수에 꽤 유용하다.

declare global {
  interface Window {
    __INITIAL_TIME__?: number;
  }
}

function Clock() {
  const [time, setTime] = useState(() => {
    // 클라이언트에서는 인라인 스크립트의 초기 시간 사용
    if (typeof window !== "undefined" && window.__INITIAL_TIME__) {
      return new Date(window.__INITIAL_TIME__);
    }
    // 서버에서는 현재 시간 사용
    return new Date();
  });
  // ...
}

function InlineScript() {
  return (
    <script
      dangerouslySetInnerHTML={{
        __html: `(${(() => {
          const secondHand = document.getElementById("second-hand");
          if (!secondHand) {
            console.error("Second hand not found");
            return;
          }
          // React가 나중에 읽을 초기 상태 계산에 사용할 시간 설정
          window.__INITIAL_TIME__ = Date.now();
          const time = new Date(window.__INITIAL_TIME__);
          // Clock 컴포넌트와 동일한 로직 사용
          const secondRotation =
            time.getSeconds() * 6 + time.getMilliseconds() * 0.006;
          secondHand.setAttribute(
            "transform",
            `rotate(${secondRotation}, 50, 50)`,
          );
        }).toString()})()`,
      }}
    />
  );
}

이 패턴의 또 다른 좋은 예시는 텍스트 입력 상태가 hydration에 의해 "지워지지" 않도록 하는 것이다. 이 경우 스크립트 태그가 필요 없고, DOM의 값으로 상태를 초기화하기만 하면 된다.

function Input() {
  const [value, setValue] = useState(() => {
    if (typeof window !== "undefined") {
      const input = document.getElementById("input");
      if (input && input instanceof HTMLInputElement) {
        return input.value;
      }
    }
    return "";
  });

  return (
    <input
      value={value}
      onChange={(e) => setValue(e.target.value)}
      id="input"
    />
  );
}

둘째, 애플리케이션 상태에서 UI 상태를 도출하는 로직이 무엇이든 간에, 컴포넌트 본문과 인라인 스크립트 태그 사이에서 동기화되는 게 매우 중요하다. 이상적으로는 그 로직을 함수로 빼내서 둘 사이에서 공유하면 되지만, 스크립트 태그 안에서는 아무것도 import할 수 없다는 걸 기억하자! 그래서 사실상 불가능하다.

Next.js를 사용한다면 instrumentation-client.js 파일이 실제로 도움이 될 수 있다. import를 해석하고 코드를 번들링하면서도 여전히 hydration 전에 실행되기 때문이다. 하지만 이건 전체 HTML 문서가 로드된 후에 실행되므로 첫 페인트 전에 실행되기에는 충분히 빠르지 않을 수 있다(나는 이런 스크립트 태그를, 대상 요소 바로 뒤에 최대한 가까이 넣는 걸 선호한다).

이론적으로는 프레임워크가 이런 케이스를 더 지원해줄 수 있을 것이다. 마지막으로 들은 바로는 React 팀이 "검토해봤다"고 했으니, 뭔가 나올지 지켜보자.

최근에 이걸 라이브러리로 만든다면 어떤 API가 될지 이것저것 탐구해봤다. 하지만 내 솔루션은 "pre-hydration" 섹션에 쓰인 코드를 따로 뽑아서 인라인되는 자체 번들로 만들기 위해 꽤 미친 컴파일러/번들러 핵이 필요하다. 하지만 이렇게 하면 스크립트 태그에 거대한 라이브러리를 import하는 게 너무 쉬워 보여서 발등을 찍을 위험이 있다.

이걸 라이브러리로 만드는 건 좋지 않은 아이디어일 수 있다. 그다지 지속 가능한 패턴이 아니니까. "그럼 hydration 전후에 특정 컴포넌트를 그대로 렌더링할 수 있게 React 초경량 버전을 인라인으로 박아버리면 되잖아?"라는 식으로 금방 변질될 게 보이는데, 이건 꽤 끔찍하다.

하지만 지금은 이 솔루션으로 괜찮다고 본다. 실제로 놀랄 만큼 여러 번 꺼내 써야 했기 때문에, 더 견고한 장기 솔루션이 나오길 바란다.

직접 이런 것들을 가지고 놀아보자!

이 글의 예시 링크:

preview
git (window.__INITIAL_TIME__ 관련 코드는 no-hydration-warning 브랜치에 있다)

각주

이 예시는 내 좋은 친구 Charlie의 사이트에서 가져왔다. 이후 이 글의 기법으로 고쳐졌다!
Next.js 부분 사전 렌더링 참고: https://nextjs.org/docs/app/api-reference/config/next-config-js/ppr

[FE/react] 깜빡임 없는 시계