Vite + React + TypeScript で開発環境を構築する

概要

React のフロントエンド開発を始めるとき、ビルドツールに Vite を選ぶのは今や標準的な選択肢です。かつて主流だった Create React App（CRA）はメンテナンス体制が縮小し、公式でも新規プロジェクトには Vite などのモダンツールを推奨する流れになりました。

本記事では、Vite + React + TypeScript の開発環境をゼロから構築し、実務で必要になるパスエイリアス・環境変数・ESLint / Prettier・本番ビルドまでを一通り整える手順を、ハンズオン形式で解説します。

• 対象読者: React をこれから始める人、CRA から Vite へ移行したい人
• ゴール: 型安全に開発でき、Lint / Format が効き、本番ビルドまで通る最小構成

環境

• Node.js 20.x 以降（Vite 5 は Node 18+ が必須）
• Vite 5.x / React 18.x / TypeScript 5.x
• パッケージマネージャは npm（pnpm / yarn 読み替え可）

プロジェクトの作成

Vite の公式スキャフォールディングで、TypeScript 付きの React テンプレートを生成します。

npm create vite@latest my-app -- --template react-ts
cd my-app
npm install
npm run dev

npm run dev を実行すると、デフォルトで http://localhost:5173 に開発サーバが立ち上がり、HMR（Hot Module Replacement）が有効になります。

なお、-- --template react-ts の最初の -- は、npm 側と Vite 側のオプションを区切る記号です。省くと --template が npm のオプションとして解釈され、意図通りに動きません。

ディレクトリ構成を把握する

my-app/
├─ index.html          # Viteのエントリ。ルート直下にある
├─ tsconfig.json
├─ tsconfig.node.json
├─ vite.config.ts
└─ src/
   ├─ main.tsx
   ├─ App.tsx
   └─ vite-env.d.ts

CRA との最大の違いは、index.html がルート直下にあり、そこが起点になる点です。Vite は index.html をソースの一部として扱い、<script type="module" src="/src/main.tsx"> を解決してビルドします。

パスエイリアスを設定する

規模が大きくなると相対パスが読みにくくなります。@/ を src/ に向けるエイリアスを、TypeScript と Vite の両方に設定します。

tsconfig.json（新テンプレートでは tsconfig.app.json）:

{
  "compilerOptions": {
    "baseUrl": ".",
    "paths": { "@/*": ["src/*"] }
  }
}

Vite 側（@types/node を先に入れる）:

npm install -D @types/node

import { defineConfig } from 'vite'
import react from '@vitejs/plugin-react'
import path from 'node:path'

export default defineConfig({
  plugins: [react()],
  resolve: {
    alias: { '@': path.resolve(__dirname, './src') },
  },
})

片方だけの設定だと「エディタでは通るがビルドで落ちる」あるいはその逆が起きるため、必ず両方に書きます。

環境変数を扱う

Vite では VITE_ プレフィックス付きの変数だけが import.meta.env 経由でクライアントに公開されます。これは、秘密情報を誤ってバンドルに含めないための安全弁でもあります。

# .env
VITE_API_BASE_URL=https://api.example.com

const baseUrl = import.meta.env.VITE_API_BASE_URL

型補完を効かせる場合は src/vite-env.d.ts に追記します。

/// <reference types="vite/client" />

interface ImportMetaEnv {
  readonly VITE_API_BASE_URL: string
}
interface ImportMeta {
  readonly env: ImportMetaEnv
}

.env は .gitignore に入れ、.env.example を配布するとチームで必要な変数を共有できます。

ESLint と Prettier を整える

フォーマットは Prettier、品質チェックは ESLint、と役割を分けます。

npm install -D prettier eslint-config-prettier

eslint-config-prettier を ESLint 設定の末尾に置き、Prettier と競合するルールを無効化します（Flat Config の場合）。

import prettier from 'eslint-config-prettier'

export default [
  // ...既存設定...
  prettier, // 末尾に置くのが必須
]

package.json の scripts:

{
  "scripts": {
    "dev": "vite",
    "build": "tsc -b && vite build",
    "preview": "vite preview",
    "lint": "eslint .",
    "format": "prettier --write ."
  }
}

本番ビルドと確認

npm run build     # tsc -b で型チェック → vite build でバンドル
npm run preview   # dist/ を本番相当でローカル配信（確認用）

build スクリプトは型チェック込みのため、型エラーがあればビルドが止まります。生成物は dist/ に出力されます。preview は本番相当の静的ファイルを確認するためのもので、本番サーバの代わりにはなりません。

動作確認

1. npm run dev で HMR が効く
2. @/ の import がエディタ・ビルド双方で通る
3. import.meta.env.VITE_* が期待した値を返す
4. npm run lint がパスする
5. npm run build が型エラーなく完了し dist/ が生成される
6. npm run preview で本番相当の表示が確認できる

注意点

• エイリアスは二重管理になる（tsconfig と vite.config の両方に書く）
• VITE_ プレフィックスの無い変数はフロントに来ない。逆に、秘密情報に VITE_ を付けてはいけない（公開される）
• preview は本番サーバではない。実運用は各種ホスティングで dist/ を配信する
• CRA からの移行時は process.env.REACT_APP_* → import.meta.env.VITE_*、index.html の位置に注意する

まとめ

Vite + React + TypeScript は、npm create vite で即座に始められる一方、実務で効いてくるのは「パスエイリアス・環境変数・Lint / Format・型チェック込みビルド」の初期整備です。特に「tsconfig と Vite の両方に設定を書く」「VITE_ プレフィックスの意味を理解する」の2点を最初に押さえておくと、後からの手戻りを大きく減らせます。