Vue.js 패턴 및 모범 사례

Composition API를 활용한 Vue.js 3 개발을 위한 종합 가이드(

표현형 컴포넌트 대 컨테이너형 컴포넌트

• 컨테이너 컴포넌트: 데이터 가져오기, 상태 및 부수 효과를 직접 관리합니다. 프리젠테이션 컴포넌트를 렌더링합니다.
• 표현형 컴포넌트: 프로프(props)를 수신하고 이벤트를 발생시킵니다. API 호출이나 스토어 접근이 없습니다. 순수한 렌더링만 수행합니다.

프로프 모범 사례

// 기본값이 지정된 타입 기반 props
interface Props {
  label: string;
  variant?: "primary" | "secondary";
  disabled?: boolean;
  items: Item[];
}

const props = withDefaults(defineProps(), {
  variant: "primary",
  disabled: false,
});

• 항상 타입을 명시하고, 필요한 경우필수 속성 및기본값을 지정하세요.
• 부울형 프로퍼티: isXxx, hasXxx, canXxx.
• 프로퍼티를 절대 직접 수정하지 말고, 대신 이벤트를 발생시키세요.
• v-model 바인딩의 경우, defineModel() (Vue 3.4 이상) 또는 modelValue + update:modelValue를 사용하세요.

이벤트

const emit = defineEmits<{
  submit: [];
  "update:modelValue": [value: string];
  select: [id: string, index: number];
}>();

• 템플릿에서는 kebab-case를 사용하세요 (@update:model-value).
• 스크립트에서는 camelCase를 사용하세요 (emit("update:modelValue", val)).

3. 컴포저블(재사용 가능한 로직)

구조

// composables/useDebounce.ts
export function useDebounce(value: MaybeRef, delay: number): Ref {
  const debounced = ref(toValue(value)) as Ref;

  let timer: ReturnType;
  watch(
    () => toValue(value),
    (newVal) => {
      clearTimeout(timer);
      timer = setTimeout(() => { debounced.value = newVal; }, delay);
    }
  );

  onUnmounted(() => clearTimeout(timer));
  return readonly(debounced);
}

규칙

• 반드시 'use' 접두사로 시작해야 합니다.
• 반응형 값(ref, computed, reactive)을 반환해야 하며, 절대 일반 기본형(primitives)을 반환해서는 안 됩니다.
• MaybeRef / toRef() / toValue()를 통해 반응형 입력을 받아들여야 합니다.
• onUnmounted 또는 watcher의 onCleanup에서 부수 효과를 정리해야 합니다.
• 모듈 범위 내의 부수 효과는 허용되지 않습니다.

vs 믹신

Composables는 Vue 2의 믹신을 완전히 대체합니다:

• 믹신: 불투명한 데이터 흐름, 단일 진실원 충돌, 이름 충돌.
• 컴포저블: 명시적인 임포트, 명확한 반환 값, 조합 가능하며 트리 셰이킹이 가능합니다.

4. 상태 관리

언제 무엇을 사용할지

Pinia 스토어 설정 (권장)

// stores/useCartStore.ts
export const useCartStore = defineStore("cart", () => {
  const items = ref([]);
  const isLoading = ref(false);

  const totalPrice = computed(() =>
    items.value.reduce((sum, i) => sum + i.price * i.quantity, 0)
  );
  const itemCount = computed(() =>
    items.value.reduce((sum, i) => sum + i.quantity, 0)
  );

  async function addItem(productId: string) {
    isLoading.value = true;
    try {
      const item = await fetchProduct(productId);
      const existing = items.value.find(i => i.id === item.id);
      if (existing) existing.quantity++;
      else items.value.push({ ...item, quantity: 1 });
    } finally {
      isLoading.value = false;
    }
  }

  return { items, isLoading, totalPrice, itemCount, addItem };
});

• Setup Store 구문(Options Store가 아님)을 사용하세요.
• 비즈니스 수준의 변경에는 액션을, 그룹화된 업데이트에는 $patch() 를 우선적으로 사용하세요.
• 모든 비동기 액션: 로딩 + 성공 + 오류 처리.

5. Vue Router

경로 정의

const routes = [
  {
    path: "/users/:id",
    name: "user-detail",
    component: () => import("@/pages/UserDetail.vue"), // 지연 로딩
    props: true, // 매개변수를 props로 전달
    meta: { requiresAuth: true },
  },
];

네비게이션 가드

router.beforeEach((to, from) => {
  const { isLoggedIn } = useAuthStore();
  if (to.meta.requiresAuth && !isLoggedIn) {
    return { name: "login", query: { redirect: to.fullPath } };
  }
});

반응형 라우트 매개변수

컴포넌트가 마운트된 상태에서 라우트 매개변수가 변경될 때:

const route = useRoute();
const id = computed(() => route.params.id as string);
watch(id, (newId) => fetchItem(newId));

6. 템플릿 패턴

템플릿 구문

로딩 중...
오류: {{ error }}
{{ content }}


토글된 콘텐츠


{{ item.name }}


{{ item.name }}




  저장

7. 성능

8. 테스트

Stack

• 단위 테스트 및 컴포넌트 테스트를 위한Vitest
• 마운팅 및 상호작용을 위한Vue Test Utils
• 스토어 모킹을 위한@pinia/testing
• E2E 테스트용Playwright

컴포넌트 테스트 패턴

import { mount } from "@vue/test-utils";
import { createPinia, setActivePinia } from "pinia";
import UserCard from "./UserCard.vue";

beforeEach(() => { setActivePinia(createPinia()); });

it("렌더링되고 이벤트가 발생합니다", async () => {
  const wrapper = mount(UserCard, {
    props: { user: { id: "1", name: "Alice" } },
  });
  expect(wrapper.text()).toContain("Alice");
  await wrapper.find("button").trigger("click");
  expect(wrapper.emitted("select")![0]).toEqual(["1"]);
});

9. Nuxt 전용 패턴

자동 임포트

Nuxt는 ref, computed, watch, useFetch, useAsyncData 등을 자동으로 임포트합니다. 임포트 선언 없이 바로 사용하세요. Nuxt가 아닌 프로젝트에서는 항상 명시적으로 임포트해야 합니다.

useAsyncData / useFetch

const { data: user, pending, error, refresh } = await useAsyncData(
  "user", // 캐싱을 위한 고유 키
  () => $fetch(`/api/users/${id}`),
);

const { data: posts } = await useFetch("/api/posts", {
  query: { page: 1 },
  key: "posts-page-1", // 중복 요청 방지
});

서버 라우트

// server/api/users/[id].ts
export default defineEventHandler(async (event) => {
  const { id } = await getValidatedRouterParams(event, z.object({
    id: z.string().uuid(),
  }).parse);
  // ... 데이터를 가져와 반환
});

런타임 구성

// nuxt.config.ts
export default defineNuxtConfig({
  runtimeConfig: {
    // 서버 전용
    apiSecret: "",
    // 공개 (클라이언트에 노출)
    public: {
      apiBase: "https://api.example.com",
    },
  },
});

10. Vue 3.5+의 새로운 API

반응형 프로프스 해체

Vue 3.5에서는 반응형 프로프스 해체 기능이 안정화되었습니다. defineProps() 에서 해체된 변수는 자동으로 반응형이 됩니다:

// Vue 3.5 이상: 분해된 프로프스는 반응형입니다 (toRefs가 필요 없음)
const { count = 0, msg = "hello" } = defineProps<{
  count?: number;
  msg?: string;
}>();

// 제한 사항: 분해 할당된 프로퍼티를 직접 감시할 수 없음
watch(() => count, (newVal) => { ... }); // 통과, getter 필수

useTemplateRef()

템플릿 참조의 경우, 이름이 일치하는 일반 ref를 useTemplateRef() 로 대체하세요:

import { useTemplateRef } from "vue";
const inputEl = useTemplateRef("input");
// "input"은 변수 이름이 아닌 템플릿 내의 ref="input" 속성과 일치합니다

동적 ref ID 지원: useTemplateRef(dynamicRefId).

onWatcherCleanup()

전역에서 임포트 가능한 워처 정리 API(Vue 3.5 이상). 워처 콜백 내부에서 동기식으로 호출해야 합니다:

import { watch, onWatcherCleanup } from "vue";

watch(userId, async (newId) => {
  const controller = new AbortController();
  onWatcherCleanup(() => controller.abort());
  // ... 신호를 사용하여 데이터 가져오기
});

useId()

폼 요소 및 접근성을 위한 SSR 호환 고유 ID 생성:

import { useId } from "vue";
const id = useId();

defer Teleport

동일한 렌더링 사이클 내에서 렌더링된 대상 위치로 텔레포트할 수 있게 합니다:

콘텐츠

지연 하이드레이션 (SSR)

defineAsyncComponent() 가 이제 하이드레이션 전략을 지원합니다:

import { defineAsyncComponent, hydrateOnVisible } from "vue";
const AsyncComp = defineAsyncComponent({
  loader: () => import("./Comp.vue"),
  hydrate: hydrateOnVisible(),
});

안티패턴

안티패턴	왜 잘못된가	해결 방법
defineProps() 의 디스트럭처링 (Vue 3.5 미만)	스냅샷을 캡처하여 반응성을 상실함	props.xxx를 통해 접근하거나 toRefs() 사용
해체된 prop에watch() 적용 (Vue 3.5+)	컴파일 시간 오류 — 구조 해체된 props는 직접 감시할 수 없음	게터 래퍼 사용: watch(() => count, ...)
동일한 요소에v-if + v-for 적용	모호한 실행 순서	계산된 필터링된 배열 사용
v-for 키 = 인덱스	순서 변경 시 상태 오류	안정적인 데이터베이스 ID 사용
프로퍼티 변경	단방향 데이터 흐름 위반	이벤트 발생 또는 v-model 사용
사용자 콘텐츠가 포함된v-html	XSS 취약점	DOMPurify를 사용하여 정제
Vue 3의 믹스인	불투명하고 충돌 발생 가능성이 높음	컴포저블로 대체
컴포저블 내 모듈 범위 부작용	인스턴스 간 공유	onMounted 및 onUnmounted 내의 스코프
교체 가능한 상태를 위한reactive()	교체 시 반응성이 깨짐	대신 ref() 사용
정리 기능이 없는 Watcher	메모리 누수, 경합 상태	onCleanup 또는 onWatcherCleanup() 사용 (Vue 3.5 이상)
새로운 Vue 3 코드의 Options API	생태계가 Composition API로 전환 중	사용법 모든 파일 1개 파일 vue-patterns.md 12.8k 보기 vue-patterns 설치 ZIP 다운로드 Git Clone 스킬 파일을 다운로드한 후 .claude/skills/ 디렉터리에 압축을 풀어주세요. ZIP 다운로드 저장소를 클론하고 스킬 파일을 프로젝트에 복사하세요. git clone https://github.com/affaan-m/ECC/tree/main/skills/vue-patterns # Copy SKILL.md to your .claude/skills/ directory 복사 빠른 설정: 스킬 폴더를 .claude/skills/로 복사하세요. Claude가 해당 스킬을 자동으로 감지하여 사용할 것입니다. 저장소 affaan-m/ECC 관련 스킬 github-code-search 업데이트 된 시간 2026년 6월 29일 0 drizzle-orm 업데이트 된 시간 2026년 6월 29일 0 clickhouse-io 업데이트 된 시간 2026년 6월 29일 0 prisma-client-api 업데이트 된 시간 2026년 6월 29일 0 「모든 쿠키 수락」을 클릭하면 사이트 탐색 개선, 사이트 사용 분석 및 마케팅 활동 지원을 위해 장치에 쿠키를 저장하는 데 동의하게 됩니다.개인정보 취급방침 공지 쿠키 설정 모두 거부 모든 쿠키 수락 개인정보 설정 웹사이트를 방문하면 브라우저에 정보를 저장하거나 불러올 수 있으며, 대부분은 쿠키의 형태입니다. 이 정보는 사용자, 환경설정 또는 기기에 관한 것일 수 있으며, 사이트가 기대한 대로 작동하도록 하는 데 주로 사용됩니다. 이 정보가 직접적으로 사용자를 식별하지는 않지만, 더 개인화된 웹 환경을 제공할 수 있습니다. 당사는 사용자의 개인정보 보호 권리를 존중하기 때문에 일부 유형의 쿠키를 허용하지 않을 수 있습니다. 각 카테고리 제목을 클릭하면 자세히 알아보고 기본 설정을 변경할 수 있습니다. 그러나 일부 유형의 쿠키를 차단하면 사이트 이용 경험 및 제공 가능한 서비스에 영향을 줄 수 있습니다. 개인정보 취급방침 성명 환경설정 관리 필수 쿠키 항상 활성화 이 쿠키는 웹사이트가 정상적으로 기능하는 데 필요하며, 우리 시스템에서 끌 수 없습니다. 이러한 쿠키는 일반적으로 개인정보 설정, 로그인 또는 양식 작성과 같은 서비스 요청에 해당하는 사용자 행동에 응답하여만 설정됩니다. 브라우저를 설정하여 이러한 쿠키를 차단하거나 경고할 수 있지만, 그 경우 사이트의 일부 기능이 작동하지 않을 수 있습니다. 이러한 쿠키는 개인 식별 정보를 저장하지 않습니다. 모든 쿠키 수락 로그인 가입하십시오 OR 나를 기억하십시오 비밀번호를 잊어 버렸습니다 로그인 확인 코드를 가져옵니다 가입하십시오