Zustand를 활용한 상태 관리

useState는 한 컴포넌트의 상태를, Context는 한 트리 안에서 값을 전달하는 방법을 줍니다. 그런데 서로 멀리 떨어진 여러 컴포넌트가 같은 상태를 읽고 바꿔야 하면, 상태를 아주 위쪽 컴포넌트로 올리고 Provider와 props로 내려보내는 코드가 길어집니다. 이럴 때 컴포넌트 바깥에 상태를 두고 필요한 컴포넌트가 직접 구독하게 하는 상태 관리 라이브러리를 씁니다.

Zustand는 그런 라이브러리 가운데 API가 작은 편으로, 상태와 그것을 바꾸는 함수를 하나의 스토어(store)로 만들고 훅으로 꺼내 씁니다. 이 글은 2026년 10월 현재 최신인 Zustand 5로 스토어에 타입을 붙이고, 선택자(selector)로 필요한 값만 구독한 뒤, 비동기 액션과 저장 미들웨어를 다룹니다.

스토어 만들기

먼저 프로젝트에 Zustand를 설치합니다. Zustand는 타입 정의를 패키지 안에 함께 배포하므로 @types 패키지를 따로 설치하지 않아도 됩니다.

npm install zustand

스토어는 JSX가 없으므로 .ts 파일로 만듭니다. 다음은 카운터의 상태와 그것을 바꾸는 액션을 함께 담은 스토어입니다.

import { create } from "zustand";

interface CounterState {
  count: number;
  increment: () => void;
  decrement: () => void;
  reset: () => void;
  incrementByAmount: (amount: number) => void;
}

export const useCounterStore = create<CounterState>()((set) => ({
  count: 0,
  increment: () => set((state) => ({ count: state.count + 1 })),
  decrement: () => set((state) => ({ count: state.count - 1 })),
  reset: () => set({ count: 0 }),
  incrementByAmount: (amount) => set((state) => ({ count: state.count + amount })),
}));

create<CounterState>()(...)에서 타입 인수 뒤의 빈 괄호는 실수가 아닙니다. 스토어를 만드는 함수는 상태를 돌려주면서 동시에 set과 get으로 그 상태를 받기도 해서, 타입스크립트가 초기값만으로 상태의 타입을 추론하지 못합니다. 그래서 Zustand의 TypeScript 안내는 상태의 타입을 먼저 적고 한 번 더 호출하는 이 커링 형태를 권하며, 미들웨어를 쓸 때도 같은 형태가 필요합니다.

set은 넘긴 객체를 현재 상태와 합쳐 새 상태를 만듭니다. 이때 합치는 것은 최상위 속성 한 단계뿐이어서, set({ count: 0 })은 count만 바꾸고 액션 함수들은 그대로 둡니다. 중첩된 객체의 일부만 바꾸려면 전개 구문으로 안쪽 객체를 직접 복사해야 하며, Zustand가 상태 객체를 직접 고치는 코드를 막아 주지는 않습니다.

더 깊이: 빈 괄호가 필요한 두 가지 이유

Zustand의 고급 TypeScript 안내는 상태의 타입을 초기값에서 추론하지 못하는 이유를, 상태의 타입 T가 불공변(invariant)이기 때문이라고 설명합니다. 스토어를 만드는 함수는 상태를 돌려주므로 T가 출력 자리에 있고, 동시에 매개변수로 받은 get이 T를 돌려주므로 입력 자리에도 있습니다. 다시 말해 T가 공변(covariant) 자리와 반공변(contravariant) 자리에 함께 있는 것이며, 이때 컴파일러는 T를 어디서 정할지 알 수 없어 unknown으로 추론합니다.

그렇다면 create<CounterState>(...)처럼 한 번에 적으면 될 것 같지만, create에는 미들웨어가 더하는 타입을 위한 타입 매개변수가 더 있습니다. 타입스크립트에서는 타입 인수를 일부만 적으면 나머지 타입 매개변수를 인수에서 추론하지 않으므로, 안내는 이 커링 형태를 TypeScript 저장소의 이슈 #10571에 대한 우회책이라고 부릅니다. 첫 호출 create<CounterState>()는 실행 중에는 아무 일도 하지 않고 상태의 타입만 정하며, 그것이 돌려준 함수가 나머지 타입을 인수에서 추론합니다. 안내는 이 타입이 완전히 건전하지는 않다는 점도 인정하는데, 스토어를 만드는 도중에 get()을 동기적으로 부르면 검사는 통과하지만 초기 상태가 아직 없어 실행 중에는 undefined를 받습니다.

