💚
Vue 3 Composition API 치트시트

프로젝트 설치부터 create-vue, SFC 구조, 템플릿 문법, ref 반응형, v-model, 컴포넌트 통신까지 초보자를 위한 단계별 퀵 레퍼런스
#vue3#vue#install#vite#create-vue#composition-api#script-setup#javascript#typescript#frontend#beginner최종 업데이트: 2026-09-26
Vue 3 Composition API 치트시트 핵심 명령어 및 실전 가이드

프로젝트 설치부터 create-vue, SFC 구조, 템플릿 문법, ref 반응형, v-model, 컴포넌트 통신까지 초보자를 위한 단계별 퀵 레퍼런스
## 1. 프로젝트 생성 & 설치 (create-vue / Vite)
```bash
# 1. 공식 추천 방식으로 새 Vue 3 프로젝트 생성 (Vite 기반)
npm create vue@latest

# 프롬프트 선택 가이드:
# ✔ Project name: … my-vue-app
# ✔ Add TypeScript? … Yes (권장)
# ✔ Add JSX Support? … No
# ✔ Add Vue Router for SPA? … Yes (페이지 라우팅 필요 시)
# ✔ Add Pinia for state management? … Yes (전역 상태 관리 필요 시)
# ✔ Add ESLint & Prettier? … Yes

# 2. 의존성 설치 및 로컬 개발 서버 실행
cd my-vue-app
npm install
npm run dev

# 💡 초간단 CDN 방식 (별도 설치 없이 HTML 파일 하나로 테스트할 때)
# <script src="https://unpkg.com/vue@3/dist/vue.global.js"></script>
```

## 2. 프로젝트 디렉토리 구조 & SFC (.vue) 기본 개념
```text
my-vue-app/
├── index.html         → 브라우저가 가장 먼저 읽는 HTML 엔트리 포인트
├── src/
│   ├── main.ts        → Vue 앱 생성(createApp) 및 #app에 마운트
│   ├── App.vue        → 최상위 루트 컴포넌트
│   ├── components/    → 재사용 가능한 자식 컴포넌트 폴더
│   └── assets/        → 이미지, 전역 CSS 등 정적 리소스
└── package.json       → 프로젝트 설정 및 의존성 라이브러리
```
```vue
<!-- SFC (Single File Component): HTML + JS + CSS를 하나의 파일로 구성 -->
<script setup lang="ts">
// [1] 스크립트 영역: 자바스크립트/타입스크립트 로직 (Composition API)
const message = 'Hello, Vue 3!'
</script>

<template>
  <!-- [2] 템플릿 영역: 사용자에게 보여질 HTML 화면 -->
  <div class="container">
    <h1>{{ message }}</h1>
  </div>
</template>

<style scoped>
/* [3] 스타일 영역: scoped를 붙이면 이 컴포넌트 내부에만 CSS 격리 적용 */
.container { text-align: center; margin-top: 2rem; }
</style>
```

## 3. 템플릿 기본 문법: 화면에 데이터 띄우기
```vue
<script setup lang="ts">
const title = 'Vue 3 기본 문법'
const imgUrl = 'https://vuejs.org/images/logo.png'
const isVisible = true
const fruits = ['사과', '바나나', '포도']

const handleClick = () => alert('버튼이 클릭되었습니다!')
</script>

<template>
  <!-- 1. 텍스트 보간: {{ 변수 }} -->
  <h1>{{ title }}</h1>

  <!-- 2. 속성 바인딩: v-bind 또는 축약형 콜론(:) -->
  <img :src="imgUrl" alt="로고" width="40" />

  <!-- 3. 이벤트 바인딩: v-on 또는 축약형 골뱅이(@) -->
  <button @click="handleClick">클릭 이벤트</button>

  <!-- 4. 조건부 렌더링: v-if, v-else (DOM 자체를 생성/제거) -->
  <p v-if="isVisible">조건이 참일 때 표시</p>
  <p v-else>조건이 거짓일 때 표시</p>

  <!-- 5. 반복 렌더링: v-for (반드시 고유한 :key 바인딩) -->
  <ul>
    <li v-for="(fruit, index) in fruits" :key="index">{{ fruit }}</li>
  </ul>
</template>
```

