• 보일러플레이트 제로 - Provider 없이도 작동해요
• 타입 추론이 자동 - 타입스크립트랑 궁합이 환상적이에요
• React 18 동시성 모드 완벽 지원 - Next.js 15랑 같이 쓰기 최적
• 서버 컴포넌트 호환성 - SSR 타입 안전성 보장 가능

npm install zustand@latest
npm install -D @types/node typescript

yarn add zustand
yarn add -D @types/node typescript

pnpm add zustand
pnpm add -D @types/node typescript

{
  "compilerOptions": {
    "strict": true,
    "strictNullChecks": true,
    "noImplicitAny": true,
    "esModuleInterop": true,
    "skipLibCheck": true,
    "forceConsistentCasingInFileNames": true,
    "moduleResolution": "bundler",
    "resolveJsonModule": true,
    "isolatedModules": true,
    "jsx": "preserve",
    "incremental": true,
    "plugins": [
      {
        "name": "next"
      }
    ],
    "paths": {
      "@/*": ["./src/*"]
    }
  }
}

src/
├── app/                    # Next.js 15 App Router
│   ├── layout.tsx
│   └── page.tsx
├── stores/                 # Zustand 스토어 모음
│   ├── index.ts           # 모든 스토어 export
│   ├── userStore.ts       # 사용자 상태
│   └── types.ts           # 스토어 타입 정의
├── hooks/                  # 커스텀 훅
│   └── useStore.ts        # 타입 안전 스토어 훅
└── types/                  # 전역 타입 정의
    └── index.ts

혹시 버전이 맞지 않는다면요, node_modules 폴더를 삭제하고 package-lock.json (또는 yarn.lock, pnpm-lock.yaml)도 지운 다음 다시 설치해보세요. 캐시 때문에 구버전이 남아있는 경우가 있거든요.

import { create } from 'zustand';
import { devtools, persist } from 'zustand/middleware';

// 1. State 타입 먼저 정의
interface User {
  id: string;
  name: string;
  email: string;
}

interface UserState {
  user: User | null;
  isLoading: boolean;
  error: string | null;
}

// 2. Actions 타입 정의
interface UserActions {
  setUser: (user: User) => void;
  clearUser: () => void;
  updateUser: (updates: Partial<User>) => void;
  fetchUser: (id: string) => Promise<void>;
}

// 3. 전체 스토어 타입 결합
type UserStore = UserState & UserActions;

export const useUserStore = create<UserStore>()(
  devtools(
    persist(
      (set, get) => ({
        // 초기 상태
        user: null,
        isLoading: false,
        error: null,

        // 액션들
        setUser: (user) => 
          set({ user, error: null }, false, 'setUser'),

        clearUser: () => 
          set({ user: null }, false, 'clearUser'),

        updateUser: (updates) => 
          set(
            (state) => ({
              user: state.user ? { ...state.user, ...updates } : null
            }),
            false,
            'updateUser'
          ),

        fetchUser: async (id) => {
          set({ isLoading: true, error: null });
          try {
            const response = await fetch(`/api/users/${id}`);
            if (!response.ok) throw new Error('Failed to fetch user');
            const user = await response.json();
            set({ user, isLoading: false }, false, 'fetchUser/success');
          } catch (error) {
            set({ 
              error: error instanceof Error ? error.message : 'Unknown error',
              isLoading: false 
            }, false, 'fetchUser/error');
          }
        }
      }),
      {
        name: 'user-storage',
        partialize: (state) => ({ user: state.user }), // user만 persist
      }
    )
  )
);

// 셀렉터 함수들을 별도로 정의
export const selectUser = (state: UserStore) => state.user;
export const selectIsLoading = (state: UserStore) => state.isLoading;
export const selectUserName = (state: UserStore) => state.user?.name;
export const selectUserEmail = (state: UserStore) => state.user?.email;

// 컴포넌트에서 사용
export default function UserProfile() {
  // ✅ 이렇게 하면 user가 변경될 때만 리렌더링
  const user = useUserStore(selectUser);
  
  // ✅ name만 필요하면 name만 구독
  const userName = useUserStore(selectUserName);
  
  // ❌ 이렇게 하면 모든 상태 변경에 리렌더링
  const { user, isLoading } = useUserStore();
  
  return <div>{userName}</div>;
}

