Vue.js 3 컴포지션 API 기반 프론트엔드 프로젝트 구조 이해

Vue.js란 무엇인가

Vue.js는 사용자 인터페이스를 구축하기 위한 자바스크립트 프레임워크이다.

표준 HTML, CSS, JavaScript 위에 구축된 Vue는 선언적이고 컴포넌트 기반의 프로그래밍 모델을 제공하여 복잡한 UI도 효율적으로 개발할 수 있게 한다. Vue는 React나 Angular와 달리, 프로그레시브 프레임워크를 지향한다.

 필요한 기능만 점진적으로 채택할 수 있어 기존 프로젝트에 무리 없이 도입하기 쉽다.

Vue 3 버전에서는 컴포지션 API (Composition API)를 도입하여 상태와 로직을 보다 유연하게 구성할 수 있게 되었고,

성능과 개발자 경험 면에서도 여러 개선이 이루어졌다.

즉, Vue.js는 가볍지만 강력한 프론트엔드 프레임워크로, 뷰(View) 레이어를 중심으로 한 빠른 개발을 돕는다.

---

프론트엔드 프로젝트 디렉터리 구조

Vue.js로 프로젝트를 시작하면 일반적으로 frontend 디렉터리에 아래와 같은 구조를 갖추게 된다.

각 폴더와 파일은 역할에 따라 나뉘어 있어, 프로젝트 규모가 커져도 코드를 체계적으로 관리할 수 있게 한다.

frontend/ (프로젝트 루트)
├─ public/               # 정적 파일 및 HTML 템플릿 위치
│   └─ index.html        # 애플리케이션 진입점이 되는 기본 HTML
└─ src/                  # 소스 코드 디렉터리
    ├─ main.js           # 애플리케이션 진입 JS 파일 (Vue 앱 생성 및 플러그인 등록)
    ├─ App.vue           # 최상위 Root 컴포넌트
    ├─ components/       # 재사용 가능한 Vue 컴포넌트들
    ├─ views/            # 화면 단위 컴포넌트 (페이지 컴포넌트)
    ├─ router/           # Vue Router 설정 (라우트 매핑 정의)
    ├─ store/            # 상태 관리 스토어 (Pinia 등 상태 관리 모듈들)
    ├─ composables/      # 컴포지션 API로 작성한 재사용 로직 (훅/유틸 함수)
    ├─ assets/           # 정적 자산 (이미지, CSS, 폰트 등)
    └─ ... 기타 환경설정 파일 (.env 등) 및 폴더 (예: utils/, plugins/, tests/)

 

