Zustand Todo 완성 실습: actions·선택 훅·persist 연결

TaskFlow는 작업을 추가·완료·삭제하는 할 일 앱입니다. 이 선택 실습에서는 여러 화면이 공유하는 상태를 관리합니다.

이번 주제: Zustand Todo 완성 실습: actions·선택 훅·persist 연결.

선택: 연재 프로젝트와 전체 자료

연재 프로젝트를 이어 만드는 분을 위한 자료입니다. 이 글의 개념과 예제만 찾으셨다면 필요한 파일과 실행 방법만 펼쳐보세요.

TaskFlow 프로젝트 적용

import { useState } from 'react';
import { useAddTask } from '../store/taskSelectors';


export default function TaskForm() {
  const [title, setTitle] = useState('');
  const addTask = useAddTask();


  const handleSubmit = (
    event: React.FormEvent<HTMLFormElement>,
  ) => {
    event.preventDefault();


    const value = title.trim();
    if (!value) return;


    addTask(value);
    setTitle('');
  };


  return (
    <form onSubmit={handleSubmit}>
      <label htmlFor="task-title">새 작업</label>
      <input
        id="task-title"
        value={title}
        onChange={(event) =>
          setTitle(event.target.value)
        }
      />
      <button type="submit">추가</button>
    </form>
  );
}

import { useTaskStore } from '../store/useTaskStore';
import { useTasks, useTaskFilter } from '../store/taskSelectors';
import TaskItem from './TaskItem';


export default function TaskList() {
  const tasks = useTasks();
  const filter = useTaskFilter();


  const preferences = useTaskStore((state) => state.preferences);
  const visibleTasks = tasks.filter((task) => {
    if (!preferences.list.showCompleted && task.completed) return false;
    if (filter === 'active') {
      return !task.completed;
    }


    if (filter === 'completed') {
      return task.completed;
    }


    return true;
  });


  if (visibleTasks.length === 0) {
    return <p>표시할 작업이 없습니다.</p>;
  }


  return (
    <ul style={{ lineHeight: preferences.list.compact ? 1.4 : 2 }}>
      {visibleTasks.map((task) => (
        <TaskItem
          key={task.id}
          task={task}
        />
      ))}
    </ul>
  );
}

import { useTaskStore } from './useTaskStore';
export const useTasks = () => useTaskStore((state) => state.tasks);
export const useTaskFilter = () => useTaskStore((state) => state.taskFilter);
export const useAddTask = () => useTaskStore((state) => state.addTask);

프로젝트 마지막 단계입니다. 누적 실습은 이 절의 프로젝트 단계 링크를 따라 진행합니다. 페이지 끝 학습 순서는 기술 주제 읽기 순서입니다.

이전 프로젝트 단계: Zustand 실무 사용 기준: store가 복잡해질 때 피할 실수의 적용 결과에서 시작합니다. 아래 체크포인트 이름은 단계 식별자이며 다운로드 파일명이나 Git 명령이 아닙니다.

아래는 여러 회차에서 확장한 TaskFlow의 최종 구성 설명입니다. 위 단독 실습은 작은 별도 App으로, 아래 코드의 대체 시작본이 아닙니다. 기존 TaskItem·App 연결 등 이전 파일을 유지하며 최종 Store와 선택 훅·TaskForm·TaskList를 합칩니다.

과정 시작 전 구조

React 과정의 시작점은 다음과 같았습니다.

TaskContext
TaskProvider
taskReducer
dispatch
useContext

이 구조는 React 기본 기능만으로 전역 상태 공유와 reducer 흐름을 이해하기에 좋습니다.

Zustand 과정 종료 구조

useTaskStore
├─ state
│  ├─ tasks
│  ├─ taskFilter
│  ├─ selectedTaskId
│  ├─ isTaskModalOpen
│  └─ preferences
├─ actions
│  ├─ addTask
│  ├─ toggleTask
│  ├─ deleteTask
│  ├─ selectTask
│  ├─ openTaskModal
│  ├─ closeTaskModal
│  ├─ setFilter
│  └─ toggleCompact
├─ selectors
├─ persist
├─ devtools
└─ migration

최종 Store

