記事には広告が含まれています
Viteは高速なビルドツールとして多くのフロントエンドプロジェクトで採用されていますが、「最初はJavaScriptで始めたプロジェクトに、途中からTypeScriptを導入したい」という場面は少なくありません。フレームワークの規模が大きくなるにつれて型安全性の重要性が増し、後からTypeScriptを追加したいというニーズは現場でも頻繁に発生します。
本記事では、既存のViteプロジェクトにTypeScriptを後から追加する具体的な手順を、設定ファイルの内容も含めてわかりやすく解説します。新規プロジェクトをTypeScriptテンプレートで作成する方法も合わせて紹介するので、状況に合わせて参考にしてください。
もくじ
ViteとTypeScriptの関係をまず押さえよう
ViteはデフォルトでTypeScriptをサポートしています。ただし、Vite自体は型チェックは行わず、esbuildによってTypeScriptをJavaScriptへトランスパイルするだけという点が重要です。つまり、型エラーがあってもビルドは通ってしまうため、型チェックを厳密に行いたい場合は別途 tsc を実行する設定が必要になります。
ViteはesbuildでTypeScriptをJSに変換します。この処理はvanillaのtscに比べて約20〜30倍高速で、HMR（ホットモジュールリプレースメント）の更新は50ミリ秒未満で反映されます。型チェックはCI等でtscを別途実行する構成が一般的です。
新規プロジェクトにTypeScriptを追加する場合（テンプレートを使う方法）
これからViteプロジェクトを新規作成する場合は、最初からTypeScriptテンプレートを選ぶのが最もシンプルです。以下のコマンドでTypeScript対応のプロジェクトを作成できます。
npm create vite@latest my-app -- --template react-ts cd my-app npm install npm run devフレームワークなしのVanilla TypeScriptを使いたい場合は、--template vanilla-ts を指定します。テンプレートを使うことで、tsconfig.json・tsconfig.node.json・vite-env.d.ts が自動生成されます。
既存のViteプロジェクトにTypeScriptを後から追加する手順
すでにJavaScriptで動いているViteプロジェクトにTypeScriptを追加する場合は、以下の手順を順番に進めてください。
# TypeScript本体 npm install -D typescript # Reactを使っている場合は型定義も追加 npm install -D @types/react @types/react-dom インストール後、package.json の devDependencies に typescript が追加されていることを確認してください。
tsconfig.json を作成します。以下は基本的な設定例です。Viteの公式ドキュメントでは "isolatedModules": true の設定が推奨されています。
{ "compilerOptions": { "target": "ESNext", "module": "ESNext", "moduleResolution": "bundler", "strict": true, "skipLibCheck": true, "isolatedModules": true, "noEmit": true, "jsx": "react-jsx" }, "include": ["src"] } Vite 5以降では "moduleResolution": "bundler" が推奨設定です。
src/ ディレクトリ内に vite-env.d.ts ファイルを作成します。このファイルは Viteが提供する型定義を読み込むためのエントリーポイントとなるもので、import.meta.env や import.meta.hot などVite固有のAPIを TypeScript上で正しく認識させるために必要です。 最低限の設定は以下の1行です。
/// <reference types="vite/client" />この1行だけで、以下のような Vite 組み込みの環境変数が型補完の対象になります。
import.meta.env.MODE（現在のモード。例：development / production）import.meta.env.BASE_URL（ベースURL）import.meta.env.PROD（本番環境かどうかの真偽値）import.meta.env.DEV（開発環境かどうかの真偽値）
カスタム環境変数の型定義を追加する
プロジェクトで .env ファイルにカスタム変数（VITE_ プレフィックスが必須）を定義している場合は、同ファイルに ImportMetaEnv インターフェースを拡張することで型補完が効くようになります。
/// interface ImportMetaEnv { readonly VITE_APP_TITLE: string readonly VITE_API_BASE_URL: string readonly VITE_FEATURE_FLAG: string // 追加した環境変数の分だけ定義する } interface ImportMeta { readonly env: ImportMetaEnv } vite-env.d.ts の中に import 文を書いてしまうと、TypeScriptがこのファイルを「モジュール」として扱うようになり、グローバルな型拡張が機能しなくなります。型定義の拡張が上手く動かない場合はファイル内の import 文を確認してください。
Viteはセキュリティ上の理由から、VITE_ で始まる環境変数のみをクライアントサイドのコードに公開します。DB_PASSWORD のようなプレフィックスなしの変数は import.meta.env から参照しても undefined になります。APIキーなどの秘密情報は VITE_ プレフィックスを使わないようにしましょう。
| 変更前 | 変更後 | 使用場面 |
|---|---|---|
.js |
.ts |
通常のTypeScriptファイル |
.jsx |
.tsx |
JSX（Reactコンポーネント等）を含むファイル |
移行時の実践的なアプローチ
一度に全ファイルを変換しようとすると大量の型エラーが発生し、収拾がつかなくなりがちです。現場では以下のような段階的な移行が有効です。
- まず
tsconfig.jsonで"strict": falseにして全ファイルの拡張子だけ変更する - ビルドが通ることを確認してから、ファイルごとに型を付けていく
- 全ファイルの型付けが完了したら
"strict": trueに戻す
それでも対応が難しいファイルは、一時的に // @ts-nocheck をファイル先頭に追加することで型チェックを無効化できます。段階的な移行中の逃げ道として覚えておくと安心です。
// @ts-nocheck // このファイルの型チェックを一時的に無効化（移行期間中の暫定対応） export function someFunction() { // ... } Vite設定ファイルを vite.config.js から vite.config.ts に変更することも推奨です。TypeScriptで書くことでIDEの補完が効き、設定ミスを防ぎやすくなります。変更時は defineConfig ヘルパーを使うと型サポートが自動的に有効になります。
package.json の各スクリプトを以下のように更新することで、ビルドと型チェックを連携させられます。
{ "scripts": { "dev": "vite", "build": "tsc && vite build", "type-check": "tsc --noEmit", "preview": "vite preview" } } 各スクリプトの役割
- build：
tscで型チェックを先に実行し、エラーがなければvite buildでバンドル。型エラーがあるとビルドが止まる - type-check：型チェックのみを単独で実行するスクリプト。CIパイプラインや開発中の確認に便利
開発中にリアルタイムで型チェックしたい場合
vite-plugin-checker を導入すると、開発サーバー起動中もブラウザのオーバーレイで型エラーを通知してくれます。型エラーに気づかないまま開発が進んでしまうリスクを大幅に減らせます。
npm install -D vite-plugin-checker import { defineConfig } from 'vite' import react from '@vitejs/plugin-react' import checker from 'vite-plugin-checker' export default defineConfig({ plugins: [ react(), checker({ typescript: true, }), ], }) これにより、開発サーバー起動時（npm run dev）から型エラーがブラウザ画面に表示されるようになります。ただし、大規模プロジェクトでは型チェックに時間がかかることがあるため、チームの状況に合わせて導入を検討してください。
tsconfig.jsonの主要設定項目と意味
Viteプロジェクト向けのtsconfig.jsonでは、いくつかの設定項目の意味を理解しておくと運用がスムーズです。
| 設定項目 | 推奨値 | 意味・理由 |
|---|---|---|
isolatedModules |
true | esbuildの制約に合わせた分離トランスパイルモード。Vite利用時は必須に近い |
moduleResolution |
bundler | Vite 5以降の推奨。バンドラー向けのモジュール解決ルール |
noEmit |
true | tscはJSファイルを出力しない（出力はViteに任せる） |
skipLibCheck |
true | 依存ライブラリの型チェックをスキップ。ビルド速度の向上と競合回避に有効 |
strict |
true | 厳格な型チェックを有効化。新規プロジェクトでは必ず有効にする |
Viteのテンプレートでプロジェクトを生成すると tsconfig.node.json も作成されます。これは vite.config.ts など、Node.js環境で動作するファイル向けの設定ファイルです。ブラウザ向けコードとNode.js向けコードで異なるコンパイル設定が必要なため、Viteでは設定ファイルを分けるアーキテクチャが採用されています。
よくあるエラーと対処法
「Cannot find module ‘vite/client’」と表示される
vite-env.d.ts が存在しないか、tsconfig.json の include に src が含まれていない可能性があります。ファイルの配置場所と include パスを確認しましょう。
「Property ‘env’ does not exist on type ‘ImportMeta’」が出る
vite-env.d.ts の1行目に /// <reference types="vite/client" /> が書かれているか確認してください。また、このファイルが tsconfig.json の include 対象に含まれているかも合わせて確認が必要です。
型エラーがあってもビルドが通ってしまう
前述のとおり、ViteはTypeScriptの型チェックをしません。型エラーを検知したい場合は build スクリプトに tsc を含めるか、vite-plugin-checker を導入してください。
「isolatedModules」に関するエラーが出る
isolatedModules: true の設定下では、型のみのインポートに import type 構文を使う必要があります。
// NG：通常のimportで型だけをインポートしている import { SomeType } from './types' // OK：import type を使う import type { SomeType } from './types' JavaScriptからTypeScriptへの移行は、一度に全ファイルを変換しようとすると大量のエラーが発生しがちです。まず strict: false にして動作確認を行い、徐々に strict: true に移行するか、ファイルを1つずつ変換していくアプローチが現場では安全です。
ViteにTypeScriptを追加導入する方法まとめ
- ViteはesbuildでTSをトランスパイルするが、型チェックは自動では行わない
- 新規プロジェクトは
--template react-tsなどのテンプレートを使うのが最短 - 既存プロジェクトへの追加は、①typeScriptインストール → ②tsconfig.json作成 → ③vite-env.d.ts追加 → ④拡張子変更 → ⑤buildスクリプト更新 の順で進める
isolatedModules: trueとnoEmit: trueはVite環境では必須に近い設定- 型チェックを開発中にも行いたい場合は
vite-plugin-checkerの導入を検討する - 大規模プロジェクトの移行では段階的に進め、一度に全ファイルを変換しない
ViteとTypeScriptの組み合わせは、現在のフロントエンド開発における定番構成の一つです。最初の設定さえ整えてしまえば、その後の開発体験は大きく向上します。本記事の手順を参考に、ぜひ型安全な開発環境を整えてみてください。