• public/: 빌드되지 않은 정적 자원을 두는 곳이다. index.html 파일은 단일 페이지 애플리케이션의 기본 HTML 틀로서, Vue로 생성한 애플리케이션이 이 HTML 내 #app 등의 DOM 엘리먼트에 마운트된다. 이 폴더는 주로 파비콘이나 특정 정적 파일을 둘 때 사용하며, Vue CLI나 Vite 기반 프로젝트에서 기본 제공된다.
• src/main.js: 애플리케이션 진입 스크립트 파일이다. 여기서 Vue 어플리케이션을 생성(createApp)하고, 라우터와 스토어(Pinia) 등의 플러그인을 등록한 뒤 #app 엘리먼트에 마운트한다. 예를 들어, Pinia를 사용할 경우 import { createPinia } from 'pinia'로 Pinia 인스턴스를 만들고 app.use(createPinia())로 앱에 주입하며, 라우터도 app.use(router)로 등록한 뒤 app.mount('#app')으로 초기화한다.
• src/App.vue: 애플리케이션의 루트 컴포넌트이다. 보통 최상위 레이아웃 역할을 하며, <router-view>를 포함하여 라우트에 따라 변하는 화면을 표시한다. 모든 컴포넌트의 공통 조상이므로 전역 스타일이나 애플리케이션 전반의 레이아웃을 여기서 정의한다.
• src/components/: 재사용 가능한 Vue 컴포넌트를 모아두는 디렉터리이다. 예를 들어 버튼, 카드, 모달 창 같은 UI 요소들을 컴포넌트로 만들어 이 폴더에 넣는다. 컴포넌트는 필요할 때마다 임포트하여 사용하며, 다른 컴포넌트나 뷰에서 조합되어 화면을 구성한다. 일반적으로 하나의 .vue 파일이 하나의 컴포넌트를 표현한다.
• src/views/ (혹은 pages/): 화면 단위 컴포넌트를 위한 디렉터리이다. 뷰 컴포넌트는 라우터와 매핑되어 하나의 페이지(화면)을 구성한다. 예를 들어 Home.vue, Login.vue, Dashboard.vue 같은 파일이 여기에 위치하며, 각각 애플리케이션의 라우트(route)와 연결되어 있다. 뷰 컴포넌트 내부에서는 여러 재사용 컴포넌트(components/ 폴더의 내용)를 조합하여 하나의 완성된 화면을 구현한다.
• src/router/: Vue Router 설정 파일들을 포함한다. 일반적으로 index.js 혹은 index.ts 파일에 경로별 컴포넌트 매핑을 정의한다. 예를 들어 '/login' 경로에 Login.vue 컴포넌트를 표시하도록 라우트를 설정하고, 히스토리 모드 여부, 글로벌 네비게이션 가드 등을 여기서 설정한다. main.js에서 이 라우터 인스턴스를 불러와 앱에 등록하여 사용한다.
• src/store/: 전역 상태 관리를 위한 스토어 모듈들을 모아놓은 폴더이다. Vue 3 기준으로는 공식 상태 관리 라이브러리인 Pinia를 주로 사용하며, 각 스토어를 별도의 파일로 정의한다. (Vue 2의 Vuex를 사용한다면 유사한 구조로 store/index.js에서 스토어를 생성했겠지만, Pinia에서는 보통 각 스토어 파일별로 defineStore를 사용하고 main.js에서 Pinia를 플러그인으로 등록한다.) 이 디렉터리에는 예를 들어 auth.js (인증 관련 상태), todo.js (할 일 목록 상태) 등 여러 개의 상태 모듈을 파일별로 정의할 수 있다. 스토어를 활용하면 애플리케이션 전역에서 공유되는 상태를 체계적으로 관리할 수 있다.
• src/composables/: Vue 3 컴포지션 API로 작성된 재사용 가능한 로직을 모은 폴더이다. 컴포넌트 간에 공통으로 쓰이는 코드(예: 데이터 페칭, 폼 핸들링 등)를 훅(hook) 형태로 추상화한 컴포저블(composable) 함수를 여기에 작성한다. 관례상 useSomething.js처럼 파일명을 짓는다 (예: useAuth.js는 인증 관련 상태나 함수를 제공). 이렇게 분리하면 로직을 쉽게 공유할 수 있고, 컴포넌트의 가독성도 높아진다.
• src/assets/: 이미지, 폰트, 글로벌 CSS 등 정적 자원을 저장하는 폴더이다. Webpack이나 Vite 등 빌드 도구에 의해 처리되는 자산 경로이므로, 이 폴더에 넣은 파일들은 빌드시 번들에 포함되거나 복사된다. 예컨대 로고 이미지 logo.png나 공통 스타일시트 styles.css 등을 이곳에 둘 수 있다. .vue 파일 안에서 @/assets/... 경로나 상대경로로 참조하면 빌드 시 적절히 처리된다.
• 기타 폴더: 규모에 따라 추가적인 폴더를 구성하기도 한다. 예를 들어 plugins/ 폴더는 전역으로 사용하는 Vue 플러그인 초기화 코드 (예: axios 인스턴스 설정, i18n 국제화 설정 등)를 넣는 곳이다v. utils/ 폴더는 범용 유틸리티 함수나 헬퍼를 모아놓는 곳으로 사용된다. 테스트를 작성한다면 tests/ 폴더 아래에 unit 또는 e2e 폴더를 두어 단위 테스트와 종단간 테스트 코드를 관리한다. 프로젝트가 매우 커질 경우 Atomic Design 방식이나 도메인 별 모듈 폴더로 세분화하기도 하지만, 기본적으로는 위와 같은 구조를 토대로 필요에 따라 폴더를 추가/정리한다.

