---
category: Unified
tags: [auto-wikified, technical-documentation]
title: Composition API
description: "Vue 3의 Composition API는 작고 독립적인 단위로 애플리케이션의 복잡한 로직을 구성할 수 있게 해주는 API 모음이다."
last_updated: 2026-05-02
---

# Composition API

## 📌 Brief Summary
Vue 3의 Composition API는 작고 독립적인 단위로 애플리케이션의 복잡한 로직을 구성할 수 있게 해주는 API 모음이다. 기존 Options API가 데이터나 메서드 등 옵션 타입별로 코드를 분리했던 것과 달리, 기능적 논리 단위별로 관련된 코드를 그룹화할 수 있게 해준다. 이를 통해 상태 저장 로직(Stateful logic)을 캡슐화하고 재사용하는 '컴포저블(Composable)' 패턴을 구현하여, 대규모이거나 빠르게 성장하는 애플리케이션에서 높은 유지보수성과 확장성을 제공한다.

## 📖 Core Content
*   **로직의 캡슐화와 재사용 (Composables 패턴)**
    Composition API를 활용하면 상태 기반 로직을 '컴포저블'이라는 독립적이고 재사용 가능한 함수로 추출할 수 있다. 마우스 위치 추적, 비동기 데이터 패칭(`useFetch`), 윈도우 크기 조정 등 시간에 따라 변하는 상태를 관리하는 로직을 여러 컴포넌트 간에 충돌 없이 공유할 수 있다. 과거 Options API에서 사용하던 Mixins의 한계(네임스페이스 충돌, 암묵적 의존성)를 완벽히 해결한다.
*   **기능 중심의 코드 구조화**
    기존 Options API에서는 특정 기능과 관련된 로직이 `data()`, `methods()`, `created()` 등으로 흩어져 있어 컴포넌트가 거대해질수록 파악하기 어려웠다. Composition API는 단일 기능과 관련된 모든 로직을 한 곳에 모을 수 있어 가독성을 높이고 디버깅 및 코드 추출을 용이하게 한다.
*   **TypeScript와의 강력한 통합**
    Composition API는 네이티브 수준의 TypeScript 지원을 제공한다. 기존 방식보다 보일러플레이트 코드가 적고, 변수나 함수에 대한 강력한 타입 추론과 제네릭 지원을 통해 훨씬 안정적인 개발자 경험(DX)을 선사한다.
*   **컴포저블 작성 베스트 프랙티스**
    *   **명명 규칙**: 컴포저블 함수명은 `use`로 시작해야 한다 (예: `useMouse`).
    *   **입력 매개변수 유연성**: 일반 값뿐만 아니라 `ref`나 `getter` 함수도 입력받을 수 있도록 설계하며, 내부에서 `toValue()`를 사용해 처리하는 것이 권장된다.
    *   **반환 값 처리**: 반환 객체를 구조 분해 할당(Destructuring)할 때 반응성을 잃지 않도록, `reactive` 객체가 아닌 여러 개의 `ref`를 포함하는 일반(plain) 객체를 반환해야 한다.
    *   **부수 효과(Side Effects) 관리**: `<script setup>` 또는 `setup()` 내부에서 동기적으로 호출해야 하며, `onMounted()`에서 DOM 이벤트 리스너 등을 등록하고 `onUnmounted()`에서 반드시 정리(Clean-up)해야 한다.
*   **현대 Vue 생태계의 표준**
    Nuxt 3, Pinia, Vue Router 4, VueUse 등 최신 Vue 생태계의 핵심 도구들은 Composition API를 기본 전제로 설계되어 있어 원활한 통합을 제공한다.

## ⚖️ Trade-offs & Caveats
*   **자유도에 따른 파편화 위험**: 코드를 조직하는 방식에 대한 강제성이 적다. 따라서 팀 내에 엄격한 컨벤션(예: ESLint 규칙, 명명 규칙, 계층화된 디렉토리 구조)이 없다면, 개발자마다 다른 방식으로 로직을 구현하여 코드가 혼란스러워질 수 있다. 너무 많은 로직을 `setup()` 내부에 방치하면 오히려 유지보수가 어려워진다.
*   **반응성(Reactivity) 객체의 함정**: 초보자의 경우 `ref()`와 `reactive()`의 사용 기준에 혼란을 겪기 쉽다. 특히, 반응형 객체의 프로퍼티를 일반적인 방식으로 구조 분해 할당하면 반응성이 끊어지므로 `toRefs()`나 `storeToRefs()`를 반드시 사용해야 하며, `ref`에 접근할 때 `.value`를 붙이는 것을 잊는 실수가 잦다.
*   **러닝 커브 상승**: Options API가 초보자 친화적이었던 반면, Composition API는 JavaScript의 클로저(Closures), 반응성 동작 원리, 함수 스코프에 대한 깊은 이해를 요구한다. 따라서 주니어 개발자 위주의 팀이나 구조가 단순한 프로젝트에서는 오히려 생산성을 저하시킬 수 있다.
*   **기존 Options API와의 혼용 제약**: 컴포저블은 `setup()` 내부에서만 완벽히 동작한다. 기존 Options API 기반의 컴포넌트(`data()`, `created()` 등)에서 `VueUse`나 `Pinia` 같은 최신 도구를 사용하려면 중복된 상태를 만들거나 부자연스러운 연결(glue) 코드를 작성해야 하는 하이브리드 상태의 고통(Hybrid Pain)이 따른다.

## 🔗 Knowledge Connections

### Related Concepts