// authStore.ts
interface AuthState {
  isAuthenticated: boolean;
  token: string | null;
}

interface AuthActions {
  login: (token: string) => void;
  logout: () => void;
}

type AuthStore = AuthState & AuthActions;

export const useAuthStore = create<AuthStore>()((set) => ({
  isAuthenticated: false,
  token: null,
  login: (token) => set({ isAuthenticated: true, token }),
  logout: () => set({ isAuthenticated: false, token: null }),
}));

// 컴포넌트에서 여러 스토어 사용
export default function Dashboard() {
  const user = useUserStore(selectUser);
  const isAuthenticated = useAuthStore((state) => state.isAuthenticated);
  const logout = useAuthStore((state) => state.logout);
  
  // 타입이 모두 안전하게 추론됨!
  const handleLogout = () => {
    logout();
    useUserStore.getState().clearUser();
  };
  
  return <div>...</div>;
}

• State와 Actions를 명확히 분리했나요?
• 제네릭 타입을 create<T>()() 형태로 제대로 사용했나요?
• 비동기 액션에서 에러 핸들링이 타입 안전하게 되어있나요?
• Optional 값(user?.name)을 안전하게 처리했나요?
• Partial 타입을 활용해서 업데이트 함수를 만들었나요?
• 셀렉터 함수의 반환 타입이 명확하게 추론되나요?

• "Type instantiation is excessively deep"
  → 미들웨어 체이닝이 너무 깊을 때 발생해요. create<T>()() 패턴 사용하세요.
• "Property does not exist on type"
  → 스토어 타입 정의에서 해당 속성을 빠뜨렸을 거예요. State 인터페이스를 다시 확인하세요.
• "Cannot invoke an object which is possibly undefined"
  → Optional chaining(?.)을 사용하거나 null 체크를 추가하세요.

'use client';

import { useUserStore } from '@/stores/userStore';

export default function UserProfile() {
  const { name, email, updateUser } = useUserStore();

  const handleUpdate = () => {
    updateUser({ name: '홍길동' });
  };

  return (
    <div>
      <h2>{name}</h2>
      <p>{email}</p>
      <button onClick={handleUpdate}>이름 변경</button>
    </div>
  );
}

'use client';

import { useUserStore } from '@/stores/userStore';

// ❌ 나쁜 예 - 전체 스토어 구독
export function BadExample() {
  const store = useUserStore();
  // name만 써도 모든 상태 변경에 리렌더링됨
  return <div>{store.name}</div>;
}

// ✅ 좋은 예 - 필요한 부분만 구독
export function GoodExample() {
  const name = useUserStore((state) => state.name);
  // name이 변경될 때만 리렌더링
  return <div>{name}</div>;
}

// ✅ 여러 값이 필요할 때
export function MultipleValues() {
  const { name, email } = useUserStore((state) => ({
    name: state.name,
    email: state.email,
  }));
  
  return (
    <div>
      <p>{name}</p>
      <p>{email}</p>
    </div>
  );
}

// app/page.tsx (서버 컴포넌트)
import { UserProfileClient } from './UserProfileClient';

export default async function Page() {
  // 서버에서 데이터 페치
  const initialData = await fetchUserData();
  
  return (
    <div>
      <h1>마이 페이지</h1>
      {/* 클라이언트 컴포넌트에 초기값 전달 */}
      <UserProfileClient initialData={initialData} />
    </div>
  );
}

// app/UserProfileClient.tsx (클라이언트 컴포넌트)
'use client';

import { useEffect } from 'react';
import { useUserStore } from '@/stores/userStore';

export function UserProfileClient({ initialData }: Props) {
  const { name, updateUser } = useUserStore();
  
  // 서버 데이터로 스토어 초기화
  useEffect(() => {
    if (initialData) {
      updateUser(initialData);
    }
  }, [initialData, updateUser]);
  
  return <div>{name}</div>;
}

