구조 분해하면 반응성이 사라집니다.

state/getter는 storeToRefs로, 액션은 스토어 객체에서 직접 꺼내는 패턴을 씁니다. const { count } = store만 하면 ref가 아닌 일반 값으로 고정됩니다.

Nuxt·SSR에서 스토어가 초기화됩니다.

요청마다 Pinia 인스턴스를 만들고 직렬화 가능한 상태만 클라이언트로 넘깁니다. 브라우저 전용 API 접근은 클라이언트 가드로 분리합니다.

스토어 간 순환 의존이 납니다.

동시 초기화 순서 문제를 피하려면 상위 스토어로 승격하거나, 교차 참조를 이벤트·컴포지션 루트로 한정합니다.

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

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

이 글의 핵심

Pinia는 Vue의 반응성 시스템 위에 스토어를 올리고, Options/Setup 스타일 모두에서 동일한 구독·디버깅 모델을 제공합니다. storeToRefs·SSR·플러그인·영속화와 운영 시 흔한 함정을 함께 다룹니다.

이 글의 핵심

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

9. Pinia 내부 모델과 Vue 반응성

Pinia 스토어는 Vue 3의 reactive/ref 위에 구축됩니다. Options 스타일 스토어는 내부적으로 상태·게터·액션을 Vue의 반응 시스템에 맞게 래핑하고, Setup 스타일은 작성한 ref/computed를 그대로 스토어 인스턴스로 노출합니다. 스토어 인스턴스는 effectScope 안에서 실행되어, 앱이 마운트 해제될 때 관련 이펙트가 함께 정리되는 방향으로 이해하면 디버깅이 수월합니다.

storeToRefs를 쓰는 이유: 액션·전체 스토어 객체를 그대로 구조 분해하면 반응성이 사라질 수 있습니다. 상태와 게터만 구조 분해할 때는 storeToRefs로 ref 유지를 보장합니다.

10. 프로덕션 패턴

10.1 스토어 간 의존과 순환 참조

한 스토어의 setup에서 다른 스토어를 useOtherStore()로 부르는 것은 흔하지만, 순환 의존(A→B→A)이 생기면 초기화 순서가 꼬일 수 있습니다. 해결책은 공통 도메인을 상위 스토어로 승격하거나, 이벤트 버스·컴포지션 루트에서만 교차 참조하도록 경계를 나누는 것입니다.

10.2 SSR·Nuxt

Nuxt 3에서는 @pinia/nuxt로 서버마다 깨끗한 스토어를 만들고, 클라이언트로 상태 직렬화를 넘깁니다. localStorage에 의존하는 플러그인은 import.meta.client 가드 없이 쓰면 SSR에서 터집니다. hydration mismatch가 나면 서버와 클라이언트 초기 상태를 맞추는지 확인합니다.

10.3 지속화(persist)와 보안

앞 절의 간이 localStorage 예제는 토큰·PII를 넣기에 부적절합니다. 민감 필드는 메모리만 두거나, httpOnly 쿠키·세션과 역할을 나눕니다. $subscribe는 대량 업데이트마다 저장하면 I/O 병목이 되므로 debounce를 고려합니다.

11. 트러블슈팅

증상	원인 후보
구조 분해 후 화면이 갱신 안 됨	`storeToRefs` 미사용 또는 액션을 잘못 분해
두 스토어가 서로 다른 인스턴스처럼 보임	테스트·스토리북에서 새 Pinia를 매번 만들지 않음
HMR 후 상태가 꼬임	개발 전용 이슈 — 새로고침 또는 스토어 `$reset`
무한 요청 루프	`watch`+액션에서 동일 조건으로 다시 트리거
Devtools에 액션이 안 보임	프로덕션 빌드에서 devtools 비활성 — 정상

정리 및 체크리스트

핵심 요약

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 공식 라이브러리로 안정적입니다.

심화 부록: 구현·운영 관점

이 부록은 앞선 본문에서 다룬 주제(「Pinia 완벽 가이드 | Vue 3 상태 관리·Composition API·TypeScript·실전 활용」)를 구현·런타임·운영 관점에서 다시 압축합니다. 도메인별 세부 구현은 글마다 다르지만, 입력 검증 → 핵심 연산 → 부작용(I/O·네트워크·동시성) → 관측의 흐름으로 장애를 나누면 원인 추적이 빨라집니다.

내부 동작과 핵심 메커니즘

flowchart TD
  A[입력·요청·이벤트] --> B[파싱·검증·디코딩]
  B --> C[핵심 연산·상태 전이]
  C --> D[부작용: I/O·네트워크·동시성]
  D --> E[결과·관측·저장]

sequenceDiagram
  participant C as 클라이언트/호출자
  participant B as 경계(런타임·게이트웨이·프로세스)
  participant D as 의존성(API·DB·큐·파일)
  C->>B: 요청/이벤트
  B->>D: 조회·쓰기·RPC
  D-->>B: 지연·부분 실패·재시도 가능
  B-->>C: 응답 또는 오류(코드·상관 ID)

