Zustand persist 마이그레이션 기준: 저장된 상태 구조가 바뀔 때

중간부터 시작하는 전체 실습 파일

기존 React Context TaskFlow의 작업 목록·추가·완료·삭제 화면을 이어서 확장합니다.

• 시작본 다운로드 — zustand-step-12-subscribe-devtools.zip
• 완료본 다운로드 — zustand-step-13-migration.zip

이 글의 시작본은 직전 프로젝트 단계 완료본 전체입니다. 이미 직전 단계를 마쳤다면 그 폴더를 이어 쓰셔도 됩니다. Node.js 24.x와 npm을 사용하며 패키지 버전은 package-lock.json에 고정했습니다.

시작본에서 직접 바꾸기

시작본을 실행한 뒤 아래 변경 파일을 순서대로 수정합니다. 완료본의 같은 경로 파일에는 import와 입력 타입을 포함한 전체 코드가 있습니다.

1. docs/migration-fixture.md — 이전 단계에 없던 파일을 만듭니다.
2. src/components/TaskFilter.tsx — 기존 파일의 같은 위치를 갱신합니다.
3. src/components/TaskFilterWatcher.tsx — 기존 파일의 같은 위치를 갱신합니다.
4. src/components/TaskList.tsx — 기존 파일의 같은 위치를 갱신합니다.
5. src/store/migrateUi.ts — 이전 단계에 없던 파일을 만듭니다.
6. src/store/useTaskStore.ts — 기존 파일의 같은 위치를 갱신합니다.

변경 이유와 결과: filter를 taskFilter로 바꾸고 모든 읽기·호출부·Watcher를 함께 갱신합니다. 저장 version 2와 안전한 migrate를 적용해 이전 filter/selectedTaskId/preferences를 보존합니다. docs/migration-fixture.md는 개인 값과 분리된 테스트 절차입니다.

완료본의 docs/changes.patch에서 시작·완료 차이를, docs/current-step.md에서 파일별 적용 위치를 확인할 수 있습니다. 아래 전체 파일을 같은 경로에 반영한 다음 실행하세요.

docs/migration-fixture.md 전체 파일

# v0 → v2 테스트

개인 저장소와 분리한 브라우저 프로필의 taskflow-ui 키에만 다음 JSON을 저장하고 새로고침합니다.
```json
{"state":{"filter":"completed","selectedTaskId":"task-1","preferences":{"list":{"compact":true,"showCompleted":false}}},"version":0}
```
기대: taskFilter completed·선택 task-1·compact true·showCompleted false 보존. 모달은 닫힘, tasks는 메모리 초기값입니다. 알 수 없는 필터 값은 all로 정규화합니다.

src/components/TaskFilter.tsx 전체 파일

import {
  useTaskStore,
  type TaskFilter as TaskFilterValue,
} from '../store/useTaskStore';


const options: TaskFilterValue[] = [
  'all',
  'active',
  'completed',
];


export default function TaskFilter() {
  console.count('TaskFilter render');
  const filter = useTaskStore((state) => state.taskFilter);
  const setFilter = useTaskStore((state) => state.setFilter);


  return (
    <section>
      <h2>필터</h2>
      <select
        value={filter}
        onChange={(event) =>
          setFilter(event.target.value as TaskFilterValue)
        }
      >
        {options.map((option) => (
          <option key={option} value={option}>
            {option}
          </option>
        ))}
      </select>
    </section>
  );
}

src/components/TaskFilterWatcher.tsx 전체 파일

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


export default function TaskFilterWatcher() {
  useEffect(() => {
    const unsubscribe =
      useTaskStore.subscribe(
        (state) => state.taskFilter,
        (nextFilter, previousFilter) => {
          console.log(
            'filter:',
            previousFilter,
            '→',
            nextFilter,
          );
        },
      );


    return unsubscribe;
  }, []);


  return null;
}

src/components/TaskList.tsx 전체 파일

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


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


  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>
  );
}

src/store/migrateUi.ts 전체 파일

