React 하이드레이션 오류: localStorage 읽기를 useSyncExternalStore로 다룬 사례

Uncaught Error: Hydration failed because the server rendered HTML
didn't match the client.

// RecentlyRead 컴포넌트
+  <div className="flex gap-2 overflow-x-auto ...">   ← 클라이언트
-  <p className="text-sm text-gray-500 ...">            ← 서버

// PostExplorer의 FileItem 컴포넌트
+  className="... text-gray-400 dark:text-gray-500"   ← 클라이언트 (방문한 글)
-  className="... text-gray-800 dark:text-gray-200"   ← 서버 (미방문)

export function getReadPosts(): ReadRecord[] {
  if (typeof window === "undefined") return [];
  try {
    const raw = localStorage.getItem(STORAGE_KEY);
    return raw ? (JSON.parse(raw) as ReadRecord[]) : [];
  } catch {
    return [];
  }
}

export function RecentlyRead({ rootPath = "/" }: RecentlyReadProps) {
  const [mounted, setMounted] = useState(false);

  useEffect(() => {
    setMounted(true);
  }, []);

  const readPosts = mounted ? getReadPosts() : [];
  // ...
}

Error: Calling setState synchronously within an effect
can trigger cascading renders

const value = useSyncExternalStore(
  subscribe, // 외부 스토어가 변경될 때 호출될 콜백을 등록
  getSnapshot, // 클라이언트에서 현재 값을 가져오는 함수
  getServerSnapshot, // 서버에서 사용할 초기값을 반환하는 함수
);

function subscribeStorage(cb: () => void) {
  window.addEventListener("storage", cb);
  return () => window.removeEventListener("storage", cb);
}

const EMPTY_POSTS: ReadRecord[] = [];
const EMPTY_SET = new Set<string>();

export function RecentlyRead({ rootPath = "/" }: RecentlyReadProps) {
  const readPosts = useSyncExternalStore(
    subscribeStorage,
    getReadPosts, // 클라이언트: localStorage에서 읽기
    () => EMPTY_POSTS, // 서버: 빈 배열
  );
  const commentedPosts = useSyncExternalStore(
    subscribeStorage,
    getCommentedPosts,
    () => EMPTY_SET,
  );
  // ...
}

const EMPTY_POSTS: ReadRecord[] = [];

export function PostExplorer({ rootPath = "/" }: PostExplorerProps) {
  const readPosts = useSyncExternalStore(
    subscribeStorage,
    getReadPosts,
    () => EMPTY_POSTS,
  );
  const visitedHref = new Set(readPosts.map((p) => p.href));
  // ...
}

[useState + useEffect]
  서버 렌더링 → HTML (빈 데이터)
  클라이언트 하이드레이션 → 첫 렌더링 (빈 데이터, 서버와 일치 ✓)
  useEffect 실행 → setMounted(true) → 리렌더링 ← cascading render 경고!
  두 번째 렌더링 → localStorage 데이터 표시

[useSyncExternalStore]
  서버 렌더링 → HTML (getServerSnapshot = 빈 데이터)
  클라이언트 하이드레이션 → getServerSnapshot = 빈 데이터 (서버와 일치 ✓)
  하이드레이션 후 → getSnapshot = localStorage 데이터
  외부 스토어가 달라졌으면 다시 렌더링

The result of getSnapshot should be cached to avoid an infinite loop

const EMPTY_READ_POSTS: ReadRecord[] = [];
let _readPostsCache: ReadRecord[] = EMPTY_READ_POSTS;
let _readPostsRaw: string | null = null;

export function getReadPosts(): ReadRecord[] {
  if (typeof window === "undefined") return EMPTY_READ_POSTS;
  try {
    const raw = localStorage.getItem(STORAGE_KEY);
    if (raw !== _readPostsRaw) {
      _readPostsRaw = raw;
      _readPostsCache = raw ? (JSON.parse(raw) as ReadRecord[]) : [];
    }
    return _readPostsCache;
  } catch {
    return EMPTY_READ_POSTS;
  }
}

// ✓ 모듈 레벨 상수 — 참조가 안정적
const EMPTY_POSTS: ReadRecord[] = [];
const EMPTY_SET = new Set<string>();

// △ 컴포넌트 안에서 인라인 — 호출할 때마다 새 참조
useSyncExternalStore(subscribe, getSnapshot, () => []);