nextjs-localstorage-persistence

jhlee0409 的头像作者 jhlee0409

在Next.js 14应用路由器中使用SSR安全模式实现localStorage持久性。在localStorage中存储数据、处理水合错误、实现状态持久性或创建类型安全存储工具时使用。

📖 中文导读:在Next.js 14应用路由器中使用SSR安全模式实现localStorage持久性。在localStorage中存储数据、处理水合错误、实现状态持久性或创建类型安全存储工具时使用。 以下正文为该技能的原始 SKILL.md 内容(英文),上方安装命令可直接使用。

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

When to Use

  • Next.js에서 localStorage 사용 시 하이드레이션 에러 발생
  • 세션 간 상태 지속성 구현 시
  • 타입-안전한 스토리지 추상화 필요 시
  • Zustand persist 미들웨어 설정 시