새로 고침 직후 날짜가 바뀌고, 색상 모드가 한 번 깜빡였습니다. 버튼을 고치기 전에 서버가 보낸 HTML과 브라우저가 처음 그린 화면부터 나란히 봤습니다. 같은 페이지처럼 보여도 입력값이 서로 달랐습니다.

경고보다 먼저, 달라진 값을 찾기#

개발 도구의 hydration 경고는 출발점입니다. 문구가 다른지, 요소 개수가 다른지, 브라우저가 잘못된 HTML 구조를 고쳤는지부터 구분합니다. 여기서는 날짜·설정처럼 값의 출처가 달라지는 경우를 다룹니다.

  1. 서버 응답의 HTML을 저장합니다. 자바스크립트가 바꾼 뒤의 DOM과 구분합니다.

  2. 날짜, ID, 언어, 저장된 설정 중 달라진 값을 표시합니다.

  3. 같은 입력으로 새로 고쳤을 때도 차이가 반복되는지 확인합니다.

값의 출처를 세 갈래로 나누기#

값을 만드는 위치를 적어 두면 확인 순서가 짧아집니다. 화면 크기처럼 서버가 알 수 없는 값과, 요청 언어처럼 양쪽이 공유할 수 있는 값을 같은 방식으로 다루지 않습니다.

처음 그리는 화면이 달라지는 세 가지 경우
값의 출처예보이는 차이먼저 확인할 곳
시간과 난수현재 시각, 무작위 ID새로 고칠 때마다 달라지는 값렌더링 중 값을 생성하는 코드
브라우저의 환경화면 크기, 저장된 색상 모드기기나 저장 설정에 따른 차이첫 분기에서 호출한 브라우저 API
서버 요청의 환경요청 언어, 시간대날짜와 숫자 표기의 차이브라우저에 전달한 초기 데이터

처음 보여 줄 문자열을 함께 전달하기#

날짜는 원래 시각과 표시할 문장을 함께 보냅니다. 아래 Rust/Leptos 컴포넌트는 어느 쪽에서 실행해도 받은 문자열을 그대로 사용합니다. 첫 화면에서 현재 시각을 읽거나 언어를 다시 추측하지 않습니다.

src/features/posts/published_at.rs
use leptos::prelude::*;​#[component]pub fn PublishedAt(iso: String, label: String) -> impl IntoView {    view! { <time datetime=iso>{label}</time> }1}
  1. 1
    기계가 읽는 시각과 사람이 읽는 문장을 각각 전달합니다.5행

상대 시간처럼 브라우저에서 보완할 표현은 hydration 이후에 갱신합니다. 색상 모드를 첫 화면부터 정확히 맞춰야 한다면 서버도 읽을 수 있는 쿠키 등에 설정을 두는 방법을 따로 검토합니다.

  1. 같은 입력으로 비교

    고정된 날짜·언어·설정으로 서버 HTML과 첫 DOM을 비교합니다.

  2. 브라우저 보완 확인

    화면이 연결된 뒤에만 상대 시간이나 저장 설정이 반영되는지 봅니다.

  3. 다른 환경에서 재현

    언어와 시간대를 바꾸고 직접 주소로 들어가 다시 확인합니다.

참고 자료

  1. Leptos. (2026 열람). Hydration Bugs