#### [아키텍처/기반 기술]
- [[Composables]]
  - 연결 이유: Composition API를 활용해 상태 유지 로직을 캡슐화하는 핵심 소프트웨어 설계 패턴이다.
  - 이 개념을 통해 더 깊게 이해할 수 있는 부분: 상태를 가지는 로직과 순수 함수의 분리, 단일 책임 원칙에 기반한 프론트엔드 모듈화 전략.
- [[Options API]]
  - 연결 이유: Composition API가 대체하거나 보완하고자 하는 이전 Vue의 기본 문법이자 비교 대상이다.
  - 이 개념을 통해 더 깊게 이해할 수 있는 부분: 프레임워크의 진화 과정, 소규모 프로젝트와 대규모 프로젝트에 각각 적합한 API 선택 기준 및 점진적 마이그레이션(Migration) 전략.
- [[React Hooks]]
  - 연결 이유: Composition API의 설계에 큰 영감을 준 React의 논리 합성 패턴이다.
  - 이 개념을 통해 더 깊게 이해할 수 있는 부분: 상태 변경 시 전체가 재실행(Re-render)되는 React Hooks와, `setup()`에서 한 번만 실행되며 프록시(Proxy) 기반으로 추적하는 Vue의 실행 모델(Execution Model) 차이.

#### [구현/활용 도구]
- [[Pinia]]
  - 연결 이유: Composition API를 기반으로 설계된 Vue 3의 공식 상태 관리 라이브러리로, Vuex를 대체한다.
  - 이 개념을 통해 더 깊게 이해할 수 있는 부분: 컴포저블 스토어 패턴을 통한 전역 상태 관리 및 Mutations 없이 상태를 다루는 현대적인 상태 정규화(Normalization) 기법.
- [[VueUse]]
  - 연결 이유: Composition API를 활용해 200개 이상의 유틸리티를 구현한 오픈소스 컴포저블 컬렉션이다.
  - 이 개념을 통해 더 깊게 이해할 수 있는 부분: 브라우저 API, 센서, 상태 동기화 등을 추상화하는 실전 컴포저블 구현 모범 사례.

### Deeper Research Questions
- Composition API의 프록시(Proxied refs) 기반 반응성 모델은 React Hooks의 실행 모델과 비교하여 렌더링 최적화 측면에서 어떤 근본적인 차이를 만들어내는가?
- 대규모 엔터프라이즈 환경에서 Composition API로 로직을 캡슐화할 때, 도메인 주도 설계(DDD) 관점에서 기능 중심 모듈화(Feature-based architecture)를 어떻게 설계할 수 있는가?
- 상태 저장 로직을 재사용하고자 할 때, 렌더리스 컴포넌트(Renderless Components) 패턴과 컴포저블(Composables) 패턴 중 인스턴스 오버헤드와 UI 렌더링 제어권 측면에서 어느 것을 선택해야 하는가?
- 기존 Options API로 작성된 거대한 레거시 컴포넌트를 Composition API로 점진적으로 리팩토링할 때(Hybrid 상태), 부작용과 코드 중복을 최소화하는 전략은 무엇인가?
- 대규모 리스트나 복잡한 상태 트리를 다룰 때, 반응성 오버헤드를 줄이기 위해 `shallowRef`나 `v-memo`와 같은 고급 최적화 기법을 어떻게 적용해야 하는가?

### Practical Application Contexts
- **Implementation:** 비동기 데이터 로딩(`useFetch`), 윈도우 사이즈 추적(`useWindowSize`), 모달 상태 관리 등 여러 UI 컴포넌트에서 반복되는 로직을 단일 함수로 분리하여 작성할 때 구현된다.
- **System Design:** 컴포넌트 트리를 구성할 때, UI 레이어(Template)와 비즈니스 로직 레이어(Composable)를 명확히 격리하여 각 컴포넌트가 프레젠테이셔널(Presentational) 역할을 수행하도록 돕는 기반 구조로 작동한다.
- **Operation / Maintenance:** 관련된 로직이 단일 함수로 응집되므로, UI 렌더링 환경 없이도 비즈니스 로직만 별도로 단위 테스트(Unit Testing)하기 쉬워져 유지보수성이 대폭 향상된다.
- **Learning Path:** Vue의 기초 문법을 익힌 뒤, `ref`와 `reactive`의 동작 원리인 반응성 시스템을 공부하고, VueUse 라이브러리의 소스 코드를 읽으며 우수한 컴포저블 작성 컨벤션을 학습하는 경로로 이어진다.
- **My Project Relevance:** 컴포넌트의 크기가 비대해져 코드 파악이 어렵거나(Giant Component 현상), 동일한 상태 관리 로직을 여러 뷰(View)에서 복사-붙여넣기로 사용하고 있는 경우 이를 리팩토링하는 핵심 솔루션이 될 수 있다.

### Adjacent Topics
- [[Renderless Components]]
  - 확장 방향: 자체 템플릿(Markup)을 가지지 않고 상태와 로직만 하위 스코프 슬롯(Scoped Slots)으로 전달하는 또 다른 뷰 로직 재사용 패턴으로, Composition API의 대안적 접근법을 이해할 수 있다.
- [[Vue 3 Reactivity System]]
  - 확장 방향: 프록시(Proxy) 기반으로 작동하는 `ref`, `reactive`, `watchEffect`의 내부 원리와 의존성 추적(Dependency tracking) 메커니즘을 심도 있게 탐구할 수 있다.

---
*Last updated: 2026-05-02*