[Vue.js] Vue2 탈출기: Vue3 마이그레이션 가이드

이전 글에 이어서 Vue2.7 upgrade + Vite 적용 Vue3로 성공적으로 업그레이드 했습니다..! 

Vue2 에서 Vue3로 업그레이드하는 거는 금방이지만, 그에 맞춰 종속된 라이브러리들을 Vue3에 맞게 리팩토링하는게 더 오래 걸린 것 같아요.

하면서 중간중간 기획개발도 같이 진행하고, QA도 진행하면서 수정개발하니 커밋 기록상 진행 일자는 아래와 같습니다. 

🗓️ 처음 시작일 : 2024년 9월 3일 

🗓️ 마지막 QA 수정 개발 완료 : 2024년 10월 4일

실 md 는 대략 2주정도? 인 것 같네요

 

 

이제 앞으로 장기적인 리팩토링을 진행해야 합니다. 틈틈히 진행해야 할 것 같아요 

vue3 로 가면서 맞춰가야할 사항 (장기적인 목표)
▫️Composition API + SFC 구조 [script setup]
▫️composables
▫️폴더 구조 재정립
▫️pinia + api 재사용성 형태 변경 필요
▫️✚ prettier + eslint 설정
▫️✚ tailwind css+ + ui library
▫️✚ typescript
▫️✚ storybook

 

 

 

아래는 Vue2 에서 Vue3 로 완벽히 마이그레이션 하는 과정을 단계별로 작성하였습니다. 도움이 되시길 바랍니다 ~.~ 

 

 

 

 

 

🐕 🐈 🐕 🐈 🐕 🐈 🐕 🐈

 

 

 

 

 

🎢 작업 내용

---

⚡️ Vue 버전 업데이트  (^3.1.0) 

⚡️ Vue 마이그레이션 빌드 @vue/compat  → 추후 삭제 !

• @vue/compat(일명 "마이그레이션 빌드")은 Vue 2의 동작이 호환되는 구성을 제공하는 Vue 3의 빌드입니다.

https://www.vuemastery.com/blog/vue-3-migration-build/#what-is-a-migration-build

 

마이그레이션 빌드는 기본적으로 Vue 2에서 실행되며, 몇 가지 예외 케이스말고는 왠만한 공통 APIs는 Vue 2와 동일하게 사용합니다. Vue 3에서 변경되었거나 더이상 지원되지 않는 기능을 사용하면 런타임 경고가 발생합니다.

즉, 이 패키지는 Vue 2와 Vue 3를 모두 지원할 수 있으며, 프로덕션용이 아니기 때문에 앱을 변환하는 동안에만 사용해야 합니다.

 

yarn add @vue/compat

 

 

 

vite.config.js

export default {
  resolve: {
    alias: {
      vue: '@vue/compat'
    }
  },
  plugins: [
    vue({
      template: {
        compilerOptions: {
          compatConfig: {
            MODE: 2
          }
        }
      }
    })
  ]
}

 

 

 

 

 

⚡️ vue-template-compiler → @vue/compiler-sfc@^3.1.0 로 교체

yarn add @vue/compiler-sfc

 

 

Package.json

"dependencies": {
  "vue": "^2.7.14", 👈 delete!
  "vue": "^3.1.0", 👈 add!
  "@vue/compat": "^3.1.0" 👈 add!
   ...
},
"devDependencies": {
  "vue-template-compiler": "^2.6.14" 👈 delete!
  "@vue/compiler-sfc": "^3.1.0" 👈 add!
}

 

 

 

⚡️Vuex v4 upgrade

Vuex는 이제 더 이상 사용되지 않는 라이브러리로 간주되어 Pinia로 대체되었습니다.

추후에 공식 상태 관리 라이브러리인 pinia 로 리팩토링 할 예정이며, 빠르게 대체하기 위해 Vuex4로 업데이트 하였습니다.

 

 

⚡️main.js 코드 수정

기존에 Vue 생성자 함수를 사용하는 대신에, createApp() 함수를 사용합니다.

import { createApp } from "vue";
const app = createApp(App);
...
// Vue 인스턴스 생성
app.mount("#app");

 

 

 

⚡️ 호환성 모드 활성화 [24.12.12 추가사항]

브라우저 네트워크 창을 켜보면, 콘솔창에 아래와 같은 에러가 나타납니다.

 

 

main.js

import { createApp } from "vue";
import { configureCompat } from "vue"; 👈 add!
// 호환성 모드 활성화
configureCompat({ INSTANCE_CHILDREN: true }); 👈 add!
const app = createApp(App);
app.mount("#app");

Vue 2 스타일 코드가 여전히 사용되고 있다면, Vue 3의 호환성 모드를 활성화해야 합니다. main.js에서 다음과 같이 설정할 수 있습니다.

해당 코드를 넣어줘야 Vue 2 방식 코드가 오류를 발생시키지 않고 동작해주기 때문에 점진적으로 Vue 3로 코드 전환을 진행하는 데 유용합니다.

 

 

 

 

