Vue 2 → Vue 3 마이그레이션 초기 세팅

최근 진행 중인 BrickML 프론트엔드 애플리케이션에서 큰 과제가 하나 바로 Vue 2 기반 프로젝트를 Vue 3로 마이그레이션하는 작업!!

처음엔 단순히 패키지 업그레이드 정도일 거라 생각했는데, 막상 해보니 호환성 문제, UI 깨짐, 런타임 오류 등 꽤 다양한 난관들이 있었습니다. 이번 글에서는 그 과정을 기록해보려고 합니다.

---

🔍 처음 마주한 문제들

업그레이드 직후 가장 먼저 부딪힌 건 이런 문제들이었습니다:

• 런타임 오류
  vue__WEBPACK_IMPORTED_MODULE_0__.default is not a constructor
  → Vue 2 전용 문법/플러그인 때문에 발생

• UI 깨짐
  Vuetify 2 → 3 전환 과정에서 색상 클래스나 버튼 속성이 달라져서, 대시보드 레이아웃이 망가짐

• 플러그인 호환성
  vue-navigation-bar, vue-screen-size 같은 Vue 2 전용 플러그인이 정상 동작하지 않음

결국 단순 업그레이드라기보다, 마이그레이션에 가까운 작업이라는 걸 실감하게 됐습니다.

---

🧭 원인 분석

Vue 3로 올라가면서 바뀐 부분들을 하나씩 살펴보니:

1. 프레임워크 차원 변경

   • Vue Router 3 → 4
   • Vuex 4 혹은 Pinia로 대체 필요

2. Vuetify 2 → 3

   • 색상 클래스 체계가 변경됨
   • 버튼 속성 (:dark, depressed 등) 사용 방식 변화

3. 이벤트 시스템 차이

   • Vue 2에서 쓰던 EventBus 패턴이 바로 동작하지 않음

4. 외부 플러그인 호환성

   • Vue 2 전용 라이브러리들은 대부분 제거 후 대체 방안 필요

즉, 오류들은 단순한 버그가 아니라 Vue 3의 새로운 구조와 생태계 변화 때문이었습니다.

---

✨ 해결 방향과 접근 방식

처음부터 완벽하게 바꾸는 건 무리라고 판단해서, 점진적 마이그레이션을 선택.

• 하위 호환성 최대한 유지: 기존 코드 베이스를 크게 흔들지 않고 변경
• UI 일관성 우선: 사용자 입장에서 Vue 2 → Vue 3 전환이 눈에 띄지 않도록
• 임시 해결책 적극 활용: 당장 호환되지 않는 부분은 제거하거나 대체

---

⚙️ 주요 작업 정리

✅ 프레임워크 업그레이드

• Vue 2 → Vue 3 (vue@3.4.0)
• Vuetify 2 → Vuetify 3 (vuetify@3.4.0)
• Vue Router 3 → Vue Router 4
• 상태관리: Vuex 4 유지 or Pinia 전환 검토 중

✅ UI/UX 복원

• 앱 바 레이아웃 재정렬
• 로고와 메뉴 위치 조정
• Vuetify 색상 클래스 업데이트
• 원형 버튼 스타일 복원 (border-radius: 50%)

✅ 컴포넌트 마이그레이션

- grey--text text--darken-1 → text-grey-darken-1
- grey lighten-4           → grey-lighten-4
- blue--text text--darken-1 → text-blue-darken-1

- :dark="true"  → variant="elevated"
- depressed     → variant="tonal"

📂 이미지 로딩 방식 변경

• require() 방식 → public 폴더 참조 방식으로 변경

---

✅ 이벤트 시스템

• Vue 3 호환 EventBus 구현
• $on, $emit, $off 메서드 하위 호환 제공

---

⚠️ 임시 해결책

• ApexCharts: Vue 3 호환성 이슈로 현재 비활성화
  → 스타일링된 플레이스홀더 UI로 대체

---

🧪 현재 상태

• 개발 서버 정상 실행 (npm run dev)
• 빌드 오류 없음
• 기본 네비게이션 정상 동작
• 대시보드 UI는 Vue 2와 동일한 수준으로 복원 완료

---

🔄 앞으로의 계획

1. 높은 우선순위

• ApexCharts Vue 3 호환 버전 적용
• 전체 페이지 기능 테스트
• Vue 3 성능 최적화

2. 중간 우선순위

• 불필요한 Vue 2 코드 정리
• TypeScript 마이그레이션
• 상태관리: Pinia 도입 여부 확정

3. 낮은 우선순위

• 제거된 플러그인의 대안 검토
• 번들 크기 분석 및 최적화

---

💡 작업하면서 느낀 점

Vue 3 마이그레이션은 단순히 버전 업그레이드가 아니라, 생태계 전체의 변화를 따라가는 과정이라는 걸 다시금 깨달았습니다.

UI가 깨지지 않도록 하나씩 복원하면서도, Vue 3의 장점을 살리려면 점진적으로 접근하는 게 가장 현실적인 방법이었습니다.

특히, 사용자가 차이를 느끼지 못하지만 내부적으로는 최신 기술로 바뀐다는 점이 이번 작업의 핵심이었던 것 같습니다.

---

✍️ 마무리하며

아직 시작 단계지만, 이제 Vue 3 기반에서 일부 화면은 나오게 되었습니다.

앞으로는 Pinia + TypeScript 조합으로 코드 품질을 끌어올리고, 성능 최적화까지 진행할 예정입니다.

비슷한 상황에서 마이그레이션을 고민하는 분들께 도움이 되길 바랍니다 🙌