현재 TaskFlow의 tasks는 학습용 로컬 데이터입니다. 실제 API 기반 프로젝트에서는 서버 원본 tasks와 mutation을 TanStack Query로 옮기고 Zustand에는 UI 상태를 남기는 구조가 적합합니다.

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


export type Task = {
  id: string;
  title: string;
  completed: boolean;
};


export type TaskFilter =
  | 'all'
  | 'active'
  | 'completed';


type Preferences = {
  compact: boolean;
};


type TaskStore = {
  tasks: Task[];
  taskFilter: TaskFilter;
  selectedTaskId: string | null;
  isTaskModalOpen: boolean;
  preferences: Preferences;


  addTask: (title: string) => void;
  toggleTask: (id: string) => void;
  deleteTask: (id: string) => void;
  selectTask: (id: string | null) => void;
  openTaskModal: () => void;
  closeTaskModal: () => void;
  setFilter: (filter: TaskFilter) => void;
  toggleCompact: () => void;
};


type PersistedTaskStore = {
  taskFilter: TaskFilter;
  selectedTaskId: string | null;
  preferences: Preferences;
};


export const useTaskStore =
  create<TaskStore>()(
    devtools(
      persist(
        (set) => ({
          tasks: [],
          taskFilter: 'all',
          selectedTaskId: null,
          isTaskModalOpen: false,
          preferences: {
            compact: false,
          },


          addTask: (title) =>
            set(
              (state) => ({
                tasks: [
                  ...state.tasks,
                  {
                    id: crypto.randomUUID(),
                    title,
                    completed: false,
                  },
                ],
              }),
              false,
              'task/add',
            ),


          toggleTask: (id) =>
            set(
              (state) => ({
                tasks: state.tasks.map(
                  (task) =>
                    task.id === id
                      ? {
                          ...task,
                          completed:
                            !task.completed,
                        }
                      : task,
                ),
              }),
              false,
              'task/toggle',
            ),


          deleteTask: (id) =>
            set(
              (state) => ({
                tasks: state.tasks.filter(
                  (task) =>
                    task.id !== id,
                ),
              }),
              false,
              'task/delete',
            ),


          selectTask: (selectedTaskId) =>
            set(
              { selectedTaskId },
              false,
              'task/select',
            ),


          openTaskModal: () =>
            set(
              { isTaskModalOpen: true },
              false,
              'task/modal-open',
            ),


          closeTaskModal: () =>
            set(
              { isTaskModalOpen: false },
              false,
              'task/modal-close',
            ),


          setFilter: (taskFilter) =>
            set(
              { taskFilter },
              false,
              'task/filter',
            ),


          toggleCompact: () =>
            set(
              (state) => ({
                preferences: {
                  ...state.preferences,
                  compact:
                    !state.preferences.compact,
                },
              }),
              false,
              'ui/toggle-compact',
            ),
        }),
        {
          name: 'taskflow-ui',
          version: 2,


          partialize: (state) => ({
            taskFilter: state.taskFilter,
            selectedTaskId:
              state.selectedTaskId,
            preferences:
              state.preferences,
          }),


          migrate: (
            persistedState,
            version,
          ) => {
            const previous =
              persistedState as
                Partial<
                  PersistedTaskStore & {
                    filter: TaskFilter;
                  }
                >;


            if (version < 2) {
              return {
                taskFilter:
                  previous.filter ??
                  previous.taskFilter ??
                  'all',
                selectedTaskId:
                  previous.selectedTaskId ??
                  null,
                preferences:
                  previous.preferences ?? {
                    compact: false,
                  },
              };
            }


            return persistedState;
          },
        },
      ),
      {
        name: 'TaskFlowStore',
      },
    ),
  );

선택 훅

반복되는 의미 있는 selector만 작은 훅으로 정리할 수 있습니다.

export const useTasks = () =>
  useTaskStore(
    (state) => state.tasks,
  );


export const useTaskFilter = () =>
  useTaskStore(
    (state) => state.taskFilter,
  );


export const useSelectedTaskId = () =>
  useTaskStore(
    (state) => state.selectedTaskId,
  );

모든 selector를 감싸지 않고 반복되거나 의미 있는 구독 단위만 추상화합니다.