선택자로 구독하기

컴포넌트는 스토어 훅에 선택자 함수를 넘겨, 상태 가운데 필요한 값만 꺼냅니다. 선택자의 결과가 바뀔 때만 그 컴포넌트가 다시 렌더링됩니다.

import { useCounterStore } from "../store/counterStore";

export default function ZustandCounter() {
  const count = useCounterStore((state) => state.count);
  const increment = useCounterStore((state) => state.increment);
  const decrement = useCounterStore((state) => state.decrement);
  const reset = useCounterStore((state) => state.reset);
  const incrementByAmount = useCounterStore((state) => state.incrementByAmount);

  return (
    <div>
      <p>Count: {count}</p>
      <button onClick={increment}>Increment</button>
      <button onClick={decrement}>Decrement</button>
      <button onClick={reset}>Reset</button>
      <button onClick={() => incrementByAmount(5)}>Increment by 5</button>
    </div>
  );
}

import { useCounterStore } from "../store/counterStore";

export default function ZustandCountDisplay() {
  const count = useCounterStore((state) => state.count);
  return <h3>Current Count (from another component): {count}</h3>;
}

import ZustandCounter from "./components/ZustandCounter";
import ZustandCountDisplay from "./components/ZustandCountDisplay";

export default function App() {
  return (
    <div>
      <ZustandCounter />
      <ZustandCountDisplay />
    </div>
  );
}

두 컴포넌트는 처음에 모두 0을 보여 줍니다. Increment by 5를 누르면 둘 다 5, Decrement를 누르면 둘 다 4가 되고, Reset 뒤에는 둘 다 0입니다. 13장 2절의 useCounter는 부르는 컴포넌트마다 상태를 따로 만들었지만, 여기서는 두 컴포넌트가 같은 스토어의 count 하나를 읽습니다. 이 decrement는 0 아래를 막지 않으므로 Reset 뒤 Decrement를 누르면 둘 다 -1이 됩니다.

그림처럼 액션의 set이 스토어를 바꾸면, 같은 count를 선택한 두 구독자가 각각 새 값을 받습니다. 두 컴포넌트가 차례로 실행되는 것이 아니라 같은 값을 따로 구독하는 것이며, 선택자는 스토어의 변경 가운데 어떤 것에 반응할지를 정할 뿐 부모나 Context 때문에 생기는 렌더링까지 막지는 않습니다. 선택자의 결과가 바뀌었는지는 기본으로 Object.is로 비교합니다.

그래서 선택자가 여러 값을 담은 새 객체를 돌려주면 문제가 됩니다. 매번 새 객체가 만들어져 결과가 늘 바뀐 것으로 보이기 때문이며, Zustand 5에서는 이것이 Maximum update depth exceeded 오류로 이어질 수 있습니다. 여러 값을 한 번에 꺼낼 때는 zustand/react/shallow의 useShallow로 선택자를 감싸, 안의 값이 얕게 같으면 같은 결과로 보게 합니다.

import { useShallow } from "zustand/react/shallow";

const { increment, decrement } = useCounterStore(
  useShallow((state) => ({ increment: state.increment, decrement: state.decrement })),
);

비동기 액션

액션은 보통의 함수이므로 async 함수로 만들 수 있고, 작업의 진행에 따라 set을 여러 번 부를 수 있습니다. 다음 스토어는 앞 글들의 사용자 불러오기를 스토어로 옮긴 것입니다.

import { create } from "zustand";

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

export function fakeFetchUser(userId: number): Promise<User> {
  return new Promise((resolve, reject) => {
    setTimeout(() => {
      if (userId === 1) {
        resolve({ id: 1, name: "Alice", email: "[email protected]" });
      } else {
        reject(new Error("User not found!"));
      }
    }, 1500);
  });
}

interface UserState {
  user: User | null;
  loading: boolean;
  error: string | null;
  fetchUser: (userId: number) => Promise<void>;
}

export const useUserStore = create<UserState>()((set) => ({
  user: null,
  loading: false,
  error: null,
  fetchUser: async (userId) => {
    set({ loading: true, error: null });
    try {
      const user = await fakeFetchUser(userId);
      set({ user, loading: false });
    } catch (err) {
      set({ user: null, loading: false, error: err instanceof Error ? err.message : "Unknown error" });
    }
  },
}));