---

RESTful API 연동과 비동기 요청 처리 (axios)

현대적인 프론트엔드 개발에서 Vue 애플리케이션은 RESTful API를 통해 백엔드 서버와 데이터 통신을 한다.

RESTful API는 HTTP 프로토콜을 활용하여 자원을 CRUD할 수 있는 엔드포인트를 제공하는 웹 API 방식이다.

Vue에서는 이러한 API 호출을 위해 주로 axios 라이브러리를 사용한다.

axios는 브라우저와 Node.js 모두에서 동작하는 Promise 기반 HTTP 클라이언트로,

프론트엔드 자바스크립트 애플리케이션에서 간편하게 AJAX 요청을 보낼 수 있게 해준다.

axios를 이용하면 GET, POST 같은 HTTP 메서드로 백엔드 REST 엔드포인트에 요청을 보내고,

응답 데이터를 Promise 형태로 받아올 수 있다.

즉, axios를 통해 클라이언트에서 CRUD 작업에 대응하는 HTTP 요청을 보내고

RESTful 엔드포인트로부터 데이터를 주고받을 수 있다.

 

Vue 3 컴포지션 API 환경에서는 axios를 통합하기가 매우 수월하다.

컴포넌트의 <script setup> 영역이나 setup 함수 내에서 필요한 곳에 단순히 import axios from 'axios'로 불러와 사용할 수 있다. axios의 호출은 비동기로 이루어지므로 Promise를 반환하며,

async/await 구문을 활용하면 동기 코드처럼 작성할 수 있어 가독성이 좋다.

또한 API 호출 중 에러가 발생할 수 있으므로 예외 처리를 위한 try...catch를 사용하는 것이 일반적이다.

 

예를 들어, 컴포지션 API 기반 컴포넌트에서 onMounted 훅을 사용해 초기 데이터 로드를 수행하고,

버튼 클릭 등 이벤트에 따라 추가 요청을 보내는 코드를 작성할 수 있다.

아래는 axios를 이용하여 데이터를 가져오는 컴포넌트의 기본적인 예시이다:

<script setup>
import { ref, onMounted } from 'vue'
import axios from 'axios'

const items = ref([])         // 가져온 데이터 배열
const error = ref(null)       // 에러 상태 저장

// 데이터 불러오기 함수
const fetchItems = async () => {
  try {
    // REST API GET 요청 (예시 URL)
    const response = await axios.get('/api/items')
    items.value = response.data   // 응답 데이터를 상태에 저장
  } catch (err) {
    error.value = err            // 에러 발생 시 에러 정보 저장
  }
}

// 컴포넌트가 마운트될 때 API 호출 실행
onMounted(() => {
  fetchItems()
})
</script>

<template>
  <div v-if="error">
    에러 발생: {{ error.message }}
  </div>
  <ul v-else>
    <li v-for="item in items" :key="item.id">
      {{ item.name }}
    </li>
  </ul>
</template>

 

위 코드에서는 onMounted 훅 내부에서 fetchItems() 함수를 호출하여

컴포넌트가 화면에 나타날 때 자동으로 GET 요청을 보내도록 한다.

axios.get으로 받은 응답 데이터(response.data)를 items 상태에 넣고, 에러가 발생하면 error 상태에 에러 정보를 기록한다.

이렇게 불러온 items는 <template>에서 리스트 렌더링(v-for)을 통해 화면에 출력되고,

error 상태가 있으면 에러 메시지를 표시하도록 했다.

