nextjs-localstorage-persistence
Implement localStorage persistence in Next.js 14 App Router with SSR-safe patterns. Use when storing data in localStorage, handling hydration errors, implementing state persistence, or creating type-safe storage utilities.
When & Why to Use This Skill
This Claude skill provides specialized patterns and utilities for implementing SSR-safe localStorage persistence in Next.js 14 App Router. It solves the common 'Hydration failed' errors by providing industry-standard patterns for accessing browser-only APIs, ensuring seamless state synchronization between the server and client while maintaining type safety.
Use Cases
- Case 1: Eliminating hydration mismatch errors when initializing React state from localStorage in a Next.js environment.
- Case 2: Implementing persistent user preferences, such as dark mode or language settings, that remain consistent across browser sessions.
- Case 3: Developing type-safe storage wrappers to prevent runtime errors and ensure data integrity when interacting with browser storage APIs.
- Case 4: Integrating state management libraries like Zustand with persistence middleware specifically optimized for the Next.js lifecycle.
| name | nextjs-localstorage-persistence |
|---|---|
| description | Implement localStorage persistence in Next.js 14 App Router with SSR-safe patterns. Use when storing data in localStorage, handling hydration errors, implementing state persistence, or creating type-safe storage utilities. |
Next.js LocalStorage Persistence
Next.js 14 App Router에서 SSR-안전한 localStorage 지속성 구현 스킬입니다.
Quick Reference
SSR-Safe 패턴
// ❌ 잘못된 방법 - 하이드레이션 에러 발생
const data = localStorage.getItem('key');
// ✅ 올바른 방법 - useEffect 내에서 사용
useEffect(() => {
const data = localStorage.getItem('key');
}, []);
하이드레이션 에러 방지
const [hydrated, setHydrated] = useState(false);
useEffect(() => {
setHydrated(true);
}, []);
if (!hydrated) return <Loading />;
Contents
- reference.md - SSR/CSR 라이프사이클 및 하이드레이션 가이드
- guide.md - 타입-안전 스토리지 유틸리티 및 Zustand 통합
- scripts/validate_storage_schema.py - 스토리지 스키마 검증
When to Use
- Next.js에서 localStorage 사용 시 하이드레이션 에러 발생
- 세션 간 상태 지속성 구현 시
- 타입-안전한 스토리지 추상화 필요 시
- Zustand persist 미들웨어 설정 시