import { useUserStore } from "../store/userStore";

export default function ZustandUserProfile() {
  const { user, loading, error, fetchUser } = useUserStore();

  return (
    <div>
      <button onClick={() => fetchUser(1)} disabled={loading}>
        Fetch Alice (ID 1)
      </button>
      <button onClick={() => fetchUser(99)} disabled={loading}>
        Fetch Non-Existent User (ID 99)
      </button>
      {error && <p>Error: {error}</p>}
      {user ? <p>{user.name} ({user.email})</p> : !loading && !error && <p>Click a button to fetch user data.</p>}
    </div>
  );
}

처음에는 Click a button to fetch user data.가 보이고, ID 1을 누르면 1.5초 뒤 Alice ([email protected])가 보입니다. 이어서 ID 99를 누르면 불러오는 동안에는 Alice가 남아 있다가, 실패가 도착하면 user가 null이 되고 Error: User not found!가 보입니다. 선택자 없이 useUserStore()를 부르면 상태 전체를 구독하므로, 이 컴포넌트는 스토어의 어떤 값이 바뀌어도 다시 렌더링됩니다.

버튼은 불러오는 동안 비활성화되지만, 다른 코드가 fetchUser를 직접 부르는 것까지 막지는 못합니다. 이 액션에는 요청을 구별하는 장치가 없으므로, 두 요청이 겹치면 나중에 끝난 요청의 결과가 먼저 시작했든 나중에 시작했든 상태를 덮습니다. 또 이 스토어는 받은 사용자를 담아 둘 뿐이어서, 서버 데이터를 캐시하고 다시 검증하는 일은 TanStack Query 같은 서버 상태 도구에 맡기는 편이 낫습니다.

최신 요청만 반영하기

겹친 요청을 다루는 방법 가운데 하나는 요청마다 번호를 붙이고, 결과가 도착했을 때 그 번호가 가장 최근의 것인지 확인하는 것입니다. 13장 2절에서 본 ignore 플래그와 같은 생각을 스토어에 적용한 것입니다.

그림의 왼쪽은 요청을 시작할 때 번호를 기억해 두고 현재 번호의 결과만 반영하는 흐름이고, 오른쪽은 다음 절에서 볼 저장값의 복원입니다. 두 흐름은 서로 다른 수명을 가지므로 하나의 단계로 묶지 않습니다. 다음 스토어가 왼쪽 흐름을 구현합니다.

import { create } from "zustand";
import { fakeFetchUser } from "./userStore";
import type { User } from "./userStore";

interface LatestUserState {
  user: User | null;
  loading: boolean;
  error: string | null;
  fetchUser: (userId: number) => Promise<void>;
}

export const useLatestUserStore = create<LatestUserState>()((set) => {
  let version = 0;
  return {
    user: null,
    loading: false,
    error: null,
    fetchUser: async (userId) => {
      const mine = ++version;
      set({ user: null, loading: true, error: null });
      try {
        const user = await fakeFetchUser(userId);
        if (mine !== version) return;
        set({ user, loading: false });
      } catch (err) {
        if (mine !== version) return;
        set({ user: null, loading: false, error: err instanceof Error ? err.message : "Unknown error" });
      }
    },
  };
});

version은 스토어를 만드는 함수 안의 지역 변수여서 바깥에서 바꿀 수 없고, fetchUser를 부를 때마다 1씩 늘어납니다. 결과가 도착했을 때 자기 번호 mine이 현재 version과 다르면 그사이에 새 요청이 시작된 것이므로 아무것도 하지 않습니다. 성공뿐 아니라 실패와 loading을 끄는 처리까지 번호를 확인해야, 이전 요청이 먼저 끝나면서 새 요청의 loading을 꺼 버리는 일이 없습니다.

이 스토어는 새 요청을 시작할 때 이전 사용자를 지우도록 정했으므로, 불러오는 동안 이전 사용자를 남기던 userStore와 화면이 다릅니다. 또 이전 요청의 타이머를 취소하지는 않으므로 이전 요청도 끝까지 실행되며, 그 결과를 상태에 쓰지 않을 뿐입니다. 실제 HTTP 요청이라면 AbortController로 요청 자체를 취소하는 방법을 함께 씁니다.

미들웨어로 저장하고 복원하기

Zustand는 스토어를 만드는 함수를 감싸 기능을 더하는 미들웨어를 제공합니다. devtools는 상태의 변화를 Redux DevTools 브라우저 확장에서 볼 수 있게 하고, persist는 상태를 브라우저 저장소에 저장했다가 다시 불러옵니다.

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

