SEO Jing
본문 이미지를 나중에 넣는 게 아니라 — SEOJing 글쓰기.
SEOJing에서 새 글을 쓸 때 대표 이미지와 본문 이미지를 빼먹지 않도록, 블로그 맵과 글쓰기 파이프라인 안에 시각 판단 단계를 넣은 과정을 정리했다.
ReactuseSyncExternalStoreHydrationlocalStorage트러블슈팅DevLog
React 하이드레이션 오류: localStorage 읽기를 useSyncExternalStore로 다룬 사례
수정 11분 읽기
문제 상황
블로그의 "최근 읽은 글"과 "포스트 탐색기" 컴포넌트에서 하이드레이션 에러가 터졌다.
원인은 서버에서는 빈 목록을 그렸는데, 클라이언트의 첫 렌더링에서는 localStorage에 저장된 글을 바로 읽어 다른 HTML을 만든 것이었다. 이 사례에서는 서버와 하이드레이션 중에 같은 빈 스냅샷을 쓰고, 하이드레이션이 끝난 뒤 브라우저의 값을 읽도록 바꿨다.
text
Uncaught Error: Hydration failed because the server rendered HTML
didn't match the client.에러 메시지의 diff를 보면 원인이 명확하다.
text
// 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" ← 서버 (미방문)서버에서는 "읽은 글 없음" 상태로 렌더링되고, 클라이언트에서는 localStorage에 저장된 데이터로 렌더링된다. 두 결과가 다르니 React가 하이드레이션 에러를 던진 것이다.
localStorage가 React 하이드레이션 오류를 일으킨 이유
두 컴포넌트 모두 getReadPosts()를 호출해서 읽은 글 목록을 가져온다. 이
함수의 구현을 보자.
ts
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 [];
}
}서버에서는 window가 없으므로 빈 배열을 반환한다. 클라이언트에서는
localStorage에서 데이터를 읽어 반환한다.
하이드레이션의 핵심 규칙은 이것이다 — 서버에서 렌더링한 HTML과 클라이언트의 첫 번째 렌더링 결과가 동일해야 한다.
서버는 빈 배열 → "열람한 페이지가 없습니다" <p> 태그를 렌더링하고,
클라이언트는 localStorage 데이터 → 카드 목록
Post Q&A
오케이징에게 물어보기
React 하이드레이션 오류: localStorage 읽기를 useSyncExternalStore로 다룬 사례 전체를 기준으로 질문과 피드백을 받아요.답을 본 뒤에는 이 내용을 댓글로 달아서 서징에게도 물어볼 수 있어요. 작성자가 직접 볼 수 있어요!
0/500
포스트 목록
/SEOJing
파일 15개, 폴더 1개
Cloudflare Workers에서 fs 모듈이 안 되는 이유와 해결법대표 이미지 자동화 실험 — 검색과 Codex 생성이 같은 경로로 붙었다본문 이미지를 나중에 넣는 게 아니라 — SEOJing 글쓰기 파이프라인에 시각 판단을 넣기모바일 웹에서 가로 모드를 강제하는 5가지 방법 — iOS Safari에서도 동작하는 코드 뷰어 만들기블로그 글을 PPT로 만들기 — DOM 클로닝 기반 프레젠테이션 모드100vh가 100%가 아닌 이유 — 모바일 뷰포트 단위 완전 정리Context로 퀴즈 컴포넌트를 만들다 막혀서 React.Children을 공부하게 된 이야기대표 이미지를 글마다 다시 붙이는 방식 — 사진 검색에서 리소그래프 배경까지글 위에 영상을 붙인다는 것 — SEOJing 요약 쇼츠 파이프라인React 하이드레이션 오류: localStorage 읽기를 useSyncExternalStore로 다룬 사례useEffect cleanup과 의존성 배열 — 실전 버그 사례로 이해하는 생애주기vinext + GitHub Actions로 Cloudflare Workers 배포하기vinext 오픈소스 기여기: 한국어 slug가 RSC에서 이슈를 일으킨 이유RSC 환경에서 WebAssembly가 차단되는 이유 — Shiki에서 rehype-prism-plus로vinext는 왜 빠를까? — SSR, Vite, Edge, 그리고 Web Vitals까지
