【Vite + Vue3 + TypeScript】エイリアスを設定して@インポートする

Vite + Vue3 + TypeScriptの環境でインポートエイリアスを設定する手法は様々な記事で紹介されていますが、どれもうまくいかずにつまずいたのでメモに残しておきます。

環境

npm create vite@latest
 ※この後の選択肢で「Vue」「TypeScript」を選択

ディレクトリ構成

npm createしたばかりの構成です。

.
├── public
│   └── vite.svg
├── src
│   ├── assets
│   │   └── vue.svg
│   ├── components
│   │   └── HelloWorld.vue
│   ├── App.vue
│   ├── main.ts
│   └── style.css
├── .gitignore
├── index.html
├── package-lock.json
├── package.json
├── README.md
├── tsconfig.app.json
├── tsconfig.json
├── tsconfig.node.json
└── vite.config.ts

目標

// Before
import HelloWorld from './components/HelloWorld.vue'
// After
import HelloWorld from '@/components/HelloWorld.vue'

手順

1. vite.config.tsに追記

import { defineConfig } from 'vite'
import vue from '@vitejs/plugin-vue'
+ import path from "path"

// https://vite.dev/config/
export default defineConfig({
  plugins: [vue()],
+  resolve: {
+    alias: {
+      "@": path.resolve(__dirname, "./src"),
+      "@/*": path.resolve(__dirname, "./src/*"),
+    },
+  },
})

pathモジュールはデフォルトで使用可能なはず。

この状態だとnpm run devは通るがnpm run buildは通らない。ついでにVSCodeのエラーもうるさい。

2. tsconfig.jsonをリネーム

tsconfig.jsonをtsconfig.build.jsonに変更してください。変更後の名前は何でも良いですが、ここでは.buildとしておきます。後のステップでpackage.jsonに記載します。

tsconfig.build.json

{
  "files": [],
  "references": [
    { "path": "./tsconfig.app.json" },
    { "path": "./tsconfig.node.json" }
  ]
}

3. tsconfig.jsonを作成

tsconfig.json

// インポートエイリアスをVSCodeで検出できるようにするための設定 (つまり無くてもビルドは通る)
// 元のtsconfig.jsonはtsconfig.build.jsonに移行
{
  "compilerOptions": {
    "baseUrl": ".",
    "paths": {
      "@": ["./src"],
      "@/*": ["./src/*"],
    },

    /* 以下は移行に伴うvite.config.tsのエラーを解消するための設定 (tsconfig.node.jsonから抜粋) */
    "target": "ES2023",
    "module": "ESNext",
    "moduleResolution": "bundler",
    "noEmit": true,
  },
}

4. tsconfig.app.jsonに追記

tsconfig.app.json

{
  "extends": "@vue/tsconfig/tsconfig.dom.json",
  "compilerOptions": {
    "tsBuildInfoFile": "./node_modules/.tmp/tsconfig.app.tsbuildinfo",
    "types": ["vite/client"],

+    /* エイリアスの設定 */
+    "baseUrl": ".",
+    "paths": {
+      "@": ["./src"],
+      "@/*": ["./src/*"],
+    },

    /* Linting */
    "strict": true,
    "noUnusedLocals": true,
    "noUnusedParameters": true,
    "erasableSyntaxOnly": true,
    "noFallthroughCasesInSwitch": true,
    "noUncheckedSideEffectImports": true
  },
  "include": ["src/**/*.ts", "src/**/*.tsx", "src/**/*.vue"]
}

5. package.jsonを変更

package.json

{
  "name": "hogehoge-app",
  "private": true,
  "version": "0.0.0",
  "type": "module",
  "scripts": {
    "dev": "vite",
-    "build": "vue-tsc -b && vite build",
+    "build": "vue-tsc -b tsconfig.build.json && vite build",
    "preview": "vite preview"
  },
  "dependencies": {
    "vue": "^3.5.24"
  },
  "devDependencies": {
    "@types/node": "^24.10.1",
    "@vitejs/plugin-vue": "^6.0.1",
    "@vue/tsconfig": "^0.8.1",
    "typescript": "~5.9.3",
    "vite": "^7.2.4",
    "vue-tsc": "^3.1.4"
  }
}

ビルド時に先ほど作成したtsconfig.build.jsonを参照するようにします。

最終的なディレクトリ構成

.
├── public
│   └── vite.svg
├── src
│   ├── assets
│   │   └── vue.svg
│   ├── components
│   │   └── HelloWorld.vue
│   ├── App.vue
│   ├── main.ts
│   └── style.css
├── .gitignore
├── index.html
├── package-lock.json
├── package.json        ← 変更
├── README.md
├── tsconfig.app.json   ← 追記
├── tsconfig.build.json ← 新規作成（内容はtsconfig.json）
├── tsconfig.json       ← 新規作成
├── tsconfig.node.json
└── vite.config.ts      ← 追記

解説

VSCodeはtsconfig.jsonを参照して解析を行うらしく、残念ながらこの参照先は変更ができませんでした。
元からあったtsconfig.jsonにエイリアスの設定を追加すると何故かビルドが通らなくなったので、tsconfig.jsonはVSCode専用にして、Viteには別ファイル（tsconfig.build.json）を参照してもらうようにしました。

おわりに

少々複雑でしたが、これらの設定によってVSCodeのエラー無くビルドが通るようになったと思います。

エイリアス周りの設定はバージョンアップによって破壊的変更がされるのか知りませんが、古い情報は当てにならないことが多かったです。

より良い手法があれば教えてください。