이처럼 axios를 컴포넌트 내에서 직접 사용하면 필요할 때마다 손쉽게 백엔드와 통신할 수 있다.

프로젝트 규모가 커지면 API 호출 로직을 모듈화하는 것도 고려한다.

예를 들어 src/plugins/axios.js 파일을 만들어 axios 기본 설정(기본 URL, 공통 헤더 등)을 정의하고

애플리케이션에 플러그인으로 등록할 수 있다.

혹은 src/composables/useApi.js 같은 컴포저블에 axios 호출 함수를 모아둘 수도 있다.

하지만 소규모 프로젝트나 개별 컴포넌트 수준에서는 위 예시처럼 컴포넌트에서 바로 axios를 불러와 사용하는 것으로 충분하다.

---

Vue에서의 상태 관리 (Pinia)와 상태 공유 구조

애플리케이션 규모가 커짐에 따라 컴포넌트 간에 공유해야 하는 상태(state)가 많아지면,

효율적인 상태 관리(state management)가 필요하다. Vue 3에서는 공식 권장 상태 관리 도구로 Pinia를 사용한다.

Pinia는 Vue의 상태 관리 라이브러리로, 여러 컴포넌트나 페이지 간에 전역 상태를 공유할 수 있도록 도와준다.

쉽게 말해, 개별 컴포넌트의 지역 상태(data)만으로 관리하기 어려운

사용자 정보, 인증 상태, 장바구니 내용 등 전역적인 데이터를 한 곳에서 관리하고 어느 곳에서나 접근할 수 있게 하는 것이다.

Pinia의 스토어(store)는 컴포넌트 트리에 속하지 않는 독립적인 객체로, 전역 상태와 비즈니스 로직을 담고 있다.

이를 일종의 항상 존재하는 숨은 컴포넌트라고 볼 수도 있는데, 모든 컴포넌트가 이 스토어에 접근하여 상태를 읽거나 쓸 수 있다.

스토어에는 세 가지 주요 개념이 있다:

state(상태 데이터), getters(상태로부터 계산된 값, 즉 파생 상태), actions(상태를 변경하는 함수, 비즈니스 로직).

이들은 각각 Vue 컴포넌트의 data, computed, methods에 대응되며 작동 방식도 유사하다.

정리하면, Pinia 스토어는 전역 공통 상태를 보관하고 관리하는 하나의 모듈이며,

여러 컴포넌트가 그 상태를 신뢰원(source of truth)으로 삼아 공유하는 구조를 갖는다.

Pinia를 프로젝트에 도입하려면, 먼저 pinia 패키지를 설치한 후 진입 파일(main.js)에서 Pinia를 생성하여 앱에 등록해야 한다.

Vue 앱 생성 시 createPinia()로 스토어 인스턴스를 만들고 app.use(pinia)로 적용하면 설정 완료이다.

이렇게 하면 앱 전역에서 Pinia를 사용할 준비가 된다.

이제 구체적인 상태 관리는 스토어 모듈을 정의함으로써 이루어진다.

Pinia에서는 개별 스토어를 정의하기 위해 defineStore 함수를 사용한다.

한 스토어는 하나의 상태 모듈에 해당하며, 고유한 ID(이름)을 가져야 한다.

다음은 Pinia를 사용해 간단한 카운터(counter) 스토어를 정의하는 코드 예제이다:

// src/store/counter.js
import { defineStore } from 'pinia'

export const useCounterStore = defineStore('counter', {
  // state: 전역에서 공유할 상태를 선언
  state: () => ({
    count: 0,
    name: 'default'
  }),
  // getters: 상태를 활용하여 계산된 값을 가져오는 속성
  getters: {
    doubleCount: (state) => state.count * 2,        // count의 2배 값을 반환
    welcomeMessage: (state) => `Hello, ${state.name}` // 상태 name을 활용한 문자열
  },
  // actions: 상태를 변경하는 메서드 (비즈니스 로직 포함 가능)
  actions: {
    increment() {
      this.count++    // this를 통해 state에 접근하여 변경
    },
    setName(newName) {
      this.name = newName  // 상태 속성 업데이트
    }
  }
})

