Pinia 완벽 가이드 | Vue 3 상태 관리·Composition API·TypeScript·실전 활용

2026년 4월 7일 · 15분 읽기 · 수정 2026년 4월 7일 중급

이 글의 핵심

Pinia로 Vue 3 상태 관리를 구현하는 완벽 가이드입니다. Store 정의, Composition API, TypeScript, Plugins, Devtools까지 실전 예제로 정리했습니다.

실무 경험 공유: Vuex에서 Pinia로 전환하면서, 보일러플레이트가 70% 감소하고 TypeScript 지원이 완벽해진 경험을 공유합니다.

들어가며: “Vuex가 복잡해요”

실무 문제 시나리오

시나리오 1: Vuex가 너무 복잡해요
Mutations, Actions가 번거롭습니다. Pinia는 간단합니다.

시나리오 2: TypeScript 지원이 부족해요
Vuex는 타입 추론이 약합니다. Pinia는 완벽합니다.

시나리오 3: Composition API와 맞지 않아요
Vuex는 Options API 기반입니다. Pinia는 Composition API 친화적입니다.

1. Pinia란?

핵심 특징

Pinia는 Vue 3 공식 상태 관리 라이브러리입니다.

주요 장점:

간단한 API: Mutations 없음
TypeScript: 완벽한 지원
Composition API: 자연스러운 통합
Devtools: 강력한 디버깅
작은 크기: 1KB

2. 설치 및 설정

설치

npm install pinia

main.ts

import { createApp } from 'vue';
import { createPinia } from 'pinia';
import App from './App.vue';

const pinia = createPinia();
const app = createApp(App);

app.use(pinia);
app.mount('#app');

3. Store 정의

Options API 스타일

// stores/counter.ts
import { defineStore } from 'pinia';

export const useCounterStore = defineStore('counter', {
  state: () => ({
    count: 0,
    name: 'Counter',
  }),

  getters: {
    doubleCount: (state) => state.count * 2,
  },

  actions: {
    increment() {
      this.count++;
    },
    decrement() {
      this.count--;
    },
    async fetchCount() {
      const response = await fetch('/api/count');
      const data = await response.json();
      this.count = data.count;
    },
  },
});

Composition API 스타일

// stores/counter.ts
import { defineStore } from 'pinia';
import { ref, computed } from 'vue';

export const useCounterStore = defineStore('counter', () => {
  const count = ref(0);
  const name = ref('Counter');

  const doubleCount = computed(() => count.value * 2);

  function increment() {
    count.value++;
  }

  function decrement() {
    count.value--;
  }

  async function fetchCount() {
    const response = await fetch('/api/count');
    const data = await response.json();
    count.value = data.count;
  }

  return {
    count,
    name,
    doubleCount,
    increment,
    decrement,
    fetchCount,
  };
});

4. 컴포넌트에서 사용

Options API

<script>
import { useCounterStore } from '@/stores/counter';

export default {
  setup() {
    const counter = useCounterStore();
    return { counter };
  },
};
</script>

<template>
  <div>
    <p>Count: {{ counter.count }}</p>
    <p>Double: {{ counter.doubleCount }}</p>
    <button @click="counter.increment">+</button>
    <button @click="counter.decrement">-</button>
  </div>
</template>

Composition API

<script setup lang="ts">
import { useCounterStore } from '@/stores/counter';
import { storeToRefs } from 'pinia';

const counter = useCounterStore();
const { count, doubleCount } = storeToRefs(counter);
const { increment, decrement } = counter;
</script>

<template>
  <div>
    <p>Count: {{ count }}</p>
    <p>Double: {{ doubleCount }}</p>
    <button @click="increment">+</button>
    <button @click="decrement">-</button>
  </div>
</template>

5. 여러 Store

// stores/user.ts
export const useUserStore = defineStore('user', () => {
  const user = ref<User | null>(null);
  const isLoggedIn = computed(() => !!user.value);

  async function login(email: string, password: string) {
    const response = await fetch('/api/login', {
      method: 'POST',
      body: JSON.stringify({ email, password }),
    });
    user.value = await response.json();
  }

  function logout() {
    user.value = null;
  }

  return { user, isLoggedIn, login, logout };
});

// 다른 Store에서 사용
export const useCartStore = defineStore('cart', () => {
  const userStore = useUserStore();

  const items = ref([]);

  async function addItem(item) {
    if (!userStore.isLoggedIn) {
      throw new Error('Please login first');
    }
    items.value.push(item);
  }

  return { items, addItem };
});

6. Plugins

// plugins/persistedState.ts
import { PiniaPluginContext } from 'pinia';

export function persistedStatePlugin({ store }: PiniaPluginContext) {
  const stored = localStorage.getItem(store.$id);

  if (stored) {
    store.$patch(JSON.parse(stored));
  }

  store.$subscribe((mutation, state) => {
    localStorage.setItem(store.$id, JSON.stringify(state));
  });
}

// main.ts
import { persistedStatePlugin } from './plugins/persistedState';

const pinia = createPinia();
pinia.use(persistedStatePlugin);

7. $patch & $reset

$patch

const counter = useCounterStore();

// 객체로 업데이트
counter.$patch({
  count: 10,
  name: 'Updated',
});

// 함수로 업데이트
counter.$patch((state) => {
  state.count++;
  state.name = 'Updated';
});

$reset

counter.$reset();

8. Devtools

// 자동으로 Vue Devtools에 통합됨
// Time-travel debugging
// State inspection
// Actions tracking

정리 및 체크리스트

핵심 요약

Pinia: Vue 3 상태 관리
간단한 API: Mutations 없음
TypeScript: 완벽한 지원
Composition API: 자연스러운 통합
Plugins: 확장 가능
Devtools: 강력한 디버깅

구현 체크리스트

같이 보면 좋은 글

Vue 3 Composition API 가이드
Zustand 완벽 가이드
Vuex 마이그레이션 가이드

이 글에서 다루는 키워드

Pinia, Vue 3, State Management, Composition API, TypeScript, Frontend, Vuex

자주 묻는 질문 (FAQ)

Q. Vuex와 비교하면 어떤가요?

A. Pinia가 훨씬 간단하고 TypeScript 지원이 좋습니다. Vuex는 더 오래됐지만 복잡합니다.

Q. Vue 2에서도 사용할 수 있나요?

A. 네, 플러그인을 통해 Vue 2에서도 사용할 수 있습니다.

Q. Vuex에서 마이그레이션이 어려운가요?

A. 비교적 간단합니다. Mutations를 Actions로 옮기면 됩니다.

Q. 프로덕션에서 사용해도 되나요?

A. 네, Vue 공식 라이브러리로 안정적입니다.