⚡️ 글로벌 함수 전역 등록 (Global API -> Instance API)+ vue3 용 코드로 리팩토링

• filters.js

: 글로벌 필터

전역적으로 등록된 필터를 앱 전체에서 사용하는 경우, globalProperties 를 통해 모든 구성 요소에서 글로벌 필터를 사용할 수 있도록 할 수 있습니다 .

https://vuejs.org/api/application.html#app-config-globalproperties

 

 

• common.js

import common from "@/common";

app.use(common);

 

 

 

 

 

⚡️Vue-router 변경내용

참고 : https://router.vuejs-korea.org/ko/guide/migration/

Vue 2에서 마이그레이션 | Vue Router

import { createRouter, createWebHistory } from 'vue-router'
createRouter({
    history: createWebHistory(),
    hash: createWebHashHistory(),
    abstract: createMemoryHistory()
    routes: [],
})

app.use(router) 옵션을 사용

 

 

 

 

⚡️Vuex 변경 내용

Vue 2에서 Vuex를 사용하려면 아래 코드를 실행합니다.

export default new Vuex.Store({
    …
});

 

Vue 3에서 Vuex createStore를 사용하려면 아래 코드를 실행합니다.

import { createStore } from 'vuex'
export const store = createStore({
    state () {
      return {
        count: 1
      }
    }
})

 

 

파일에서 사용시 Vuex 4는 useStore 함수를 사용하여 Vue 응용 프로그램의 설치 후크에서 저장소를 가져옵니다.

<scritp setup>

import { useStore } from 'vuex'

const store = useStore()

 

 

 

 

 

🅾️ 종속된 라이브러리 변경사항

Vue2	Vue3
vue 2.7.10	vue 3.1.0
vue-router	vue-router 4.4.2
vuex 3.6.2	vuex 4 [추후 pinia 변경 필요]
vite-plugin-vue2 삭제	@vitejs/plugin-vue": "^5.0.5
	@vue/compiler-sfc": "^3.1.0",
	vue/compat
	vite 설정 변경
	글로벌 함수 전역 등록 (Global API -> Instance API)+ vue3 용 코드로 리팩토링
Vueformulate	FormKit
vue-step-progress: '0'	vue-step-progress: '1.0.2'
vue-awesome-swiper	swiper

 

 

 

 

 

여기까지가 기본적인 Vue3 환경세팅이고, 아래는 해당 레포에 쓰이는 Vue2 라이브러리를 Vue3 에 맞게 수정한코드입니다.

 

 

 

 

---

Sentry

Sentry 도 Vue3에 맞게 코드를 수정해줍니다.

먼저, 사용 중인 @sentry/vue 버전을 최신으로 맞춰줍니다.

yarn add @sentry/vue@latest

• [24.12.12] "@sentry/vue": "^8.43.0",

 

다음으로, deprecated functions 들을 고쳐줍니다.

 

 

• configureScope

//before
  Sentry.configureScope((scope) => { ...

//after
  Sentry.getCurrentScope((scope) => ...

 

 

 

 

• BrowserTracing

//before
    integrations: [
      new Sentry.BrowserTracing({
        routingInstrumentation: Sentry.vueRouterInstrumentation(router),
      }),
    ],


//after
 Sentry.init({
 ...
  integrations: [
    Sentry.browserTracingIntegration({ router }), 
    Sentry.replayIntegration()
  ],

 

 

 

 

 

 

 

 

 

---

 

Vue2에서 Vue3로의 마이그레이션은 기대했던 만큼 쉽지 않았습니다. 예상은 했지만, 패키지 업데이트 후 fix Error, fix Warnings, fix… fix… 에러 고치는데 시간이 많이 들었던 것 같네요.

먼저, Vue3의 새로운 Composition API와 기존의 Options API 간의 차이를 이해하고 적응하는 데 시간이 걸렸습니다. 특히, 기존 코드베이스를 리팩토링하면서 두 API를 혼용하는 과정에서 혼란이 발생하기도 했습니다.

또한, 일부 라이브러리와 플러그인이 Vue3와 호환되지 않아 대체 라이브러리를 찾거나 직접 호환성을 맞추는 작업이 필요했습니다. 이 과정에서 예상보다 많은 시간이 소요되었고, 프로젝트 일정에도 영향을 미쳤습니다.

특히, 폼 라이브러리인 Fomkit , Sentry와 같은 핵심 플러그인들의 새로운 버전으로의 전환이 까다로웠습니다. 기존의 설정과 코드 구조를 변경해야 했고, 이로 인해 많은 테스트와 디버깅이 필요했습니다.

결국, Vue3로의 마이그레이션은 단순한 업그레이드가 아니라, 전체 프로젝트를 다시 한 번 점검하고 개선하는 기회가 되었습니다. 비록 힘들고 시간이 많이 들었지만, 예상 목표 일정보다 훨씬 빠르게 버전을 성공적으로 올려서 뿌듯합니다!🥳