Vue Router 5로 마이그레이션하기

TIP

Vue Router 5는 unplugin-vue-router(파일 기반 라우팅)를 코어 패키지에 병합한 전환 릴리스입니다. unplugin-vue-router 없이 Vue Router 4를 사용 중이라면 브레이킹 체인지는 없습니다. 코드 수정 없이 업그레이드할 수 있습니다. 유일한 예외는 iife 빌드가 더 이상 @vue/devtools-api를 포함하지 않는다는 점입니다. 이 패키지가 v8로 업그레이드되면서 자체적으로 IIFE 빌드를 제공하지 않기 때문입니다. 이 변경 사항은 이 이슈에서 추적할 수 있습니다.

Vue Router 6는 ESM 전용이 되며 deprecated API를 제거할 예정입니다. v5는 그 전환을 준비할 시간을 제공합니다.

Vue Router 4 사용자용(파일 기반 라우팅 없음)

브레이킹 체인지는 없습니다. 의존성만 업데이트하면 끝입니다:

pnpm update vue-router@5

unplugin-vue-router에서

파일 기반 라우팅에 unplugin-vue-router를 사용하고 있었다면, 마이그레이션은 대부분 import 경로 변경입니다.

마이그레이션 체크리스트(TLDR)

• Remove unplugin-vue-routerdependency
• Update vue-routerto v5
• Change plugin import: unplugin-vue-router/vite → vue-router/vite
• Change data loader imports: unplugin-vue-router/data-loaders/* → vue-router/experimental
• Change utility imports: unplugin-vue-router → vue-router/unplugin
• Change Volar plugins: unplugin-vue-router/volar/* → vue-router/volar/*
• Remove unplugin-vue-router/clientfrom tsconfig / env.d.ts

1. 의존성 업데이트

pnpm remove unplugin-vue-router
pnpm update vue-router@5

2. import 업데이트

Vite 플러그인:

import VueRouter from 'unplugin-vue-router/vite'
import VueRouter from 'vue-router/vite'

다른 빌드 도구(Webpack, Rollup, esbuild)는 vue-router/unplugin에서 import합니다:

import VueRouter from 'vue-router/unplugin'

VueRouter.webpack({
  /* ... */
})
VueRouter.rollup({
  /* ... */
})
// 등

데이터 로더:

import { defineBasicLoader } from 'unplugin-vue-router/data-loaders/basic'
import { defineColadaLoader } from 'unplugin-vue-router/data-loaders/pinia-colada'
import { DataLoaderPlugin } from 'unplugin-vue-router/data-loaders'
import { defineBasicLoader, DataLoaderPlugin } from 'vue-router/experimental'
import { defineColadaLoader } from 'vue-router/experimental/pinia-colada'

Unplugin 유틸리티(사용자 정의 통합용):

import {
  VueRouterAutoImports,
  EditableTreeNode,
  createTreeNodeValue,
  createRoutesContext,
  getFileBasedRouteName,
  getPascalCaseRouteName,
} from 'unplugin-vue-router'
} from 'vue-router/unplugin'

타입:

import type { Options, EditableTreeNode } from 'unplugin-vue-router'
import type { Options, EditableTreeNode } from 'vue-router/unplugin'

Volar 플러그인:

// tsconfig.json
{
  "compilerOptions": {
    "rootDir": ".",
  },
  "vueCompilerOptions": {
    "plugins": [
      "unplugin-vue-router/volar/sfc-typed-router", 
      "unplugin-vue-router/volar/sfc-route-blocks", 
    ],
  },
}

// tsconfig.json
{
  "compilerOptions": {
    "rootDir": ".",
  },
  "vueCompilerOptions": {
    "plugins": [
      "vue-router/volar/sfc-typed-router", 
      "vue-router/volar/sfc-route-blocks", 
    ],
  },
}

3. vite.config.ts와 tsconfig.json 업데이트

생성된 타입 파일을 src/ 안으로 옮기고 route-map.d.ts로 이름을 바꾸는 것이 권장됩니다. 대부분의 설정에서 자동으로 포함되기 때문입니다:

// vite.config.ts
export default defineConfig({
  plugins: [
    VueRouter({
      dts: 'src/route-map.d.ts', 
    }),
    Vue(),
  ],
})

이전 클라이언트 타입 참조를 제거하세요. 이는 보통 env.d.ts에 추가되어 있었거나:

/// <reference types="unplugin-vue-router/client" />

tsconfig.json에 추가되어 있었습니다:

{
  "include": [
    "./typed-router.d.ts", 
    "unplugin-vue-router/client", 
    // ...
  ],
}

문제 해결

타입이 인식되지 않음: TypeScript 서버를 재시작하고 생성된 타입 파일(예: src/route-map.d.ts)이 tsconfig에 포함되어 있는지 확인하세요.

라우트가 생성되지 않음: routesFolder 경로를 확인하고 파일 확장자를 점검하세요.

라우트 이름 오류: 생성된 이름을 사용하거나 컴포넌트에 definePage({ name: 'custom-name' })를 추가하세요.

새로운 export 참조

Export	용도
vue-router	메인 API(변경 없음)
vue-router/vite	Vite 플러그인
vue-router/auto-routes	생성된 라우트
vue-router/unplugin	Webpack/Rollup/esbuild + 유틸리티
vue-router/experimental	데이터 로더
vue-router/experimental/pinia-colada	Pinia Colada 로더