TaskList

import { useTaskStore } from '../store/useTaskStore';
import TaskItem from './TaskItem';


export default function TaskList() {
  const tasks = useTaskStore(
    (state) => state.tasks,
  );
  const taskFilter = useTaskStore(
    (state) => state.taskFilter,
  );


  const visibleTasks = tasks.filter(
    (task) => {
      if (taskFilter === 'active') {
        return !task.completed;
      }


      if (taskFilter === 'completed') {
        return task.completed;
      }


      return true;
    },
  );


  if (visibleTasks.length === 0) {
    return <p>표시할 작업이 없습니다.</p>;
  }


  return (
    <ul>
      {visibleTasks.map((task) => (
        <TaskItem
          key={task.id}
          task={task}
        />
      ))}
    </ul>
  );
}

TaskForm

form 입력값은 전역 공유할 필요가 없으므로 로컬 state로 유지합니다.

import { useState } from 'react';
import { useTaskStore } from '../store/useTaskStore';


export default function TaskForm() {
  const [title, setTitle] = useState('');
  const addTask = useTaskStore(
    (state) => state.addTask,
  );


  const handleSubmit = (
    event: React.FormEvent<HTMLFormElement>,
  ) => {
    event.preventDefault();


    const value = title.trim();
    if (!value) return;


    addTask(value);
    setTitle('');
  };


  return (
    <form onSubmit={handleSubmit}>
      <label htmlFor="task-title">
        새 작업
      </label>
      <input
        id="task-title"
        value={title}
        onChange={(event) =>
          setTitle(event.target.value)
        }
      />
      <button type="submit">
        추가
      </button>
    </form>
  );
}

최종 persist 기준

저장:

taskFilter
selectedTaskId
preferences

저장하지 않음:

isTaskModalOpen
form input
임시 loading / error
서버 원본 데이터

현재 로컬 Todo 학습에서는 tasks를 메모리 state로 유지합니다. 브라우저 로컬 Todo가 목적이라면 tasks를 persist할 수도 있지만, API 기반 TaskFlow로 확장할 계획이라면 서버 원본 tasks를 Zustand에 저장하지 않습니다.

reducer + Context와 비교

Before

TaskProvider
taskReducer
dispatch
useContext
Provider 연결
action 객체

After

useTaskStore
행동 중심 action
필요한 state selector 구독
Provider 불필요
persist / devtools 확장
migration 가능

Zustand가 항상 더 낫다는 뜻은 아닙니다. React 기본 상태 공유 원리를 이해한 뒤 앱의 상태 규모와 변경 패턴에 따라 선택하는 것이 중요합니다.

TanStack Query와 함께 사용할 때

실제 서비스 TaskFlow가 API를 사용한다면 역할을 다음처럼 나눕니다.

tasks 조회
작업 추가 API
작업 수정 API
작업 삭제 API
캐시 / refetch
→ TanStack Query


selectedTaskId
taskFilter
modal
UI preferences
→ Zustand

최종 실행 확인

npm run dev
npm run build

다음 시나리오를 확인합니다.

1. 작업 추가
2. 작업 완료/취소
3. 작업 삭제
4. filter 변경
5. 선택 상태 변경
6. modal 열기/닫기
7. compact 설정 변경
8. 새로고침
9. persist 대상만 복원
10. Redux DevTools에서 action 이름 확인

Zustand 과정 최종 체크리스트

• store와 state 구조를 설계할 수 있습니다.
• 행동 중심 action을 만들 수 있습니다.
• selector로 필요한 값만 구독할 수 있습니다.
• 객체·배열 참조와 리렌더링 관계를 이해했습니다.
• persist 대상을 최소화할 수 있습니다.
• combine과 immer 도입 기준을 설명할 수 있습니다.
• subscribe cleanup을 적용할 수 있습니다.
• devtools에서 상태 변경을 추적할 수 있습니다.
• persist migration을 작성할 수 있습니다.
• 서버 상태와 Zustand 역할을 구분할 수 있습니다.

완료 체크포인트

zustand-step-15-final

이 체크포인트가 Zustand 과정의 최종 TaskFlow 상태입니다.