TypeScript と tsconfig.json

この記事ではTypeScript と tsconfig.jsonについて説明します。

TypeScript の基本的な役割から始めて、tsconfig.json がプロジェクトで果たす役割を具体例とともに解説します。

YouTube Video

TypeScript と tsconfig.json

TypeScript は「型のある JavaScript」です。しかし、実務で TypeScript を使いこなすためには、tsconfig.json を正しく理解し、意図を持って設定できることが不可欠です。

なぜ TypeScript が必要なのか

まず、TypeScript を使う最大の理由は **「実行前に間違いを検出できること」**です。

1function add(a: number, b: number): number {
2  return a + b;
3}
4
5add(1, "2");

このコードは JavaScript なら実行時までエラーになりませんが、TypeScript では コンパイル時点で型エラーになります。

この「早期発見」が、開発効率と品質を大きく向上させます。

TypeScript はどのように実行されるのか

原則として、TypeScript はそのままでは実行できません。tsc（TypeScript Compiler）によって JavaScript に変換する必要があります。

1npm install -D typescript
2npx tsc --init

• この操作で tsconfig.json が生成され、TypeScript プロジェクトの振る舞いを定義する中心ファイルが用意されます。

tsconfig.json の役割とは何か

tsconfig.json は、**「どのファイルを」「どんなルールで」「どう変換するか」**を決める設定ファイルです。最初は内容が多く見えますが、重要なのは一部だけです。

1{
2  "compilerOptions": {
3    "target": "ES2020",
4    "module": "ESNext",
5    "strict": true
6  }
7}

• この設定だけでも、現代的で安全な TypeScript 開発が可能になります。

target：出力される JavaScript のバージョン

target は 出力される JavaScript の仕様レベルを決めます。

1"target": "ES2020"

これにより、TypeScript は ES2020 相当の JavaScript を出力します。古い環境向けにする場合は ES5、最新環境のみなら ES2022 などを選びます。

ESNext を指定する場合

1"target": "ESNext"

• ESNext は、現時点で利用可能な最新の JavaScript 構文をそのまま出力する指定です。TypeScript は構文の変換を行わず、Node.js やブラウザなどの実行環境に処理を委ねます。

• そのため ESNext は、最新の Node.js のみを対象とする場合や、Babel やバンドラで別途トランスパイルする場合に適しています。一方で、実行環境が新しい構文に対応していない場合は、ランタイムエラーになる可能性があるため注意が必要です。

module：モジュール形式の指定

module は モジュールの形式を指定します。

1"module": "ESNext"

• フロントエンドやモダンな Node.js 環境では ESNext が基本です。
• CommonJS が必要な場合のみ "CommonJS" を選びます。

strict：型安全性を最大化する設定

strict は TypeScript の安全性を最大化するスイッチです。

1"strict": true

• これを有効にすると、曖昧な型や潜在的なバグを徹底的に検出してくれます。

strict モードと暗黙的な any

strict を有効にすると、TypeScript は「型が推論できない変数」をエラーとして扱うようになります。

1function printValue(value) {
2	console.log(value);
3}

• この変数 value は宣言時に型情報がなく、TypeScript は型を確定できません。その結果、any が暗黙的に使われ、strict モードでは警告（エラー）対象になります。

1function printValue(value: number) {
2	console.log(value);
3}

• このように型を明示すると、TypeScript は「この変数は number だけを扱う」と理解できます。TypeScript では 型を省略できること よりも、型が一意に決まること が重要です。

include / exclude：コンパイル対象ファイルの制御

tsconfig.jsonでは、どのファイルをコンパイル対象にするか、どのファイルを除外するかを指定できます。

1{
2  "include": ["src"],
3  "exclude": ["node_modules"]
4}

• これにより、src 配下のみが TypeScript の管理対象になります。
• exclude に指定した node_modules は、たとえ include に含まれるパス配下にあっても、コンパイル対象から除外されます。

outDir：出力先ディレクトリの指定

出力先を管理するために outDir を指定します。

1"outDir": "dist"

• これにより、コンパイル結果はすべて dist フォルダに出力されます。実務では、ソースコードとビルド成果物を分離する構成が基本です。

rootDir：入力元ディレクトリの指定

rootDir には、TypeScript が「ここを起点にソースコードが存在する」と認識するディレクトリを指定します。

1"rootDir": "src"

• この設定により、TypeScript は src を基準としてディレクトリ構造を保ったまま出力を行います。 例えば、src/index.tsは、dist/index.jsに出力されます。

• rootDir で指定したディレクトリの構造が、outDir にそのまま出力されるイメージです。

esModuleInterop：CommonJS と ES Modules の橋渡し

次に、esModuleInterop を見てみましょう。

1"esModuleInterop": true

• これを有効にすると、CommonJS モジュールを import 構文で安全に扱えます。

1import fs from "fs";

• Node.js を使う場合は ほぼ必須の設定です。

noImplicitAny：暗黙的な any を禁止する

tsconfig.jsonで、型チェックを強化する設定も重要です。

1"noImplicitAny": true

• これにより、暗黙的な any を禁止できます。型を書き忘れた箇所を確実に検出できます。

未使用コードを検出する設定

未使用コードを検出する設定も、保守性向上に役立ちます。

1"noUnusedLocals": true,
2"noUnusedParameters": true

• これにより、不要な変数や引数が即座に警告されます。

lib：利用可能な組み込み API を定義する

lib は、**TypeScript が「存在するとみなす標準 API」**を指定する設定です。

1"lib": ["ES2020", "DOM"]

• この設定により、次のような型が利用可能になります。 ES2020では、Promise、Map、Set などの最新構文が利用できます。 DOMでは、document、window、HTMLElement などのブラウザ APIが利用できます。

フロントエンドでは DOM を含め、Node.js 専用なら DOM を外すことで不要なグローバル型の混入を防げます。

moduleResolution：モジュールの探索ルール

moduleResolution は、**import 文で指定したモジュールを「どのように探すか」**を決めます。

1"moduleResolution": "Node"

主な選択肢は次の2つです。

• Nodeを指定すると、Node.js の解決ルールに従います。
• Classicは、旧来の TypeScript 独自方式ですが、現在はほぼ使用されません。

Node.js やバンドラを使う環境では、明示的に Node を指定するのが安全です。

実務向けの最小構成 tsconfig.json

ここまでを踏まえた、実務向けの最小構成 tsconfig.json は次のようになります。

 1{
 2  "compilerOptions": {
 3    "target": "ES2020",
 4    "module": "ESNext",
 5    "moduleResolution": "Node",
 6    "lib": ["ES2020", "DOM"],
 7    "strict": true,
 8    "rootDir": "src",
 9    "outDir": "dist",
10    "esModuleInterop": true,
11    "noImplicitAny": true,
12    "noUnusedLocals": true,
13    "noUnusedParameters": true
14  },
15  "include": ["src"]
16}

この設定は、フロントエンドとNode.jsのどちらにも対応できる安全な基盤になります。

まとめ：tsconfig.json は「ルールブック」である

tsconfig.json は単なる設定ファイルではなく、**プロジェクト全体に適用される「ルールブック」**です。tsconfig.json によって、次のような重要な方針が明確に定義されます。

• 型安全性のレベルを決めます。
• チームのコーディング規約を決めます。
• 将来のバグを未然に防げます。

tsconfig.json を理解することで、TypeScriptを書くだけでなく、TypeScriptを安全に利用するための設計ができるようになります。

YouTubeチャンネルでは、Visual Studio Codeを用いて上記の記事を見ながら確認できます。 ぜひYouTubeチャンネルもご覧ください。

YouTube Video