불변 조건(Invariant): 버퍼 경계, 프로토콜 상태, 트랜잭션 격리, FD 상한 등 단계별로 문장으로 적어 두면 디버깅 비용이 줄어듭니다.
결정성: 순수 층과 시간·네트워크·스케줄에 의존하는 층을 분리해야 테스트와 장애 분석이 쉬워집니다.
경계 비용: 직렬화, 인코딩, syscall 횟수, 락 경합, 할당·GC, 캐시 미스를 의심 목록에 둡니다.
백프레셔: 생산자가 소비자보다 빠를 때 버퍼·큐·스트림에서 속도를 줄이는 신호를 어디에 둘지 정의합니다.

프로덕션 운영 패턴

영역	운영 관점 질문
관측성	요청 단위 상관 ID, 에러율·지연 p95/p99, 의존성 타임아웃·재시도가 대시보드에 보이는가
안전성	입력 검증·권한·비밀·감사 로그가 코드 경로마다 일관적인가
신뢰성	재시도는 멱등 연산에만 적용되는가, 서킷 브레이커·백오프·DLQ가 있는가
성능	캐시·배치 크기·커넥션 풀·인덱스·백프레셔가 데이터 규모에 맞는가
배포	롤백 룬북, 카나리/블루그린, 마이그레이션·피처 플래그가 문서화되어 있는가
용량	피크 트래픽·디스크·FD·스레드 풀 상한을 주기적으로 검증하는가

스테이징은 데이터 양·네트워크 RTT·동시성을 프로덕션에 가깝게 맞출수록 재현율이 올라갑니다.

확장 예시: 엔드투엔드 미니 시나리오

앞선 본문 주제(「Pinia 완벽 가이드 | Vue 3 상태 관리·Composition API·TypeScript·실전 활용」)를 배포·운영 흐름에 맞춰 옮긴 체크리스트입니다. 도메인에 맞게 단계 이름만 바꿔 적용할 수 있습니다.

입력 계약 고정: 스키마·버전·최대 페이로드·타임아웃·에러 코드를 경계에 둔다.
핵심 경로 계측: 요청 ID, 단계별 지연, 외부 호출 결과 코드를 로그·메트릭·트레이스에서 한 흐름으로 본다.
실패 주입: 의존성 타임아웃·5xx·부분 데이터·락 대기를 스테이징에서 재현한다.
호환·롤백: 설정/마이그레이션/클라이언트 버전을 되돌릴 수 있는지 확인한다.
부하 후 검증: 피크 대비 p95/p99, 에러율, 리소스 상한, 알림 임계값을 점검한다.

handle(request):
  ctx = newCorrelationId()
  validated = validateSchema(request)
  authorize(validated, ctx)
  result = domainCore(validated)
  persistOrEmit(result, idempotentKey)
  recordMetrics(ctx, latency, outcome)
  return result

문제 해결(Troubleshooting)

증상	가능 원인	조치
간헐적 실패	레이스, 타임아웃, 외부 의존성, DNS	최소 재현 스크립트, 분산 트레이스·로그 상관관계, 재시도·서킷 설정 점검
성능 저하	N+1, 동기 I/O, 락 경합, 과도한 직렬화, 캐시 미스	프로파일러·APM으로 핫스팟 확인 후 한 가지씩 제거
메모리 증가	캐시 무제한, 구독/리스너 누수, 대용량 버퍼, 커넥션 미반납	상한·TTL·힙/FD 스냅샷 비교
빌드·배포만 실패	환경 변수, 권한, 플랫폼 차이, lockfile	CI 로그와 로컬 diff, 런타임·이미지 버전 핀
설정 불일치	프로필·시크릿·기본값, 리전	스키마 검증된 설정 단일 소스와 배포 매트릭스 표준화
데이터 불일치	비멱등 재시도, 부분 쓰기, 캐시 무효화 누락	멱등 키·아웃박스·트랜잭션 경계 재검토

권장 순서: (1) 최소 재현 (2) 최근 변경 범위 축소 (3) 환경·의존성 차이 (4) 관측으로 가설 검증 (5) 수정 후 회귀·부하 테스트.

배포 전에는 git add → git commit → git push 후 npm run deploy 순서를 권장합니다.

이 글이 도움이 되셨나요?

여러분의 피드백은 더 나은 콘텐츠를 만드는 데 도움이 됩니다

문제가 있거나 개선 제안이 있으시면 연락처로 알려주세요.

Keyboard Shortcuts

이 글의 핵심

이 글의 핵심

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

실무 문제 시나리오

Vuex는 Options API 기반입니다. Pinia는 Composition API 친화적입니다.

1. Pinia란?

핵심 특징

2. 설치 및 설정

설치

main.ts

3. Store 정의

Options API 스타일

Composition API 스타일

4. 컴포넌트에서 사용

Options API

Composition API

5. 여러 Store

6. Plugins

7. $patch & $reset

$patch

$reset

8. Devtools

9. Pinia 내부 모델과 Vue 반응성

10. 프로덕션 패턴

10.1 스토어 간 의존과 순환 참조

10.2 SSR·Nuxt

10.3 지속화(persist)와 보안

11. 트러블슈팅

정리 및 체크리스트

핵심 요약

구현 체크리스트

같이 보면 좋은 글

이 글에서 다루는 키워드

자주 묻는 질문 (FAQ)

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

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

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

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

심화 부록: 구현·운영 관점

내부 동작과 핵심 메커니즘

프로덕션 운영 패턴

확장 예시: 엔드투엔드 미니 시나리오

문제 해결(Troubleshooting)

이 글이 도움이 되셨나요?