JS로 반응형 다루기: matchMedia, useMediaQuery, ResizeObserver와 SSR 하이드레이션 함정

sequenceDiagram
    participant S as 서버(SSR)
    participant B as 브라우저 DOM
    participant C as 클라이언트 JS(hydrate)
 
    S->>B: window 없음 → isMobile 값을 모름
    Note over S,B: 일단 "데스크톱"으로 가정하고 HTML 생성
    B->>C: 데스크톱용 마크업이 화면에 표시됨
    C->>C: mount 후 matchMedia로 실제 폭 측정
    Note over C: 실제로는 모바일이었음!
    C->>B: 모바일용으로 다시 렌더링
    Note over B: 화면이 깜빡이며 바뀜(layout shift)<br/>+ 하이드레이션 불일치 경고

// ⚠️ SSR에서 문제가 있는 버전
import { useEffect, useState } from 'react';
 
export function useMediaQuery(query: string) {
  const [matches, setMatches] = useState(false); // 서버·첫 렌더는 무조건 false
 
  useEffect(() => {
    const mql = window.matchMedia(query);
    setMatches(mql.matches);
 
    const onChange = (e: MediaQueryListEvent) => setMatches(e.matches);
    mql.addEventListener('change', onChange);
    return () => mql.removeEventListener('change', onChange);
  }, [query]);
 
  return matches;
}

import { useSyncExternalStore } from 'react';
 
export function useMediaQuery(query: string) {
  const subscribe = (callback: () => void) => {
    const mql = window.matchMedia(query);
    mql.addEventListener('change', callback);
    return () => mql.removeEventListener('change', callback);
  };
 
  const getSnapshot = () => window.matchMedia(query).matches; // 클라이언트: 실제 값
  const getServerSnapshot = () => false; // 서버: 명시적 기본값
 
  return useSyncExternalStore(subscribe, getSnapshot, getServerSnapshot);
}

'use client';
import { useSyncExternalStore } from 'react';
 
export function Nav() {
  const isDesktop = useMediaQuery('(min-width: 768px)');
  const mounted = useSyncExternalStore(
    () => () => {},
    () => true, // 클라이언트
    () => false // 서버·첫 렌더
  );
 
  // 아직 화면 폭을 신뢰할 수 없는 첫 렌더에는 공통 UI
  if (!mounted) return <NavSkeleton />;
 
  return isDesktop ? <DesktopNav /> : <MobileNav />;
}

import { useEffect, useRef, useState } from 'react';
 
export function useElementWidth<T extends HTMLElement>() {
  const ref = useRef<T>(null);
  const [width, setWidth] = useState<number | null>(null);
 
  useEffect(() => {
    const el = ref.current;
    if (!el) return;
 
    const observer = new ResizeObserver((entries) => {
      const entry = entries[0];
      // 최신 브라우저는 contentBoxSize, 구형 브라우저는 contentRect로 폴백
      const width = entry.contentBoxSize?.[0]?.inlineSize ?? entry.contentRect.width;
      setWidth(width);
    });
 
    observer.observe(el);
    return () => observer.disconnect();
  }, []);
 
  return { ref, width };
}

'use client';
export function Chart() {
  const { ref, width } = useElementWidth<HTMLDivElement>();
 
  return (
    <div ref={ref}>
      {/* 라이브러리에 숫자 크기를 넘겨야 하는 경우 */}
      {width !== null && <BarChart width={width} height={width * 0.6} />}
    </div>
  );
}

flowchart TD
    q["화면/요소 크기에 반응해야 한다"]
    q --> css{"스타일·배치만<br/>바뀌면 되나?"}
    css -->|"예"| useCss["CSS로 해결<br/>미디어/컨테이너 쿼리,<br/>clamp, auto-fit"]
    css -->|"아니오"| dom{"DOM 구조나 JS 값이<br/>실제로 달라져야 하나?"}
    dom -->|"뷰포트 기준"| mm["matchMedia +<br/>useSyncExternalStore"]
    dom -->|"요소 크기 기준"| ro["ResizeObserver"]
 
    style useCss fill:#dcfce7,stroke:#22c55e,color:#111
    style mm fill:#dbeafe,stroke:#3b82f6,color:#111
    style ro fill:#dbeafe,stroke:#3b82f6,color:#111