## 4. 반응형 변수 만들기: ref 와 reactive
```vue
<script setup lang="ts">
import { ref, reactive } from 'vue'

// [1] ref: 숫자, 문자, 불리언, 배열, 객체 모든 타입 지원 (가장 범용적!)
// 💡 JS 내부에서는 '.value'로 접근하고, <template>에서는 '.value' 없이 자동 언래핑!
const count = ref(0)
const userName = ref('홍길동')

const increase = () => {
  count.value++ // 스크립트에서는 .value 필수
}

// [2] reactive: 오직 '객체/배열' 전용 (속성에 직접 접근 가능)
const user = reactive({
  age: 20,
  city: '서울'
})
const birthday = () => {
  user.age++ // .value 없이 직접 수정
}
</script>

<template>
  <!-- 템플릿에서는 .value 없이 변수명 그대로 사용 -->
  <p>{{ userName }}님의 카운트: {{ count }}</p>
  <button @click="increase">+1 증가</button>

  <p>나이: {{ user.age }}세 (거주지: {{ user.city }})</p>
  <button @click="birthday">한 살 먹기</button>
</template>
```

## 5. 폼 입력 & 양방향 바인딩: v-model
```vue
<script setup lang="ts">
import { ref } from 'vue'

const message = ref('')
const isSubscribed = ref(false)
const selectedCategory = ref('tech')
</script>

<template>
  <!-- 텍스트 인풋: 입력하는 즉시 message 변수에 실시간 반영 -->
  <input v-model="message" placeholder="메시지를 입력하세요" />
  <p>실시간 입력값: {{ message }}</p>

  <!-- 단일 체크박스 (불리언 바인딩) -->
  <label>
    <input type="checkbox" v-model="isSubscribed" /> 뉴스레터 구독
  </label>
  <p>구독 여부: {{ isSubscribed ? '구독 중' : '미구독' }}</p>

  <!-- 셀렉트 박스 바인딩 -->
  <select v-model="selectedCategory">
    <option value="tech">기술</option>
    <option value="life">일상</option>
  </select>

  <!-- 💡 유용한 v-model 수식어 -->
  <!-- v-model.trim   : 앞뒤 공백 자동 제거 -->
  <!-- v-model.number : 입력값을 자동으로 숫자(Number) 타입으로 형변환 -->
  <!-- v-model.lazy   : 입력 중(input)이 아니라 포커스를 잃을 때(change) 동기화 -->
</template>
```

## 6. 계산된 속성: computed (데이터 가공 & 캐싱)
```vue
<script setup lang="ts">
import { ref, computed } from 'vue'

const firstName = ref('길동')
const lastName = ref('홍')
const items = ref([
  { name: '노트북', price: 1500000 },
  { name: '마우스', price: 35000 }
])

// 💡 computed: 의존하는 반응형 상태가 변경될 때만 재계산되고 결과를 캐싱함
// (단순 함수 호출과 달리 템플릿 리렌더링마다 불필요하게 재실행되지 않음)
const fullName = computed(() => `${lastName.value} ${firstName.value}`)

const totalPrice = computed(() => {
  return items.value.reduce((sum, item) => sum + item.price, 0)
})
</script>

<template>
  <p>사용자 이름: {{ fullName }}</p>
  <p>총 결제 금액: {{ totalPrice.toLocaleString() }}원</p>
</template>
```

## 7. 데이터 변화 감지: watch 와 watchEffect
```vue
<script setup lang="ts">
import { ref, watch, watchEffect } from 'vue'

const searchWord = ref('')
const searchHistory = ref<string[]>([])

// 1. watch: 특정 상태의 [이전값]과 [새로운값]을 비교 감시
watch(searchWord, (newVal, oldVal) => {
  console.log(`검색어 변경: "${oldVal}" → "${newVal}"`)
  searchHistory.value.push(newVal)
}, { immediate: false }) // immediate: true 시 마운트 즉시 1회 실행

// 2. watchEffect: 콜백 안에서 사용된 반응형 변수를 자동으로 추적하여 즉시 실행
watchEffect(() => {
  console.log(`현재 검색어 기준 자동 동작: ${searchWord.value}`)
})
</script>

<template>
  <input v-model="searchWord" placeholder="검색어를 입력하세요" />
</template>
```

