Vue 3 Compat Build로 Vue 2 프로젝트 안전하게 버전업

1. Compat build 개념 정리

전에 만든 샘플 프로젝트는 순수 Vue 2 + Router 3 + Vuex + Axios 구조입니다.

이번 글의 목표는 이 코드를 거의 손대지 않고, Vue 3 럳타임에서 돌아가게 올려보는 것입니다.

그때 사용하는 것이 Vue 3 Compat Build(@vue/compat)입니다.

한 줄로 정리하자면, Compat build는 Vue 3 엔진 위에서 Vue 2 문법을 최대한 그대로 돌려주는 호환 모드입니다.

 

특징을 정리하자면, 프로젝트는 vue@3를 사용하지만, 

템플릿/옵션 API/전역 API 등 Vue 2 스타일 코드 상당수를 그대로 허용하고,

Vue 3에서 제거 및 변경된 API를 쓰면 콘솔에 경고창을 띄워서 수정이 필요한 부분을 알려주며,

완전히 갈아엎기 전에 Vue 3에서 돌아가는지를 먼저 확인할 수 있는 안전장치 역알을 합니다.

이번 글에서는 Compat Build를 샘플 Vue2 프로젝트에 적용해보는 것이 목표입니다.

 

---

 

2. Vue CLI 프로젝트에 Compat Build 적용하기

Vue CLI 기반 프로젝트라면, 공식 CLI 플러그인으로 손쉽게 Vue 3 + compat을 적용할 수 있습니다.

프로젝트 루트에서 다음 명령을 실행합니다.

vue add vue-next

실행하면 몇 가지를 물어봅니다. 대표적인 선택지는 다음과 같습니다.

• Use the Vue 3 preview? → Yes
• Use the compat build? → Yes

이 플러그인은 내부적으로 다음 작업을 자동으로 해줍니다.

• vue 버전을 ^3.x로 올림
• @vue/compat, @vue/compiler-sfc 등 Vue 3 관련 패키지 설치
• webpack 설정에 vue → @vue/compat alias 추가
• SFC 컴파일 옵션에 compat 관련 설정 추가

즉, Vue 3 + compat 환경으로 프로젝트를 재구성해 줍니다.

 

---

 

3. main.js 코드 변화 확인

플러그인을 적용한 후 main.js를 열어보면, 보통 이런 형태로 바뀌어 있습니다.

// 이전(Vue 2) src/main.js
import Vue from 'vue'
import App from './App.vue'
import router from './rotuer'
import store from './store'

Vue.config.productionTip = false

new Vue({
	router,
    store,
    render: h => h(App)
}).$mount('#app')

// 플러그인 적용 후(Vue 3 compat) src/main.js
import { createApp } from 'vue'
import App from './App.vue'
import router from './rotuer'
import store from './store'

const app= createApp(App)

app.use(router)
app.use(store)

app.mount('#app')

• new Vue(...) → createApp(App)
• Vue.use(...) → app.use(...)
• 나머지 컴포넌트/라우터/Vuex/템플릿 코드는 그대로 둔 상태

즉, 런타임만 Vue 3 쪽으로 옮겨서 돌려보는 형태입니다.

만약 플러그인이 main.js를 자동으로 바꾸지 않았다면, 직접 위 패턴대로 수정하면 됩니다.

 

---

 

4. 빌드와 경고 확인

Compat Build가 제대로 적용되었는지 확인하기 위해 다시 dev 서버를 띄워 봅니다.

npm run serve

정상이라면 브라우저에서 로그인 → 대시보드 화면까지 Vue 2 때와 똑같이 동작해야 하고,

개발자 콘솔을 열면 Vue가 "You are running in Vue 2 compat mode" 류의 메시지를 보여줍니다.

Vue 2에서 deprecated된 API를 사용한 부분이 있다면,

[Vue warn]과 함게 "이 API는 Vue 3에서 제거되었으니 OO로 바꿔라"는 경고가 하나씩 뜹니다.

 

경고들을 고치기 이전에 화면이 이전과 동일하게 동작하는지 눈으로 확인하고,

콘솔 경고 목록을 쭉 스크롤 하면서 어느 컴포넌트에서 어떤 API를 얼마나 많이 쓰고 있는지 대략적인 감을 잡는 게 좋습니다.

 

---

 

5. 경고를 프로젝트 TODO로 옮기기

Compat Build의 중요한 역할은 자동 탐직기입니다.

경고 메시지는 대략 이런 식입니다.

• v-model 관련: "v-model on custom components is changed in Vue 3 ..."
• 필터 관련: "filters are removed in Vue 3 ..."
• 인스턴스 API: $on, $off, $once, $children 등 사용 경고

이런 경고를 보면서, 이전에 만들어둔 마이그레이션 체크리스트에 다음처럼 옮겨둡니다.

[템플릿 / v-model]
- Login.vue: input 컴포넌트에 커스텀 v-model 사용 → Vue 3 패턴으로 변경 필요

[필터]
- 없음 (경고 없음)

[인스턴스 이벤트]
- EventBus 사용 없음 (경고 없음)

샘플 프로젝트라서 경고가 많지 않을 수도 있지만,

실제 업무 프로젝트에서는 이 과정에서 어디서부터 손대야 하는지 우선순위가 확실히 드러납니다.

 

---

 

6. Compat Build를 언제까지 쓸까?

Compat Build는 영구적인 운영 모드가 아니라, 마이그레이션 기간 동안 쓰는 임시 다리에 가깝습니다.

실무 전략은 보통 이렇게 잡습니다.

1. Vue 2 → Vue 3 + Compat Build로 먼저 버전업
2. 콘솔 경고를 하나씩 없애면서 코드 리팩토링
3. 경고가 거의 없어진 시점에 Compat 모드를 끄고 순수 Vue 3 빌드로 전환

샘플 프로젝트 기준으로는 Compat Build를 유지한 채로 Router 4, Pinia를 적용하고

컴포넌트 일부를 Composition API로 전환할 것입니다.

그 이후 Compat 의존성을 걷어내는 연습을 할 것입니다.

 

---

 

정리

• Vue 2 샘플 프로젝트를 Vue 3 + Compat Build로 버전 업
  • vue add vue-next(또는 직접 @vue/compat 설정)
  • createApp(App) + app.use() 패턴으로 진입점 수정
• 기존 코드(로그인, Vuex, Axios, Router 3)가 그대로 동작하는지 확인
• 콘솔 경고를 읽고, 마이그레이션 TODO로 옮길 준비

 

---

 

출처

Vue 3 Migration Guide