스토어 가이드

dictionary-app은 zustand로 전역 상태를 관리한다. hooks/stores(공통) 또는 페이지 디렉토리 하위 stores(페이지 전용)에 상태 모양별로 몇 가지 패턴을 반복해서 쓴다.

작성 규칙

훅 이름은 use로 시작하고 Store 접미사를 붙인다(useSpinnerStore, useSideMenuStore).
상태 타입(XxxStoreType)에 값과 액션(setter 함수)을 함께 정의하고, create<XxxStoreType>((set, get) => ({...}))로 만든다.
액션 이름은 하는 일이 드러나는 동사로 짓는다(setSessionUser, removeSessionUser, increaseSpinner).
특정 페이지에서만 쓰는 상태는 공통 hooks/stores가 아니라 해당 페이지 디렉토리 하위 stores에 동일한 형식으로 둔다.

카운터형 상태 — `useSpinnerStore`

여러 요청이 동시에 진행될 수 있어 boolean이 아니라 카운터로 관리한다. 카운터가 0보다 크면 스피너를 표시한다.

import {create} from 'zustand'

type SpinnerStoreType = {
  counter: number
  increaseSpinner: () => void
  decreaseSpinner: () => void
}

export const useSpinnerStore = create<SpinnerStoreType>((set) => ({
  counter: 0,
  increaseSpinner: () => {
    set((prev) => ({...prev, counter: prev.counter + 1}))
  },
  decreaseSpinner: () => {
    set((prev) => ({...prev, counter: prev.counter > 0 ? prev.counter - 1 : 0}))
  },
}))

useApi의 useSpinner 옵션이 요청 시작/종료 시점에 이 카운터를 자동으로 증감시킨다 — 자세한 내용은 백엔드 API 사용 예제 참고.

boolean 토글형 상태 — `useSideMenuStore`

import {create} from 'zustand'

type SideMenuStoreType = {
  isOpen: boolean
  open: () => void
  close: () => void
  toggle: () => void
}

export const useSideMenuStore = create<SideMenuStoreType>((set) => ({
  isOpen: false,
  open: () => set({isOpen: true}),
  close: () => set({isOpen: false}),
  toggle: () => set((prev) => ({isOpen: !prev.isOpen})),
}))

모바일 화면에서 side-menu를 Drawer로 열고 닫는 상태처럼, 컴포넌트 여러 곳(헤더의 토글 버튼, Drawer 자신)이 같은 열림 상태를 공유해야 할 때 쓴다.

Promise를 반환하는 요청-응답형 상태 — `useDialogStore`

openDialog가 만든 Promise의 resolve를 상태에 들고 있다가, closeDialog가 호출될 때 그 값으로 resolve한다 — 호출부는 await openDialog(...)처럼 사용자의 선택을 기다릴 수 있다.

1
import {create} from 'zustand'
2

3
export type DialogOptions = {
4
  title: string
5
  description?: string
6
  confirmText?: string
7
  cancelText?: string
8
  confirmColorPalette?: string
9
  showCancel?: boolean
10
}
11

12
type DialogStoreType = {
13
  isOpen: boolean
14
  options: DialogOptions | null
15
  resolve: ((confirmed: boolean) => void) | null
16
  openDialog: (options: DialogOptions) => Promise<boolean>
17
  closeDialog: (confirmed: boolean) => void
18
}
19

20
export const useDialogStore = create<DialogStoreType>((set, get) => ({
21
  isOpen: false,
22
  options: null,
23
  resolve: null,
24
  openDialog: (options) => {
25
    return new Promise<boolean>((resolve) => {
26
      set({isOpen: true, options, resolve})
27
    })
28
  },
29
  closeDialog: (confirmed) => {
30
    get().resolve?.(confirmed)
31
    set({isOpen: false, options: null, resolve: null})
32
  },
33
}))

스토어를 직접 쓰지 않고 confirmDialog/alertDialog(@/utils) 전역 함수를 통해 호출한다 — 자세한 소비 방법과 실사용 예는 alert/confirm 사용 예제 참고.

영속화(persist) + 서버 상태 동기화형 상태 — `useSessionStore`

zustand/middleware의 persist로 localStorage에 저장해, 새로고침해도 로그인 상태가 유지되게 한다. 복원(rehydrate) 시점에 만료 여부를 확인해서 지난 세션이면 지운다.


4 collapsed lines
1
import {create} from 'zustand'
2
import {persist} from 'zustand/middleware'
3

4
import type {components} from '@/types'
5

6
type SessionUser = components['schemas']['SessionUser']
7

