【Vue 3】Vue 3.5 + Vite 7 + Vue Router 5 へのアップグレード手順 - 型エラーの解決まで

Vue 3 プロジェクトの依存パッケージを最新版にアップグレードする際、Vue 本体だけでなく Vue Router、Vite、TypeScript など複数のパッケージを同時に更新する必要があります。

この記事では、Vue 3.3 → 3.5、Vue Router 4 → 5、Vite 7.x 対応の一連のアップグレード手順と、発生しやすいエラーの解決方法を解説します。

アップグレード対象

今回のアップグレードで更新するパッケージの一覧です。

パッケージ	変更前	変更後	備考
vue	^3.3.11	^3.5.27	マイナーバージョンアップ
vue-router	^4.2.5	^5.0.2	メジャーバージョンアップ
vuetify	^3.4.9	^3.11.8	マイナーバージョンアップ
typescript	~5.3.0	~5.9.3	メジャーバージョンアップ
@types/node	^18.19.3	^22.12.0	Vite 7.x 要件
@vue/tsconfig	^0.5.0	^0.8.1	マイナーバージョンアップ

アップグレード手順

Step 1: package.json のバージョンを更新

まず package.json の依存パッケージバージョンを更新します。

{
  "dependencies": {
    "vue": "^3.5.27",
    "vue-router": "^5.0.2",
    "vuetify": "^3.11.8"
  },
  "devDependencies": {
    "@types/node": "^22.12.0",
    "@vue/tsconfig": "^0.8.1",
    "typescript": "~5.9.3"
  }
}

Step 2: npm install で依存関係を解決

npm install

よくあるエラー: ERESOLVE could not resolve

Vite 7.x は @types/node の ^20.19.0 以上を要求します。@types/node が古いままだとインストールに失敗します。

npm error code ERESOLVE
npm error ERESOLVE could not resolve
npm error peerOptional @types/node@"^20.19.0 || >=22.12.0" from vite@7.3.1

@types/node を ^22.12.0 に更新してから再度 npm install を実行してください。

Step 3: 型チェックエラーの修正

npm install が成功したら、ビルドを実行して型チェックを確認します。

npm run build

エラー 1: @vitejs/plugin-vue の型エラー

node_modules/@vitejs/plugin-vue/dist/index.d.mts(120,94): error TS1003: Identifier expected.

TypeScript のバージョンが古い場合に発生します。typescript を ~5.9.3 に更新することで解消します。

エラー 2: .vue モジュールの型宣言が見つからない

src/router/index.ts(2,22): error TS7016: Could not find a declaration file
  for module '@/views/HomeView.vue'.

プロジェクトルートの env.d.ts に以下の型宣言を追加します。

// env.d.ts
/// <reference types="vite/client" />

declare module '*.vue' {
  import type { DefineComponent } from 'vue'
  const component: DefineComponent<{}, {}, any>
  export default component
}

Step 4: ビルド確認

すべての修正が完了したら、ビルドが通ることを確認します。

npm run build

Vue Router 4 → 5 の主な変更点

Vue Router 5 では API の大幅な変更はなく、既存コードがそのまま動作するケースがほとんどです。主な変更点は以下の通りです。

項目	変更内容
TypeScript 型定義	より厳格な型定義に変更
ナビゲーションガード	戻り値の型が明確化
<script setup> 対応	Composition API との統合が強化

基本的なルート定義はそのまま使えます。

// router/index.ts - 基本的な変更は不要
import { createRouter, createWebHistory } from 'vue-router'
import HomeView from '@/views/HomeView.vue'

const router = createRouter({
  history: createWebHistory(import.meta.env.BASE_URL),
  routes: [
    {
      path: '/',
      name: 'home',
      component: HomeView,
    },
  ],
})

export default router

Sass @import の非推奨警告

アップグレード後、以下のような警告が表示される場合があります。

Deprecation Warning: @import is deprecated and will be removed in a future version.
Use @use instead.

これは Sass の @import 構文が非推奨になったためです。ビルドや動作には影響しませんが、将来のバージョンで削除されるため、@use への移行が推奨されます。

// Before
@import "@/styles/_single.scss";

// After
@use "@/styles/_single.scss";

トラブルシューティング

npm install が失敗する

package-lock.json を削除して再インストールすると解決する場合があります。

rm package-lock.json
npm install

vue-tsc が古い TypeScript と互換性がない

vue-tsc と typescript のバージョンの組み合わせに注意してください。vue-tsc 3.x は TypeScript 5.x 系に対応しています。

Vuetify のスタイルが崩れる

Vuetify 3.4 → 3.11 ではコンポーネントの CSS に変更が入っている場合があります。見た目に問題がないか画面を確認してください。

アップグレードチェックリスト

参考文献

• Vue 3.5 リリースノート - GitHub
• Vue Router 5 マイグレーションガイド
• Vite 7.0 リリースノート
• Vuetify 3 アップグレードガイド

まとめ

Vue 3 プロジェクトのアップグレードでは、Vue 本体だけでなく周辺パッケージの互換性も確認が必要です。特に注意すべきポイントは以下の 3 点です。

1. Vite 7.x は @types/node ^20.19.0 以上を要求する
2. Vite 7.x では .vue モジュールの型宣言を env.d.ts に手動で追加する必要がある
3. TypeScript のバージョンも合わせて更新しないと @vitejs/plugin-vue の型エラーが発生する

パッケージ間の依存関係を意識しながら、順番にエラーを解消していくのがスムーズなアップグレードのコツです。