[Nuxt3] 스토리지: vueuse

 

정리

1. 오래 보관해야 하고, 도메인 전체에서 유지할 데이터라면 localStorage.
2. 탭을 닫으면 사라져야 하는, 세션 한정 데이터라면 sessionStorage.
3. VueUse는 단순 훅으로, 컴포넌트 단위에서 직관적으로 스토리지에 접근하기 좋음.
4. Pinia Persist는 전역 상태 관리와 자동 저장에 특화되어 있어, 상황에 따라 적절한 솔루션을 골라 사용

 

---

 

1. VueUse란?

VueUse는 Vue 3의 Composition API와 반응성(Reactivity)의 장점을 극대화할 수 있도록 고안된 유틸리티 라이브러리입니다. Vue 3로 개발할 때 자주 필요한 훅(Hooks), 함수, 도구를 모아놓은 저장소라고 볼 수 있습니다.

• useLocalStorage, useSessionStorage, useStorage 등 브라우저 스토리지를 간편히 다루는 함수.
• useDark, useMediaQuery 등 브라우저 API를 프록시 해주는 함수.
• useMouse, useWindowScroll 등 사용자 입력 또는 뷰포트 관련 유틸.
• useAsyncState, useFetch 등 비동기 통신에서 편의성을 높여주는 함수.

VueUse를 사용하면, 일일이 JS API와 상태 관리를 작성하지 않고도, Vue 전용으로 추상화된 재사용 가능한 로직들을 간편히 사용할 수 있습니다.

2. 웹 스토리지의 개요

1) localStorage (로컬 스토리지)

• 유지기간: 브라우저를 닫아도 데이터가 계속 유지됩니다. (직접 삭제하지 않는 한 영구 보관)
• 범위: 도메인 단위로 저장되어, 같은 도메인 내 다른 페이지에서도 접근할 수 있습니다.
• 사용 예시: 사용자 설정, 로그인 정보, 애플리케이션 상태 등을 장기적으로 저장할 때.

2) sessionStorage (세션 스토리지)

• 유지기간: 브라우저 탭이나 창을 닫으면 세션이 종료되므로, 해당 데이터도 함께 사라집니다.
• 범위: 도메인 단위이지만, 탭/창이 닫히면 세션이 종료됩니다. 새 창(탭)에서는 기존 세션 데이터에 접근 불가.
• 사용 예시: 세션 내에서만 필요한 임시 데이터, 예: 한 탭에서만 유지되는 폼 정보.

 

3. VueUse + Nuxt3 환경에서의 활용

1) 패키지 설치

pnpm add @vueuse/core
pnpm add -D @vueuse/nuxt

2) Nuxt 구성 (nuxt.config.ts)

// nuxt.config.ts
export default defineNuxtConfig({
  modules: [
    '@vueuse/nuxt',
  ],
})

3) 기본 예시

아래는 예시로 pages/use-storage.vue를 하나 만든 다음, 로컬 스토리지와 세션 스토리지를 각각 사용해 색상 문자열을 저장/불러오는 코드입니다.

<!-- pages/use-storage.vue -->
<template>
  <div style="padding: 1rem;">
    <h1>Use Storage Example</h1>
    <div>
      <h3>Local Storage Color</h3>
      <input v-model="colorLocal" placeholder="Choose any color" />
      <p>Value in localStorage: {{ colorLocal }}</p>
    </div>
    <hr />
    <div>
      <h3>Session Storage Color</h3>
      <input v-model="colorSession" placeholder="Choose any color" />
      <p>Value in sessionStorage: {{ colorSession }}</p>
    </div>
  </div>
</template>

<script setup lang="ts">
import { useLocalStorage, useSessionStorage } from '@vueuse/core'

// localStorage
const colorLocal = useLocalStorage<string>('my-color-local', '')

// sessionStorage
const colorSession = useSessionStorage<string>('my-color-session', '')
</script>

 

4. Custom Serialization

localStorage/sessionStorage는 문자열만 저장할 수 있으므로, 객체·배열·날짜 등 복잡한 데이터를 보관하기 위해서는 직렬화 과정이 필요합니다. VueUse의 useStorage 계열 훅들은 기본적으로 JSON.stringify / JSON.parse를 사용하지만, 옵션(serializer)을 통해 원하는 방식으로 커스터마이징이 가능합니다.

