エイリアスを設定したのにVS Codeでジャンプできなかった原因

Vite環境でパスエイリアス（@utils/... など）を設定して開発していたところ、以下のような現象に遭遇した。

• アプリ自体は問題なくビルドされ、ブラウザでも正常に動作する
• 他のエイリアス（@hooks や @modules など）はVS Code上で Cmd + クリック（Windowsは Ctrl + クリック）すると定義元ファイルにジャンプできる
• しかし、一部のエイリアス（@utils や @api など）だけは Cmd + クリックしてもファイルに飛ばない

原因はシンプル、「ビルドツール向けの設定」と「エディタ（VS Code）向けの設定」を混同していたこと。

原因：ファイルを混同していた

エイリアスを設定する際、vite.config.js の resolve.alias には確かに以下のように記述していた。

// vite.config.js
export default defineConfig({
  resolve: {
    alias: {
      "@hooks": path.resolve(__dirname, "resources/js/hooks"),
      "@modules": path.resolve(__dirname, "resources/js/components/modules"),
      "@utils": path.resolve(__dirname, "resources/js/utils"),
      "@api": path.resolve(__dirname, "resources/js/api"),
    },
  },
});

「Viteの設定ファイルに書いたから大丈夫だろう」と思い込んでいたが、VS Codeの定義ジャンプに必要なもう1つのファイル jsconfig.json側への記述が漏れていた。

vite.config.js と jsconfig.json の違い

なぜ両方に書く必要があるのか、その違いは「設定の読み手と目的」にある。

項目	vite.config.js	jsconfig.json
読み手	ビルドツール（Vite）	エディタ（VS Code）
主な目的	アプリを正常にバンドル・実行するため	コードジャンプや補完を効かせるため
役割	ブラウザが解釈できないエイリアスパスを、ビルド時に実際のファイルパスへ変換する	プロジェクト内の構造を把握し、エディタ支援（Cmd+クリック、自動補完、エラー検出）を提供する
設定がないと	ブラウザ画面が真っ白になり、ビルドエラーになる	アプリは動くが、エディタ上でファイルに飛べなくなる

vite.config.js ではなく、 jsconfig.json を用意してあげる必要がある。

解決手順

プロジェクトルート（package.json と同じ階層）にある jsconfig.json（または tsconfig.json）を開き、compilerOptions.paths に不足していたエイリアスを追加。

{
  "compilerOptions": {
    "baseUrl": ".",
    "paths": {
      "@hooks/*": ["resources/js/hooks/*"],
      "@modules/*": ["resources/js/components/modules/*"],
      "@utils/*": ["resources/js/utils/*"],
      "@api/*": ["resources/js/api/*"]
    }
  },
  "include": ["resources/**/*"]
}

設定を保存後、VS Codeのウィンドウを再読み込み（またはエディタを再起動）すると、無事に @utils/... や @api/... も Cmd + クリックで目的のファイルへジャンプできるようになった。