Next.js의 App Router는 페이지 이동 시에도 클라이언트 상태를 유지해요. 근데 가끔 이게 문제가 될 수 있거든요. 예를 들어 로그아웃 후 다른 사용자가 로그인했을 때 이전 사용자 데이터가 남아있을 수 있어요. 그래서 적절한 시점에 스토어를 초기화해줘야 해요.

// stores/userStore.ts
import { create } from 'zustand';

interface UserStore {
  name: string;
  email: string;
  updateUser: (user: Partial<UserStore>) => void;
  resetStore: () => void; // 초기화 함수 추가
}

const initialState = {
  name: '',
  email: '',
};

export const useUserStore = create<UserStore>((set) => ({
  ...initialState,
  updateUser: (user) => set((state) => ({ ...state, ...user })),
  resetStore: () => set(initialState), // 초기 상태로 리셋
}));

// app/logout/page.tsx
'use client';

import { useEffect } from 'react';
import { useRouter } from 'next/navigation';
import { useUserStore } from '@/stores/userStore';

export default function LogoutPage() {
  const router = useRouter();
  const resetStore = useUserStore((state) => state.resetStore);
  
  useEffect(() => {
    // 로그아웃 시 스토어 초기화
    resetStore();
    router.push('/login');
  }, [resetStore, router]);
  
  return <div>로그아웃 중...</div>;
}

// stores/cartStore.ts
import { create } from 'zustand';
import { persist } from 'zustand/middleware';

interface CartItem {
  id: string;
  name: string;
  price: number;
  quantity: number;
}

interface CartStore {
  items: CartItem[];
  addItem: (item: CartItem) => void;
  removeItem: (id: string) => void;
  getTotalPrice: () => number;
}

export const useCartStore = create<CartStore>()(
  persist(
    (set, get) => ({
      items: [],
      addItem: (item) => set((state) => ({
        items: [...state.items, item],
      })),
      removeItem: (id) => set((state) => ({
        items: state.items.filter((item) => item.id !== id),
      })),
      getTotalPrice: () => {
        const { items } = get();
        return items.reduce((sum, item) => sum + item.price * item.quantity, 0);
      },
    }),
    { name: 'cart-storage' } // localStorage에 자동 저장
  )
);

// app/products/[id]/AddToCartButton.tsx
'use client';

import { useCartStore } from '@/stores/cartStore';
import { useRouter } from 'next/navigation';

export function AddToCartButton({ product }: Props) {
  const addItem = useCartStore((state) => state.addItem);
  const router = useRouter();
  
  const handleAddToCart = () => {
    addItem({
      id: product.id,
      name: product.name,
      price: product.price,
      quantity: 1,
    });
    
    // 장바구니 페이지로 이동
    router.push('/cart');
  };
  
  return (
    <button onClick={handleAddToCart}>
      장바구니 담기
    </button>
  );
}

// app/cart/CartSummary.tsx
'use client';

import { useCartStore } from '@/stores/cartStore';

export function CartSummary() {
  const items = useCartStore((state) => state.items);
  const getTotalPrice = useCartStore((state) => state.getTotalPrice);
  const removeItem = useCartStore((state) => state.removeItem);
  
  return (
    <div>
      {items.map((item) => (
        <div key={item.id}>
          <h3>{item.name}</h3>
          <p>{item.price}원 x {item.quantity}</p>
          <button onClick={() => removeItem(item.id)}>
            삭제
          </button>
        </div>
      ))}
      <p>총 금액: {getTotalPrice()}원</p>
    </div>
  );
}

• Warning: Text content did not match
• Hydration failed because the initial UI does not match
• There was an error while hydrating

이런 메시지들 보신 적 있으시죠? 이제 완전히 해결해드릴게요!

'use client';

import { useState, useEffect } from 'react';
import { useUserStore } from '@/store/userStore';