## 8. 부모-자식 컴포넌트 통신: defineProps & defineEmits
```vue
<!-- 자식 컴포넌트: UserCard.vue -->
<script setup lang="ts">
// 1. defineProps: 부모로부터 전달받는 속성 정의 (TypeScript 타입 지원)
const props = withDefaults(defineProps<{
  name: string
  age?: number // 선택적 prop
}>(), {
  age: 20 // 기본값
})

// 2. defineEmits: 부모에게 발생시킬 이벤트 정의
const emit = defineEmits<{
  (e: 'greet', message: string): void
}>()

const sendGreeting = () => {
  emit('greet', `${props.name}님이 인사했습니다!`)
}
</script>

<template>
  <div class="user-card">
    <h3>{{ props.name }} ({{ props.age }}세)</h3>
    <button @click="sendGreeting">인사 보내기</button>
  </div>
</template>
```
```vue
<!-- 부모 컴포넌트: App.vue -->
<script setup lang="ts">
import UserCard from './UserCard.vue' // import만 하면 템플릿에서 바로 사용 가능

const handleGreet = (msg: string) => {
  alert(msg)
}
</script>

<template>
  <!-- :props명="데이터", @emit명="핸들러함수" -->
  <UserCard name="이순신" :age="30" @greet="handleGreet" />
</template>
```

## 9. 컴포넌트 v-model 연동: defineModel (Vue 3.4+)
```vue
<!-- 커스텀 인풋 컴포넌트: MyInput.vue -->
<script setup lang="ts">
// 💡 defineModel 하나로 자식에서 props와 emit 선언 없이 부모의 v-model과 직결!
const text = defineModel<string>({ default: '' })
</script>

<template>
  <input v-model="text" class="custom-input" placeholder="여기에 입력..." />
</template>
```
```vue
<!-- 사용하는 부모 컴포넌트 -->
<script setup lang="ts">
import { ref } from 'vue'
import MyInput from './MyInput.vue'

const message = ref('안녕하세요')
</script>

<template>
  <!-- 부모의 message 변수와 자식 컴포넌트의 input이 양방향 동기화됨 -->
  <MyInput v-model="message" />
  <p>부모의 message: {{ message }}</p>
</template>
```

## 10. 생명주기 훅, DOM 참조 & 컴포저블 (실전 응용)
```vue
<script setup lang="ts">
import { ref, onMounted, onUnmounted, useTemplateRef } from 'vue'

// 1. 템플릿 DOM 직접 접근 (Vue 3.5+ useTemplateRef)
const myInput = useTemplateRef<HTMLInputElement>('inputRef')

// 2. 생명주기 훅: onMounted (화면이 브라우저에 마운트된 직후 1회 실행 - API 호출 시점)
onMounted(async () => {
  console.log('화면 준비 완료!')
  myInput.value?.focus() // 인풋에 자동 포커스
})

// 3. 생명주기 훅: onUnmounted (화면에서 컴포넌트가 사라질 때 타이머/이벤트 정리)
onUnmounted(() => {
  console.log('컴포넌트 종료: 메모리 정리')
})
</script>

<template>
  <input ref="inputRef" placeholder="자동 포커스 인풋" />
</template>
```
```typescript
// 💡 컴포저블 (Composables): 재사용 로직을 함수 파일로 깔끔하게 분리
// src/composables/useCounter.ts
import { ref } from 'vue'

export function useCounter(init = 0) {
  const count = ref(init)
  const inc = () => count.value++
  const dec = () => count.value--
  return { count, inc, dec }
}

// 사용 컴포넌트에서:
// const { count, inc } = useCounter(10)
```
💬
Vue 3 Composition API 치트시트

의견 및 질문

댓글 수정

댓글 삭제