interface SettingsState {
  darkMode: boolean;
  fontSize: number;
  toggleDarkMode: () => void;
  setFontSize: (size: number) => void;
}

export const useSettingsStore = create<SettingsState>()(
  devtools(
    persist(
      (set) => ({
        darkMode: false,
        fontSize: 16,
        toggleDarkMode: () => set((state) => ({ darkMode: !state.darkMode })),
        setFontSize: (size) => set({ fontSize: size }),
      }),
      {
        name: "user-settings-storage",
        // partialize: (state) => ({ darkMode: state.darkMode, fontSize: state.fontSize }),
        // storage: createJSONStorage(() => sessionStorage),
      },
    ),
  ),
);

persist는 name을 키로 상태를 JSON으로 바꾸어 저장하며, 저장소를 정하지 않으면 localStorage를 씁니다. localStorage는 동기 저장소이므로 스토어가 만들어질 때 저장값의 복원도 함께 끝나고, 첫 렌더링부터 복원된 값을 볼 수 있습니다. 반면 React Native의 AsyncStorage 같은 비동기 저장소는 복원이 나중에 끝나므로, 필요하면 onRehydrateStorage 옵션이나 persist.hasHydrated()로 복원이 끝났는지 확인해 기다리는 화면을 따로 만듭니다.

주석으로 둔 두 옵션은 필요할 때 켭니다. storage를 바꾸려면 zustand/middleware에서 createJSONStorage도 가져와야 하고, partialize는 저장할 필드를 고릅니다. 선택자는 컴포넌트가 읽는 값을 정할 뿐이어서, 토큰이나 진행 중인 요청 같은 값을 저장하지 않으려면 partialize로 저장할 필드를 직접 정해야 합니다.

복원할 때 persist는 저장값을 현재 상태에 얕게 합치므로, 중첩된 객체는 저장값의 것으로 통째로 바뀝니다. 또 저장값의 모양을 검사하지 않으므로, 누군가 저장소의 값을 "fontSize": "large"처럼 바꾸어 두면 number로 선언한 필드에 문자열이 들어옵니다. 저장하는 모양이 바뀔 때는 version과 migrate 옵션으로 옛 값을 옮기고, 값 자체의 검증은 앱에서 따로 합니다.

정리

• Zustand 스토어는 create<State>()(...)의 커링 형태로 상태와 액션의 타입을 먼저 적어 만들며, set은 최상위 속성 한 단계만 합칩니다.
• 컴포넌트는 선택자로 필요한 값만 구독하고, 결과는 Object.is로 비교되므로 여러 값을 객체로 꺼낼 때는 useShallow로 감쌉니다.
• 같은 스토어를 구독하는 컴포넌트는 같은 값을 보며, 선택자 없이 부르면 상태 전체를 구독합니다.
• 겹칠 수 있는 비동기 액션은 요청 번호로 최신 요청인지 확인하고, 성공과 실패, loading의 해제 모두에 그 확인을 적용합니다.
• persist는 기본으로 localStorage에 저장하고 스토어를 만들 때 동기로 복원하며, 저장 범위는 partialize로, 모양의 변경은 version과 migrate로 다룹니다.

연습 문제

1. 두 컴포넌트의 값

ZustandCounter에서 Increment를 한 번, Increment by 5를 한 번, Decrement를 두 번 눌렀습니다. 두 컴포넌트가 보여 주는 값은 얼마인가요? 그 뒤 useUserStore의 user가 바뀌면 count도 바뀌나요?

2. 겹친 요청

다른 코드가 ID 99의 요청 A를 시작하고 곧바로 ID 1의 요청 B를 시작했으며, B의 성공이 먼저, A의 실패가 나중에 도착했다고 가정합니다. useUserStore와 useLatestUserStore의 마지막 user, error, loading은 각각 무엇인가요?

3. 새로고침 뒤의 값

설정 스토어에서 toggleDarkMode()를 한 번, setFontSize(20)을 한 번 실행한 뒤 페이지를 새로고침했습니다. 저장과 복원이 정상적으로 이루어졌다면 설정과 카운터의 count는 각각 무엇인가요?

다음 글 테스팅과 성능 최적화에서는 React Testing Library로 사용자의 동작과 비동기 화면을 검사하고, memo, useCallback, useMemo를 측정한 뒤에 적용하는 방법을 다룹니다.