export default function UserProfile() {
  const [isClient, setIsClient] = useState(false);
  const user = useUserStore((state) => state.user);

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

  // 서버에서는 로딩 상태 표시
  if (!isClient) {
    return <div>Loading...</div>;
  }

  // 클라이언트에서만 실제 데이터 렌더링
  return (
    <div>
      <h1>환영합니다, {user?.name}님!</h1>
      <p>{user?.email}</p>
    </div>
  );
}

import { create } from 'zustand';
import { persist, createJSONStorage } from 'zustand/middleware';

interface CartState {
  items: CartItem[];
  addItem: (item: CartItem) => void;
}

export const useCartStore = create<CartState>()(
  persist(
    (set) => ({
      items: [],
      addItem: (item) => 
        set((state) => ({ 
          items: [...state.items, item] 
        })),
    }),
    {
      name: 'cart-storage',
      storage: createJSONStorage(() => {
        // 서버 환경에서는 더미 스토리지 반환
        if (typeof window === 'undefined') {
          return {
            getItem: () => null,
            setItem: () => {},
            removeItem: () => {},
          };
        }
        return localStorage;
      }),
      // SSR 때 rehydration 건너뛰기
      skipHydration: true,
    }
  )
);

'use client';

import { useEffect } from 'react';
import { useCartStore } from '@/store/cartStore';

export default function CartProvider({ 
  children 
}: { 
  children: React.ReactNode 
}) {
  useEffect(() => {
    // 클라이언트에서만 스토어 rehydrate
    useCartStore.persist.rehydrate();
  }, []);

  return <>{children}</>;
}

import dynamic from 'next/dynamic';

// SSR 비활성화된 컴포넌트 import
const UserProfile = dynamic(
  () => import('@/components/UserProfile'),
  { 
    ssr: false,
    loading: () => <div>프로필 로딩중...</div>
  }
);

export default function ProfilePage() {
  return (
    <div>
      <h1>마이페이지</h1>
      <UserProfile />
    </div>
  );
}

// store/themeStore.ts
import { create } from 'zustand';
import { persist, createJSONStorage } from 'zustand/middleware';

interface ThemeState {
  theme: 'light' | 'dark';
  toggleTheme: () => void;
}

export const useThemeStore = create<ThemeState>()(
  persist(
    (set) => ({
      theme: 'light',
      toggleTheme: () => 
        set((state) => ({ 
          theme: state.theme === 'light' ? 'dark' : 'light' 
        })),
    }),
    {
      name: 'theme-storage',
      storage: createJSONStorage(() => {
        if (typeof window === 'undefined') {
          return {
            getItem: () => null,
            setItem: () => {},
            removeItem: () => {},
          };
        }
        return localStorage;
      }),
      skipHydration: true,
    }
  )
);

// components/ThemeToggle.tsx
'use client';

import { useEffect, useState } from 'react';
import { useThemeStore } from '@/store/themeStore';

export default function ThemeToggle() {
  const [mounted, setMounted] = useState(false);
  const { theme, toggleTheme } = useThemeStore();

  useEffect(() => {
    useThemeStore.persist.rehydrate();
    setMounted(true);
  }, []);

  if (!mounted) {
    return (
      <button className="theme-toggle">
        ?
      </button>
    );
  }

  return (
    <button 
      onClick={toggleTheme}
      className="theme-toggle"
    >
      {theme === 'light' ? '?' : '☀️'}
    </button>
  );
}

• ✓ 서버/클라이언트 환경 체크 완료
• ✓ useEffect로 클라이언트 상태 관리
• ✓ localStorage 사용시 SSR 안전 설정
• ✓ skipHydration과 수동 rehydrate 구현
• ✓ 초기 렌더링에서 안전한 기본값 표시

// stores/userStore.ts
import { create } from 'zustand';
import { devtools } from 'zustand/middleware';

interface User {
  id: string;
  name: string;
  email: string;
}

interface UserState {
  users: User[];
  isLoading: boolean;
  error: string | null;
  fetchUsers: () => Promise;
  addUser: (user: Omit) => Promise;
}