위 코드에서는 'counter'라는 ID를 가진 스토어를 정의했다.

state는 함수 형태로 초기 상태 객체를 반환하며, 여기서는 count와 name 두 개의 속성을 가지고 있다.

getters는 현재 상태를 입력으로 받아 계산된 값을 반환하는 속성들을 정의한다.

예를 들어 doubleCount는 현재 count의 2배 값을 계산하고, welcomeMessage는 name을 이용해 환영 메시지를 만든다.

actions에는 상태를 변화시키는 함수들을 정의하는데,

increment()는 count를 1 증가시키고, setName(newName)은 name 상태를 주어진 값으로 변경한다.

Pinia의 actions 안에서는 this를 통해 해당 스토어의 상태에 접근하며,

비동기 작업이나 여러 상태 변경을 포함한 복잡한 로직도 넣을 수 있다.

이렇게 정의된 Pinia 스토어는 컴포넌트에서 자유롭게 활용할 수 있다.

사용하고자 하는 컴포넌트의 <script setup>에서 해당 스토어를 임포트하고(useCounterStore 함수 자체를 가져옴),

호출하여 스토어 인스턴스를 받는다. 예를 들면:

<script setup>
import { useCounterStore } from '@/store/counter'

const counterStore = useCounterStore()   // 스토어 인스턴스 생성 (전역에서 하나 공유됨)

// 스토어 상태 활용
console.log(counterStore.count)          // 현재 count 출력
counterStore.increment()                // 액션 호출로 상태 변경
counterStore.setName('Vue')             // name 상태를 'Vue'로 변경
</script>

<template>
  <p>Count: {{ counterStore.count }}</p>
  <p>Double: {{ counterStore.doubleCount }}</p>
  <p>{{ counterStore.welcomeMessage }}</p>
</template>

위와 같이 useCounterStore()를 호출하면 해당 스토어의 독립적인 인스턴스를 받는다.

Pinia에서는 이 인스턴스가 애플리케이션 전역에서 싱글톤(singleton)으로 관리되므로,

어떤 컴포넌트에서 불러도 모두 동일한 하나의 전역 상태 객체를 참조하게 된다.

따라서 한 컴포넌트에서 counterStore.increment()로 count를 증가시키면,

다른 컴포넌트에서 사용하는 counterStore.count 값도 즉시 증가한 값으로 반영된다.

이처럼 Pinia를 이용하면 여러 컴포넌트가 동일한 상태를 공유하고 실시간으로 반영할 수 있으며,

상태 변경 추적이나 디버깅도 Vue DevTools와 연동되어 수월해진다 (Pinia는 시간 여행 디버깅, 핫 리로딩 등도 지원한다).

정리하면, Vue 3 컴포지션 API 기반 프로젝트에서 Pinia로 전역 상태를 관리하면 구조적인 상태 공유가 가능하다.

컴포넌트들은 필요할 때 각자 스토어를 불러와 상태를 읽거나 갱신하고,

이러한 상호 작용을 통해 애플리케이션 전체의 일관된 데이터 흐름을 유지한다.

이는 규모가 커졌을 때 데이터 동기화 문제를 줄이고, 코드의 유지보수성을 높여준다.

 

Pinia에 대한 더 상세한 정보는 다음 게시글인 'Vue.js의 상태 관리 도구 : Pinia'를 확인하면 된다.

Vue.js의 상태 관리 도구 : Pinia

 

---

컴포지션 API 기반 코드 구현 예시 정리

마지막으로, 앞서 설명한 개념들을 컴포지션 API 관점에서 요약하면 다음과 같다.

Vue 3에서는 Options API 대신 Composition API를 활용하여 상태와 로직을 구성하며,

