Vue 컴포넌트 설계 패턴 완벽 가이드

Vue 3의 고급 컴포넌트 설계 패턴을 다룹니다. Composition API, props 설계, emit 패턴, provide/inject, 그리고 재사용 가능한 컴포넌트 아키텍처 설계 방법을 실전 예제와 함께 학습합니다.

---

---

들어가며

이 글에서는 Vue 컴포넌트 설계 패턴 완벽 가이드에 대해 상세히 알아보겠습니다. 총 12가지 주요 개념을 다루며, 각각의 개념에 대한 설명과 실제 코드 예제를 함께 제공합니다.

목차

1. Props_인터페이스_정의
2. Emit_타입_정의
3. Composable_함수_추출
4. Provide_Inject_패턴
5. Slots_타입_정의
6. 컴포넌트_제네릭
7. Computed_메모이제이션
8. Watch_깊은_감시
9. defineExpose_API_공개
10. Props_기본값_패턴
11. 비동기_컴포넌트_설계
12. 조건부_Props_패턴

---

1. Props 인터페이스 정의

개요

TypeScript를 활용하여 타입 안전한 props를 정의하고, 기본값과 유효성 검증을 설정합니다.

코드 예제

interface UserProps {
  name: string
  age: number
  role?: 'admin' | 'user'
}

const props = defineProps<UserProps>()
const { name, age, role = 'user' } = toRefs(props)

설명

defineProps의 제네릭 타입으로 props 인터페이스를 전달하면 타입 체크가 가능하고, toRefs로 반응성을 유지하면서 구조분해할 수 있습니다.

---

2. Emit 타입 정의

개요

컴포넌트가 발생시키는 이벤트를 타입으로 명시하여 부모 컴포넌트에서 안전하게 처리할 수 있습니다.

코드 예제

const emit = defineEmits<{
  update: [id: number, data: string]
  delete: [id: number]
  cancel: []
}>()

emit('update', 1, 'new data')
emit('delete', 1)

설명

defineEmits의 제네릭으로 이벤트명과 매개변수 타입을 정의하면, emit 호출 시 타입 체크가 이루어집니다.

---

3. Composable 함수 추출

개요

재사용 가능한 로직을 composable 함수로 분리하여 컴포넌트 간 공유하고 테스트하기 쉽게 만듭니다.

코드 예제

function useCounter(initial = 0) {
  const count = ref(initial)
  const increment = () => count.value++
  const decrement = () => count.value--

  return { count, increment, decrement }
}

설명

상태와 로직을 함수로 캡슐화하여 여러 컴포넌트에서 import하여 사용할 수 있습니다. use 접두사가 관례입니다.

---

4. Provide Inject 패턴

개요

깊이 중첩된 컴포넌트 트리에서 props drilling 없이 데이터를 전달하는 의존성 주입 패턴입니다.

코드 예제

// 부모 컴포넌트
const theme = ref('dark')
provide('theme', theme)

// 자식 컴포넌트
const theme = inject<Ref<string>>('theme')
console.log(theme.value) // 'dark'

설명

provide로 상위에서 값을 제공하고, inject로 하위 어디서든 접근할 수 있습니다. 타입 안전성을 위해 제네릭을 사용합니다.

---

5. Slots 타입 정의

개요

슬롯에 전달되는 데이터의 타입을 명시하여 부모 컴포넌트에서 자동완성과 타입 체크를 받을 수 있습니다.

코드 예제

defineSlots<{
  default(props: { item: User }): any
  header(props: { title: string }): any
}>()

// 사용: <template #default="{ item }">

설명

defineSlots로 슬롯명과 전달되는 props 타입을 정의하면, 슬롯을 사용하는 부모에서 타입 힌트를 받을 수 있습니다.

---

6. 컴포넌트 제네릭

개요

다양한 데이터 타입을 처리하는 범용 컴포넌트를 제네릭으로 설계합니다.

코드 예제

<script setup lang="ts" generic="T">
const props = defineProps<{
  items: T[]
  keyExtractor: (item: T) => string
}>()
</script>

설명

generic 속성으로 타입 매개변수를 선언하면, 컴포넌트 사용 시 실제 타입이 추론되어 타입 안전한 범용 컴포넌트를 만들 수 있습니다.

---

7. Computed 메모이제이션

개요

계산된 속성으로 복잡한 데이터 변환을 캐싱하여 성능을 최적화합니다.

코드 예제

const users = ref<User[]>([])
const activeUsers = computed(() =>
  users.value.filter(u => u.isActive)
)

const userCount = computed(() => activeUsers.value.length)

설명

computed는 의존하는 반응형 데이터가 변경될 때만 재계산되므로, 불필요한 연산을 방지하고 성능을 향상시킵니다.

---

8. Watch 깊은 감시

개요

중첩된 객체나 배열의 내부 변경까지 감지하여 사이드 이펙트를 처리합니다.

코드 예제

const state = ref({ user: { name: 'John' } })

watch(state, (newVal) => {
  console.log('상태 변경:', newVal)
}, { deep: true })

설명

deep 옵션을 true로 설정하면 객체 내부의 프로퍼티 변경도 감지합니다. 성능에 영향이 있으므로 필요한 경우에만 사용합니다.

---

9. defineExpose API 공개

개요

부모 컴포넌트가 ref로 접근할 수 있는 메서드와 속성을 명시적으로 공개합니다.

코드 예제

const count = ref(0)
const increment = () => count.value++

defineExpose({
  count: readonly(count),
  increment
})

설명

script setup은 기본적으로 모든 것이 비공개이므로, defineExpose로 외부에서 접근 가능한 API를 명시적으로 선언해야 합니다.

---

10. Props 기본값 패턴

개요

withDefaults를 사용하여 복잡한 타입의 props에 기본값을 안전하게 설정합니다.

코드 예제

interface Props {
  size?: 'sm' | 'md' | 'lg'
  config?: { theme: string }
}

const props = withDefaults(defineProps<Props>(), {
  size: 'md',
  config: () => ({ theme: 'light' })
})

설명

withDefaults는 타입과 기본값을 함께 정의할 수 있으며, 객체나 배열은 함수로 반환하여 참조 공유를 방지합니다.

---

11. 비동기 컴포넌트 설계

개요

Suspense와 함께 사용할 수 있는 비동기 setup을 활용하여 데이터 로딩을 우아하게 처리합니다.

코드 예제

<script setup>
const data = await fetch('/api/users')
  .then(r => r.json())

const filteredData = computed(() =>
  data.filter(item => item.active)
)
</script>

설명

script setup에서 최상위 await를 사용하면 컴포넌트가 비동기가 되어, 부모의 Suspense에서 로딩 상태를 처리할 수 있습니다.

---

12. 조건부 Props 패턴

개요

상호 배타적인 props를 타입 시스템으로 강제하여 잘못된 사용을 컴파일 타임에 방지합니다.

코드 예제

type Props =
  | { mode: 'edit'; item: Item }
  | { mode: 'create'; template?: Item }

const props = defineProps<Props>()

if (props.mode === 'edit') {
  console.log(props.item.id) // 타입 안전
}

설명

유니온 타입으로 mode에 따라 필수 props가 달라지는 패턴을 구현하면, 잘못된 조합의 props 사용을 컴파일 단계에서 차단할 수 있습니다.

---

마치며

이번 글에서는 Vue 컴포넌트 설계 패턴 완벽 가이드에 대해 알아보았습니다. 총 12가지 개념을 다루었으며, 각각의 사용법과 예제를 살펴보았습니다.

관련 태그

#Vue #CompositionAPI #ComponentDesign #PropsValidation #TypeScript