export const useUserStore = create()(
  devtools(
    (set, get) => ({
      users: [],
      isLoading: false,
      error: null,
      
      fetchUsers: async () => {
        set({ isLoading: true, error: null });
        try {
          const response = await fetch('/api/users');
          if (!response.ok) throw new Error('Failed to fetch');
          const data = await response.json();
          set({ users: data, isLoading: false });
        } catch (error) {
          set({ 
            error: error instanceof Error ? error.message : 'Unknown error',
            isLoading: false 
          });
        }
      },
      
      addUser: async (userData) => {
        const optimisticUser = { 
          id: `temp-${Date.now()}`, 
          ...userData 
        };
        
        // Optimistic Update
        set(state => ({ 
          users: [...state.users, optimisticUser] 
        }));
        
        try {
          const response = await fetch('/api/users', {
            method: 'POST',
            body: JSON.stringify(userData),
          });
          const newUser = await response.json();
          
          // 실제 ID로 교체
          set(state => ({
            users: state.users.map(u => 
              u.id === optimisticUser.id ? newUser : u
            )
          }));
        } catch (error) {
          // 실패시 롤백
          set(state => ({
            users: state.users.filter(u => u.id !== optimisticUser.id),
            error: error instanceof Error ? error.message : 'Failed to add user'
          }));
        }
      }
    })
  )
);

// stores/authStore.ts
import { create } from 'zustand';
import { useCartStore } from './cartStore';

interface AuthState {
  user: User | null;
  login: (credentials: LoginCredentials) => Promise;
  logout: () => void;
}

export const useAuthStore = create()((set) => ({
  user: null,
  
  login: async (credentials) => {
    const user = await loginApi(credentials);
    set({ user });
    
    // 로그인 후 카트 동기화
    useCartStore.getState().syncCart(user.id);
  },
  
  logout: () => {
    set({ user: null });
    
    // 로그아웃시 카트 초기화
    useCartStore.getState().clearCart();
  }
}));

// stores/cartStore.ts
interface CartState {
  items: CartItem[];
  syncCart: (userId: string) => Promise;
  clearCart: () => void;
}

export const useCartStore = create()((set) => ({
  items: [],
  
  syncCart: async (userId) => {
    const cartData = await fetchUserCart(userId);
    set({ items: cartData });
  },
  
  clearCart: () => set({ items: [] })
}));

• 순환 참조 피하기: A 스토어가 B를 부르고, B가 다시 A를 부르면 안돼요
• 너무 많은 의존성 금지: 스토어 간 결합도가 높아지면 유지보수 지옥이에요
• 이벤트 기반 고려: 복잡한 통신은 이벤트 버스 패턴을 쓰는 게 나아요

// ❌ 나쁜 예: 전체 스토어 구독
function UserProfile() {
  const store = useUserStore(); // 모든 변경에 리렌더링!
  return 
{store.user.name}
;
}

// ✅ 좋은 예: 필요한 것만 선택
function UserProfile() {
  const userName = useUserStore(state => state.user.name);
  return 
{userName}
;
}

// ? 최고의 예: 재사용 가능한 셀렉터
// stores/selectors.ts
export const selectUserName = (state: UserState) => state.user?.name;
export const selectActiveUsers = (state: UserState) => 
  state.users.filter(u => u.isActive);

// 컴포넌트에서 사용
function UserProfile() {
  const userName = useUserStore(selectUserName);
  const activeUsers = useUserStore(selectActiveUsers);
  
  return (
    

      
{userName}
      
활성 사용자: {activeUsers.length}명
    
  );
}

// stores/settingsStore.ts
import { create } from 'zustand';
import { persist, createJSONStorage } from 'zustand/middleware';

interface Settings {
  theme: 'light' | 'dark';
  language: string;
  notifications: boolean;
}

interface SettingsState extends Settings {
  updateSettings: (settings: Partial) => void;
  _hasHydrated: boolean;
  setHasHydrated: (state: boolean) => void;
}

