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 리스트 문서 한 개입니다.
형식은 자유지만, 팀 공유를 염두에 두고 다음 정도는 포함해 두는 게 좋습니다.
- 섹션별 체크리스트
- 위 예시들을 그대로 옮기되, 실제 프로젝트에 맞게 항목 추가/삭제
- 파일/폴더 레벨 정보
- 예: src/plugins/axios.js - Vue.prototype.$axios 사용 → globalProperties로 이전
- 예: src/mixins/formMixin.js - 여러 컴포넌트에서 사용 → useForm composable로 교체 예정
- 우선순위/난이도 메모
- 필터 제거는 먼저 진행, 라우터/스토어는 팀 논의 후 같은 간단한 메모
- 담당자/예상 주차
- 실제 프로젝트에 투입될 때는 누가 언제 어느 섹션을 맡을지까지 적어 두면 바로 액션으로 이어짐
정리
이번 글에서 중요한 건 새로운 문법을 외우는 게 아니라
Vue 2 프로젝트에 어떤 기술/패턴이 쓰였는지 조망하고
각 항목에 대해 Vue 3에서 어떻게 대응할지를 한 줄로라도 적어보는 것입니다.
출처
'Framework > Vue' 카테고리의 다른 글
| Vue 3 Compat Build로 Vue 2 프로젝트 안전하게 버전업 (0) | 2025.12.01 |
|---|---|
| Vue 3 마이그레이션 연습용 샘플 Vue 2 프로젝트 준비하기 (0) | 2025.12.01 |
| Vue 3 라이프사이클과 인스턴스 API 변경 정리 (0) | 2025.11.28 |
| Vue 3에서 달라진 v-model과 템플릿 필터 제거 정리 (0) | 2025.11.28 |
| Vue 2의 Vue.use에서 Vue 3 Global API, createApp로 마이그레이션 (0) | 2025.11.27 |