type Filter = 'all' | 'active' | 'completed';
function isRecord(value: unknown): value is Record<string, unknown> {
  return !!value && typeof value === 'object' && !Array.isArray(value);
}
export function migrateUi(value: unknown, _version: number) {
  const data = isRecord(value) ? value : {};
  const candidate = data.taskFilter ?? data.filter;
  const taskFilter: Filter = candidate === 'active' || candidate === 'completed' ? candidate : 'all';
  const preferences = isRecord(data.preferences) ? data.preferences : {};
  const list = isRecord(preferences.list) ? preferences.list : {};
  return {
    taskFilter,
    selectedTaskId: typeof data.selectedTaskId === 'string' ? data.selectedTaskId : null,
    preferences: { list: { compact: list.compact === true, showCompleted: list.showCompleted !== false } },
  };
}

src/store/useTaskStore.ts 전체 파일

import { create } from 'zustand';
import { combine, persist, devtools, subscribeWithSelector } from 'zustand/middleware';
import { immer } from 'zustand/middleware/immer';
import type { Task } from '../types/task';
import { migrateUi } from './migrateUi';
export type TaskFilter = 'all' | 'active' | 'completed';
export type { Task } from '../types/task';
const initialState = {
  tasks: [] as Task[],
  taskFilter: 'all' as TaskFilter,
  selectedTaskId: null as string | null,
  isTaskModalOpen: false,
  preferences: { list: { compact: false, showCompleted: true } },
};
const creator = persist(
  combine(initialState, immer((set) => ({
    addTask: (title: string) => {
      const value = title.trim();
      if (!value) return;
      set((state) => { state.tasks.push({ id: crypto.randomUUID(), title: value, completed: false }); });
    },
    toggleTask: (id: string) => set((state) => {
      const task = state.tasks.find((item) => item.id === id);
      if (task) task.completed = !task.completed;
    }),
    deleteTask: (id: string) => set((state) => {
      state.tasks = state.tasks.filter((task) => task.id !== id);
      if (state.selectedTaskId === id) state.selectedTaskId = null;
    }),
    selectTask: (selectedTaskId: string | null) => set({ selectedTaskId }),
    openTaskModal: () => set({ isTaskModalOpen: true }),
    closeTaskModal: () => set({ isTaskModalOpen: false }),
    setFilter: (taskFilter: TaskFilter) => set({ taskFilter }),
    toggleCompact: () => set((state) => { state.preferences.list.compact = !state.preferences.list.compact; }),
    toggleShowCompleted: () => set((state) => { state.preferences.list.showCompleted = !state.preferences.list.showCompleted; }),
  }))),
  {
    name: 'taskflow-ui',
    version: 2,
    partialize: (state) => ({ taskFilter: state.taskFilter, selectedTaskId: state.selectedTaskId, preferences: state.preferences }),
    migrate: (state, version) => migrateUi(state, version),
  },
);
export const useTaskStore = create(devtools(subscribeWithSelector(creator), { name: 'TaskFlowStore' }));

완료 확인

1. 시작본은 직전 완료본과 동일한 ZIP입니다. 압축을 푼 뒤 npm ci로 잠금 파일의 의존성을 설치합니다.
2. npm run dev 실행 후 터미널의 localhost 주소를 엽니다.
3. filter를 taskFilter로 바꾸고 모든 읽기·호출부·Watcher를 함께 갱신합니다. 저장 version 2와 안전한 migrate를 적용해 이전 filter/selectedTaskId/preferences를 보존합니다. docs/migration-fixture.md는 개인 값과 분리된 테스트 절차입니다.
4. npm run typecheck와 npm run build가 성공하면 다음 프로젝트 단계로 갑니다.

이 체크포인트는 TypeScript 검사·프로덕션 빌드와 실제 소스를 사용한 JSDOM/상태 시나리오 검증을 통과했습니다. 별도 실제 브라우저 화면 검수는 이 파일 검증 범위에 포함하지 않았습니다.

아래 부분 예제는 핵심 변경을 설명합니다. 실행에 필요한 전체 파일과 보조 타입·API는 위 완료본에서 확인하세요.