export const useSettingsStore = create()(
  persist(
    (set) => ({
      theme: 'light',
      language: 'ko',
      notifications: true,
      _hasHydrated: false,
      
      updateSettings: (newSettings) => 
        set((state) => ({ ...state, ...newSettings })),
      
      setHasHydrated: (state) => {
        set({ _hasHydrated: state });
      }
    }),
    {
      name: 'settings-storage',
      storage: createJSONStorage(() => 
        typeof window !== 'undefined' ? localStorage : undefined
      ),
      onRehydrateStorage: () => (state) => {
        state?.setHasHydrated(true);
      },
      partialize: (state) => ({
        theme: state.theme,
        language: state.language,
        notifications: state.notifications
        // _hasHydrated는 저장하지 않음!
      })
    }
  )
);

// 컴포넌트에서 안전하게 사용
'use client';

import { useEffect, useState } from 'react';

function ThemeToggle() {
  const [mounted, setMounted] = useState(false);
  const { theme, updateSettings, _hasHydrated } = useSettingsStore();

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

  if (!mounted || !_hasHydrated) {
    return 
로딩중...
; // SSR에서는 기본값 표시
  }

  return (
     updateSettings({ 
      theme: theme === 'light' ? 'dark' : 'light' 
    })}>
      현재: {theme}
    
  );
}

// stores/todoStore.ts
import { create } from 'zustand';

export interface Todo {
  id: string;
  text: string;
  completed: boolean;
}

export interface TodoState {
  todos: Todo[];
  addTodo: (text: string) => void;
  toggleTodo: (id: string) => void;
  removeTodo: (id: string) => void;
}

// 스토어 로직을 함수로 분리
export const createTodoStore = () => create()((set) => ({
  todos: [],
  
  addTodo: (text) => set((state) => ({
    todos: [...state.todos, {
      id: crypto.randomUUID(),
      text,
      completed: false
    }]
  })),
  
  toggleTodo: (id) => set((state) => ({
    todos: state.todos.map(todo =>
      todo.id === id ? { ...todo, completed: !todo.completed } : todo
    )
  })),
  
  removeTodo: (id) => set((state) => ({
    todos: state.todos.filter(todo => todo.id !== id)
  }))
}));

// 실제 사용할 스토어
export const useTodoStore = createTodoStore();

// __tests__/todoStore.test.ts
import { act, renderHook } from '@testing-library/react';
import { createTodoStore } from '@/stores/todoStore';

describe('TodoStore', () => {
  it('should add todo', () => {
    const store = createTodoStore();
    const { result } = renderHook(() => store());
    
    act(() => {
      result.current.addTodo('Test todo');
    });
    
    expect(result.current.todos).toHaveLength(1);
    expect(result.current.todos[0].text).toBe('Test todo');
  });
  
  it('should toggle todo', () => {
    const store = createTodoStore();
    const { result } = renderHook(() => store());
    
    act(() => {
      result.current.addTodo('Test');
    });
    
    const todoId = result.current.todos[0].id;
    
    act(() => {
      result.current.toggleTodo(todoId);
    });
    
    expect(result.current.todos[0].completed).toBe(true);
  });
});

• 액션 이름 명확하게: updateUser보다는 user/update-profile 이렇게 쓰면 추적이 쉬워요
• store 이름 설정: devtools 옵션에 { name: 'UserStore' } 추가하면 여러 스토어 구분이 편해요
• 프로덕션에서 비활성화: enabled: process.env.NODE_ENV === 'development' 옵션 꼭 추가하세요
• Time-travel 디버깅: Redux DevTools에서 상태를 되돌리면서 버그 재현 가능해요

import { create } from 'zustand';
import { devtools } from 'zustand/middleware';

export const useProductStore = create()(
  devtools(
    (set) => ({
      products: [],
      
      addProduct: (product) => 
        set(
          (state) => ({ 
            products: [...state.products, product] 
          }),
          false, // replace 옵션
          'products/add' // 액션 이름 - DevTools에 표시됨
        ),
      
      updateProduct: (id, updates) =>
        set(
          (state) => ({
            products: state.products.map(p =>
              p.id === id ? { ...p, ...updates } : p
            )
          }),
          false,
          { type: 'products/update', id, updates } // 상세 정보 포함
        )
    }),
    { 
      name: 'ProductStore',
      enabled: process.env.NODE_ENV === 'development'
    }
  )
);