tsconfig.jsonの読み方
この章の目次開く
tsconfig.json はTypeScriptプロジェクトの設定ファイルです。オプションが多く初見では圧倒されますが、実務で重要なものは限られています。
学習者tsconfig.json のオプションが多すぎて開く気が失せる…。全部理解しないとダメ？
先生全部覚える必要はない。まず strict を有効にして、あとはプロジェクトで問題が出たときにピンポイントで調べれば十分だよ。
strictモード — まずこれを有効にする
strict: true は、複数の厳格チェックをまとめて有効にするフラグです。
{
"compilerOptions": {
"strict": true
}
}strict: true が有効にする主要オプション：
| オプション | 何をチェックするか |
|---|---|
strictNullChecks | null / undefined を型レベルで区別する |
noImplicitAny | 型推論できないものに暗黙の any を禁止する |
strictFunctionTypes | 関数の引数型を厳密にチェックする |
strictPropertyInitialization | classプロパティの初期化漏れを検出する |
// strictNullChecks: true の場合
function greet(name: string | null) {
// ❌ name.toUpperCase(); // Object is possibly 'null'
// ✅
if (name) {
name.toUpperCase();
}
}
// noImplicitAny: true の場合
// ❌ function process(data) {} // Parameter 'data' implicitly has an 'any' type
// ✅
function process(data: unknown) {}target と module — 出力するJSの形式
{
"compilerOptions": {
"target": "ES2022",
"module": "ESNext"
}
}| オプション | 決めること | よくある値 |
|---|---|---|
target | コンパイル先のJSバージョン | ES2020, ES2022, ESNext |
module | 出力するモジュール形式 | ESNext, CommonJS, Node16 |
target を低くすると、async/await がジェネレータに変換されるなど出力が複雑になります。モダンブラウザやNode.js 18+なら ES2022 以上で問題ありません。
学習者target と module の違いがよく分からない…。どちらもES何とかを指定するけど何が違うの？
先生target は「どのバージョンのJSに変換するか」で、module は「import/exportをどの形式で出力するか」。Next.jsやViteならフレームワークが適切なデフォルトを設定してくれるから、そのまま使えばOK。
moduleResolution — importの解決方法
{
"compilerOptions": {
"moduleResolution": "bundler"
}
}| 値 | 使う場面 |
|---|---|
node | 従来のNode.js（CommonJS中心） |
node16 / nodenext | Node.js 16+のESM対応 |
bundler | Vite, Next.js, webpackなどバンドラー経由 |
bundler はバンドラーが解決してくれる前提で、拡張子なしの import や package.json の exports フィールドを柔軟に扱います。フロントエンド開発では bundler が推奨されています。
paths と baseUrl — パスエイリアス
{
"compilerOptions": {
"baseUrl": ".",
"paths": {
"@/*": ["./src/*"]
}
}
}これで import { Button } from '@/components/Button' のようなエイリアスが使えます。
include と exclude
{
"include": ["src/**/*", "types/**/*"],
"exclude": ["node_modules", "dist"]
}include に指定したパターンに一致するファイルだけがコンパイル対象になります。exclude は include の結果からさらに除外するファイルを指定します。
フレームワークのtsconfig
Next.jsやViteは、プロジェクト作成時にtsconfigを自動生成します。
// Next.js が生成する tsconfig.json（抜粋）
{
"compilerOptions": {
"target": "ES2017",
"lib": ["dom", "dom.iterable", "esnext"],
"module": "esnext",
"moduleResolution": "bundler",
"jsx": "preserve",
"strict": true,
"paths": {
"@/*": ["./src/*"]
}
}
}
フレームワークが生成したtsconfigは理由があってその値になっているため、意味が分からないまま変更すると問題が起きやすいです。変更するときは、そのオプションが何を制御しているかを確認してから行います。
実務でよく変更するオプション一覧
| オプション | 用途 | よくある変更 |
|---|---|---|
strict | 厳密な型チェック | 新規は true、レガシーは段階的に |
target | JS出力バージョン | 環境に合わせて ES2022 以上 |
paths | パスエイリアス | @/* を追加 |
skipLibCheck | .d.ts のチェック省略 | ビルド高速化のため true |
noUncheckedIndexedAccess | 配列・オブジェクトのアクセスに undefined を含める | 安全性を上げるなら true |
verbatimModuleSyntax | import type の明示を強制 | バンドルサイズ最適化 |
ちゃんと使うためのポイント
-
まず
strict: trueを有効にする。新規プロジェクトでは必須 - フレームワーク生成のtsconfigは理解してから変更する
moduleResolution: "bundler"がフロントエンド開発の現在の推奨pathsの設定はTypeScriptだけでなくバンドラー側も合わせる- 困ったときは公式ドキュメントのTSConfig Referenceを確認する
参考リンク
- TSConfig リファレンス（日本語） — 全コンパイラオプションの公式リファレンス
- What is a tsconfig.json（英語） — tsconfig.jsonの役割の公式説明