이는 코드의 모듈화와 재사용성을 높여준다. 컴포지션 API 환경에서 REST API 연동과 상태 관리는 다음과 같은 구조로 구현된다:

• Axios를 이용한 API 호출: 컴포넌트의 setup() 함수 내(혹은 <script setup> 블록)에서 axios를 임포트하여 바로 사용한다. onMounted 훅을 통해 초기 데이터 로드를 수행하고, 필요에 따라 methods나 이벤트 핸들러 내부에서 axios.get/post 등을 호출하여 비동기 요청을 보낸다. Promise 기반 호출이므로 async/await을 사용해 응답을 처리하고, 에러는 try-catch로 잡는다. 이러한 API 통신 로직은 컴포넌트에 직접 작성하거나, 여러 컴포넌트에서 쓰인다면 composables/ 폴더의 공통 훅으로 분리할 수 있다. (예: useFetch.js에 fetchItems 함수를 작성하고 각 컴포넌트에서 이를 호출).
• Pinia를 이용한 전역 상태 관리: 애플리케이션 시작 시 main.js에서 Pinia를 등록하고, 각 스토어는 src/store/ 디렉터리의 개별 파일로 정의한다. defineStore로 선언된 스토어는 필요한 컴포넌트에서 useStore() 형태로 불러와 사용한다. 컴포넌트 내에서 Pinia 스토어를 사용할 때도 Composition API 문법을 그대로 활용한다. 예를 들어 <script setup>에서 const userStore = useUserStore()로 스토어를 가져오고, 그 안의 state나 getters를 바로 참조하거나 actions를 호출하면 된다. 이렇게 하면 여러 컴포넌트가 하나의 userStore 인스턴스를 공유하므로, 한쪽에서 상태를 변경하면 다른 컴포넌트에도 변경사항이 반영된다. Pinia를 통해 애플리케이션 전반에 걸친 일관성 있는 상태 공유가 이루어지며, 컴포넌트 간 prop 전달이나 이벤트 버스 없이도 편리하게 데이터를 주고받을 수 있다.

위에서 살펴본 구조와 예시 코드를 기반으로,

Vue.js 3 프로젝트를 구성하면 초보 개발자도 실무 수준의 프로젝트 구조를 이해하고 구현할 수 있다.

프론트엔드 디렉터리를 기능별로 나누고,

컴포지션 API의 장점을 활용해 클린하고 유지보수하기 쉬운 코드를 작성하는 것이 핵심이다.

Vue.js의 유연한 컴포넌트 시스템, axios를 통한 손쉬운 API 연동, Pinia의 효율적인 상태 공유를 조합하면,

작은 인터페이스부터 복잡한 SPA에 이르기까지 견고한 구조를 갖춘 프론트엔드 애플리케이션을 만들어낼 수 있다.

---

요약

Vue.js는 가볍고 유연한 컴포넌트 기반 프레임워크이며,
Vue 3에서는 컴포지션 API 도입으로 로직 재사용성과 상태 관리의 유연성이 강화되었다.
프로젝트 구조는 src/ 디렉터리를 중심으로
components, views, router, store, composables, assets 등으로
분리하여 유지보수성을 높이는 것이 핵심이다.
RESTful API 통신은 axios를 사용해 간단하게 비동기 요청을 처리할 수 있으며,
Pinia를 활용하면 전역 상태를 안전하고 일관되게 공유할 수 있다.
이러한 구조를 기반으로 Vue 프로젝트를 설계하면 작은 앱부터 대규모 SPA까지
확장 가능한 프론트엔드 아키텍처를 구현할 수 있다.

 

---

참고 자료

• Vue.js 공식 문서 : ko.vuejs.org
• Vue FAQ 자료 : vue-faq.orgvue-faq.org
• LogRocket 블로그 : blog.logrocket.comblog.logrocket.com
• Pinia 공식 문서 : pinia.vuejs.orgpinia.vuejs.org 등.