아래 예시는 User라는 타입(이름, 나이)을 로컬 스토리지에 저장하면서, 커스텀 직렬화/역직렬화를 사용하는 간단한 예시입니다.

<!-- pages/use-storage-advanced.vue -->
<template>
  <div style="padding: 1rem;">
    <h1>Custom Serialization Example</h1>

    <label>Name:</label>
    <input v-model="user.value.name" />

    <label>Age:</label>
    <input type="number" v-model="user.value.age" />

    <p>Stored User: {{ user.value }}</p>
  </div>
</template>

<script setup lang="ts">
import { useLocalStorage } from '@vueuse/core'

interface User {
  name: string
  age: number
}

const defaultUser: User = { name: '홍길동', age: 20 }

// JSON.parse / stringify 커스텀 에러 핸들링 등을 위해 serializer 오버라이드
const user = useLocalStorage<User>('user-info', defaultUser, {
  serializer: {
    read: (raw: string) => {
      try {
        const parsed = JSON.parse(raw)
        return {
          ...defaultUser,
          ...parsed,
        }
      } catch (error) {
        return defaultUser
      }
    },
    write: (value: User) => JSON.stringify(value),
  },
})
</script>

• serializer.read(raw: string): 실제로 스토리지에 저장된 문자열(raw)을 받아서 User 객체를 반환합니다. 파싱 실패 시 기본 유저 정보를 반환.
• serializer.write(value: User): User 객체를 받아 JSON 문자열로 변환하여 저장합니다. 필요하다면 특정 필드를 마스킹하거나 추가 가공 후 저장할 수도 있습니다.

5. Pinia Persist와는 어떻게 다른가?

Vue에서 전역 상태 관리를 위해 Pinia를 사용하는 경우, 별도의 플러그인을 통해 persist(예: pinia-plugin-persistedstate) 기능을 적용할 수 있습니다. 이렇게 하면 Pinia 스토어의 상태값이 자동으로 localStorage나 sessionStorage에 동기화되어, 브라우저가 새로고침되거나 닫힌 뒤 다시 열어도(혹은 탭이 유지되는 동안) 상태가 이어집니다.

1) Pinia Persist의 특징

• 전역 상태 관리에 집중: Pinia는 Vue 앱 전체에서 공유되는 전역 상태를 관리합니다.
• 자동 동기화: 스토어 값이 바뀔 때마다 플러그인이 알아서 브라우저 스토리지에 반영합니다.
• 옵션 확장성: 특정 스토어에서만 persist를 켜거나, localStorage/sessionStorage 중 선택 가능.
• 구조: Pinia 스토어들이 각각 특정 key로 스토리지에 저장됩니다.

2) VueUse의 스토리지 훅과의 차이점

1. 설계 철학
   • Pinia Persist는 전역 상태 + 자동 동기화에 초점을 맞추고, Vue 애플리케이션 내에서 공통으로 사용하는 데이터를 효율적으로 관리합니다.
   • VueUse의 useLocalStorage나 useSessionStorage는 컴포넌트 단위나 단순 훅 차원에서 스토리지를 다루기 때문에, 작은 범위의 상태나 임시 데이터에 바로 적용하기에 유리합니다.
2. 사용 범위
   • Pinia Persist는 Pinia 스토어에 국한되어 동작합니다.
   • VueUse는 Pinia 없이도, 혹은 Pinia와 함께 혼용도 가능하므로 상황에 따라 유연합니다.
3. 커스터마이징
   • Pinia Persist는 전역 상태를 자동 저장·복원할 때 매우 간단히 설정 가능합니다.
   • VueUse useStorage 계열 훅은 직접 Serializer 옵션을 지정해 원하는 방식을 쉽게 오버라이드할 수 있어, 더욱 세밀한 커스터마이징이 가능합니다.

결론적으로, 전역 상태를 자동으로 관리하고 싶다면 Pinia Persist가 좋고, 컴포넌트 또는 로컬 단위로 빠르게 스토리지에 접근·제어해야 한다면 VueUse 훅이 편리합니다.