Vue 2에서 Vue 3 마이그레이션 시 참고해야 할 체크리스트

Vue 3 마이그레이션 문서와 여러 블로그를 보면 공통적으로 나오는 조언이 있습니다.

문법 공부보다 먼저 프로젝트에서 무엇을 쓰고 있는지 정리하라.

 

같은 Vue 2 프로젝트라도 어떤 곳은 filter, mixin, event bus를 많이 쓰고

어떤 곳은 Vuex 모듈이 복잡하고

또 어떤 곳은 axios 인터셉터와 전역 플러그인이 핵심일 수 있습니다.

 

이번 글의 목표는 프로젝트에서 실제로 쓰는 것들 목록을 뽑고

각 항목 옆에 Vue 3에서의 대응 전략 한 줄을 붙이는 체크리스트를 만드는 것입니다.

그러면 팀원과 어디부터 손대야 하는지 공유할 수 있게 됩니다.

 

---

 

1. 체크리스트 구조

• 전역 환경 & 빌드
• 템플릿 & 컴포넌트 패턴
• 상태 관리(Vuex → Pinia)
• 라우터(Router 3 → Router 4)
• 네트워크 & axios 설정

각 카테고리 안에는 Vue 2에서 실제로 쓰는 요소, Vue 3에서의 대응 전략을 한 줄씩 적어 둡니다.

 

---

 

2. 전역 환경 체크 포인트

전역 환경은 프로젝트 전반에 영향을 주기 때문에 먼저 정리해두는 게 좋습니다.

[전역 환경 / 빌드]
- [ ] Vue.use(...)로 등록한 플러그인 목록
	→ Vue 3: createApp(App) 후 app.use(...)로 등록. 플러그인 install(app) 시그니처로 정리

- [ ] Vue.prototype.*로 등록한 전역 헬퍼/클라이언트 (예: $axios, $api, $formatDate)
	→ Vue 3: app.config.globalProperties.*로 이전하거나, 그냥 유틸 모듈 import로 변경

- [ ] new Vue()를 EventBus로 사용한 코드 (event-bus.js 등)
	→ Vue 3: 인스턴스 이벤트 API 제거. mitt / tiny-emitter 같은 외부 이벤트 라이브러리로 교체

- [ ] Vue CLI 기반 빌드 여부
	→ Vue 3: 가능하면 Vite 기반 템플릿으로 프로젝트 재생성 후, 코드만 옮기는 전략도 검토

여기까지 정리하면 전역에서 Vue 2에 묶여있는 부분이 어느 정도 보입니다.

 

---

 

3. Router & Store 체크 포인트

[라우터 / 상태 관리]
- [ ] vue-router@3 사용 여부 및 router/index.js 구조 파악
	→ Vue 3: createRouter + createWebHistory로 재구성. 라우트 정의는 최대한 그대로 유지

- [ ] beforeEach / afterEach 네비게이션 가드 사용 위치
	→ Vue 3: Router4에서도 대부분 동일 패턴. next() 대신 return 기반 패턴으로 점진 리팩토링

- [ ] Vuex store / index.js 및 modules 구조 (user, auth, post 등)
	→ Vue 3: Pinia로 전환 검토. 각 Vuex 모듈을 defineStore('moduleName')으로 옮기는 설계 작성

- [ ] mapState / mapGetters / mapActions / mapMutations 사용 컴포넌트 목록
	→ Vue 3: useXxxStore() + store.state / store.getters / store.actions 패턴으로 변경

이 부분은 라우터/스토어 마이그레이션 전략 세우기 단계의 입력으로도 쓰입니다.

 

---

 

4. 템플릿 & 컴포넌트 체크 포인트

템플릿과 컴포넌트 패턴은 마이그레이션 난이도를 크게 좌우하는 영역입니다.

[템플릿 / 컴포넌트]
- [ ] 템플릿 필터 사용 여부 ({{ value | filterName }})
	→ Vue 3: 템플릿 필터 제거, computed/methods 또는 공통 포맷터 유틸로 치환

- [ ] filters: { ... } 옵션 및 Vue.filter(...)로 등록한 전역 필터
	→ Vue 3: 동일 로직을 함수/Composable(useFormatter 등) 형태로 이전.

- [ ] mixins: [...]를 사용하는 컴포넌트 목록
	→ Vue 3: 공통 로직을 Composable 함수(useXxx)나 Pinia store로 분리
    
- [ ] this.$son / this.$off / this.$once 사용 여부 (컴포넌트 간 event bus)
	→ Vue 3: 인스턴스 이벤트 API 제거. 별도 이벤트 라이브러리 또는 명시적 props/emit 구조로 변경
    
- [ ] this.$children / this.$listeners 사용 여부
	→ Vue 3: ref/$refs 또는 useAttrs()로 대체. 가능한 한 명시적인 데이터/이벤트 흐름 설계

이제 특정 컴포넌트 파일 목록까지 뽑아두면 나중에 어디부터 손댈지 우선순위를 잡는 데 도움이 됩니다.

 

---

 

5. 네트워크 & axios 설정 체크 포인트

대부분의 Vue 프로젝트는 axios나 fetch 래퍼를 씁니다.

Vue 2에서는 이걸 전역 플러그인 + prototype으로 붙여둔 경우가 많습니다.

[네트워크 / axios]
- [ ] axios 인스턴스 생성 및 인터셉터 설정 파일 위치
	→ Vue3: 파일 구조는 그대로 사용
      단, Vue.prototype.$axios → app.config.globalProperties.$axios로 이전 여부 확인

- [ ] 전역 에러 핸들러 / 토큰 갱신 로직이 컴포넌트 안에 섞여 있는지
	→ Vue3: Composable(useApi, useAuth) 또는 Pinia store로 정리해 재사용성 확보

- [ ] API 응답에 의존하는 전역 상태(Vuex)와의 결합 여부
	→ Vue3: Pinia store + Composable 조합으로 리팩토링 계획 수립

이 카테고리는 Vue 3 자체 변경사항보다는 마이그레이션 시 구조를 같이 정리할지 결정하는 용도에 가깝습니다.

 

---

 

6. 공유 가능한  TODO 문서 만들기

오늘의 최종 산출물은 마이그레이션 TODO 리스트 문서 한 개입니다.

형식은 자유지만, 팀 공유를 염두에 두고 다음 정도는 포함해 두는 게 좋습니다.

1. 섹션별 체크리스트
   • 위 예시들을 그대로 옮기되, 실제 프로젝트에 맞게 항목 추가/삭제
2. 파일/폴더 레벨 정보
   • 예: src/plugins/axios.js - Vue.prototype.$axios 사용 → globalProperties로 이전
   • 예: src/mixins/formMixin.js - 여러 컴포넌트에서 사용 → useForm composable로 교체 예정
3. 우선순위/난이도 메모
   • 필터 제거는 먼저 진행, 라우터/스토어는 팀 논의 후 같은 간단한 메모
4. 담당자/예상 주차
   • 실제 프로젝트에 투입될 때는 누가 언제 어느 섹션을 맡을지까지 적어 두면 바로 액션으로 이어짐

 

---

 

정리

이번 글에서 중요한 건 새로운 문법을 외우는 게 아니라

Vue 2 프로젝트에 어떤 기술/패턴이 쓰였는지 조망하고

각 항목에 대해 Vue 3에서 어떻게 대응할지를 한 줄로라도 적어보는 것입니다.

 

---

 

출처

Vue 3 Migration Guide