8
type SessionStoreType = {
9
  sessionUser: SessionUser | null
10
  expiresAt: number | null
11
  // 게스트 안내 다이얼로그를 이번 로그인에서 이미 보여줬는지 여부. 로그아웃하면
12
  // false로 초기화돼 다음 로그인 때 다시 1회 노출된다.
13
  guestAlertShown: boolean
14
  setSessionUser: (sessionUser: SessionUser) => void
15
  setExpiresAt: (expiresAt: number) => void
16
  setGuestAlertShown: (guestAlertShown: boolean) => void
17
  removeSessionUser: () => void
18
}
19

20
export const useSessionStore = create<SessionStoreType>()(
21
  persist(
22
    (set) => ({
23
      sessionUser: null,
24
      expiresAt: null,
25
      guestAlertShown: false,
26
      setSessionUser: (sessionUser) => set({sessionUser}),
27
      setExpiresAt: (expiresAt) => set({expiresAt}),
28
      setGuestAlertShown: (guestAlertShown) => set({guestAlertShown}),
29
      removeSessionUser: () =>
30
        set({sessionUser: null, expiresAt: null, guestAlertShown: false}),
31
    }),
32
    {
33
      name: 'SESSION_USER',
34
      onRehydrateStorage: () => (state) => {
35
        const expiresAt = state?.expiresAt
36
        if (expiresAt !== undefined && expiresAt !== null && Date.now() >= expiresAt * 1000) {
37
          state?.removeSessionUser()
38
        }
39
      },
40
    },
41
  ),
42
)

사용 예: 인증 가드 — 서버에 세션 유효성을 재확인(useSessionFindQuery)하고, 성공하면 스토어를 최신화하고 401이면 비운다. 401이 아닌 에러(네트워크 순단, 백엔드 콜드스타트 등)는 “로그인되지 않음”으로 단정하지 않고, localStorage에 남은 세션의 만료 시각(expiresAt)이 아직 지나지 않았으면 그 값을 폴백으로 신뢰한다.


5 collapsed lines
1
import {useEffect} from 'react'
2
import {Navigate, Outlet} from 'react-router'
3

4
import {useSessionFindQuery, useSessionStore} from '@/hooks'
5
import {PageLoader} from '@/components'
6

7
export const RequireAuth = () => {
8
  const {
9
    sessionUser: persistedSessionUser,
10
    expiresAt: persistedExpiresAt,
11
    setSessionUser,
12
    removeSessionUser,
13
  } = useSessionStore()
14
  const {sessionUser, isSessionChecking, isSessionExpired} = useSessionFindQuery()
15

16
  const isPersistedSessionValid =
17
    persistedSessionUser !== null &&
18
    persistedExpiresAt !== null &&
19
    Date.now() < persistedExpiresAt * 1000
20

21
  useEffect(() => {
22
    if (sessionUser !== undefined) {
23
      setSessionUser(sessionUser)
24
    }
25
  }, [sessionUser, setSessionUser])
26

27
  useEffect(() => {
28
    if (isSessionExpired || (sessionUser === undefined && !isPersistedSessionValid)) {
29
      removeSessionUser()
30
    }
31
  }, [isSessionExpired, sessionUser, isPersistedSessionValid, removeSessionUser])
32

33
  if (isSessionChecking) {
34
    return <PageLoader />
35
  }
36
  if (isSessionExpired) {
37
    return <Navigate to="/login" replace />
38
  }
39
  if (sessionUser === undefined && !isPersistedSessionValid) {
40
    return <Navigate to="/login" replace />
41
  }
42
  return <Outlet />
43
}

사용 예: 로그아웃 — 스토어를 비우는 것과 함께 react-query 캐시(queryClient.clear())도 초기화해서, 재로그인(특히 게스트 로그인) 시 이전 사용자의 캐시된 조회 결과가 잠깐 되살아나지 않게 한다.
layout/header/Header.tsx
```
const handleLogout = async () => {
  try {
    await logout()
  } finally {
    removeSessionUser()
    queryClient.clear()
    navigate('/login', {replace: true})
  }
}
```

스토어 가이드

작성 규칙

카운터형 상태 — useSpinnerStore

boolean 토글형 상태 — useSideMenuStore

Promise를 반환하는 요청-응답형 상태 — useDialogStore

영속화(persist) + 서버 상태 동기화형 상태 — useSessionStore

카운터형 상태 — `useSpinnerStore`

boolean 토글형 상태 — `useSideMenuStore`

Promise를 반환하는 요청-응답형 상태 — `useDialogStore`

영속화(persist) + 서버 상태 동기화형 상태 — `useSessionStore`