TypeScriptの基礎 - tsconfig.jsonのソースを表示

== 概要 ==
tsconfig.jsonは、TypeScriptプロジェクトにおけるコンパイラの動作を制御する設定ファイルである。<br>
<br>
このファイルが存在するディレクトリがプロジェクトルートとして認識され、TypeScriptコンパイラ (tsc) はここで定義されたオプションに従って処理を行う。<br>
<br>
tsconfig.jsonファイルが担う主な役割を以下に示す。<br>
<br>
<center>
{| class="wikitable"
|+ tsconfig.jsonファイルの主な役割
! 役割 !! 説明
|-
| コンパイラの動作制御 || 出力するJavaScriptのバージョンやモジュール形式を指定する。
|-
| 型チェックの厳格度設定 || strictオプション等で型安全性のレベルを調整する。
|-
| コンパイル対象の管理 || includeおよびexcludeでコンパイル対象ファイルを指定する。
|-
| 設定の継承 || extendsで共通設定を再利用し、環境ごとの設定を分離する。
|}
</center>
<br><br>

== tsconfig.jsonの基本 ==
==== ファイルの役割 ====
tsconfig.jsonファイルは、TypeScriptコンパイラへの指示書として機能する。<br>
このファイルをプロジェクトルートに配置することにより、<code>tsc</code> コマンドを引数無しで実行した時に自動的に読み込まれる。<br>
<br>
また、コードエディタ (Zed等) もこのファイルを参照することにより、型チェックや補完機能を適切に動作させる。<br>
<br>
下表に、主な設定カテゴリを示す。<br>
<br>
<center>
{| class="wikitable"
|+ tsconfig.jsonファイルの主な設定カテゴリ
! 設定カテゴリ !! 説明
|-
| compilerOptions || コンパイラの動作を細かく制御するオプション群
|-
| include || コンパイル対象に含めるファイルのグロブパターン
|-
| exclude || コンパイル対象から除外するファイルのグロブパターン
|-
| extends || 別のtsconfig.jsonから設定を継承するためのパス
|}
</center>
<br>
==== 基本構造 ====
tsconfig.jsonファイルの基本的な構造を以下に示す。<br>
<br>
 <syntaxhighlight lang="json">
 {
    "compilerOptions": {
       "target": "ES2020",
       "module": "ESNext",
       "strict": true,
       "outDir": "./dist",
       "rootDir": "./src"
    },
    "include": ["src/**/*"],
    "exclude": ["node_modules", "dist"]
 }
 </syntaxhighlight>
<br>
下表に、各プロパティの役割を示す。<br>
<br>
<center>
{| class="wikitable"
|+ tsconfig.json プロパティ一覧
! プロパティ !! 説明
|-
| <code>compilerOptions</code> || コンパイラの動作を制御するオプション群
|-
| <code>include</code> || コンパイル対象ファイルのグロブパターン
|-
| <code>exclude</code> || 除外するファイルのグロブパターン (デフォルト: node_modules, outDir)
|-
| <code>extends</code> || 継承元のtsconfig.jsonへのパス
|-
| <code>files</code> || コンパイル対象ファイルの明示的なリスト
|}
</center>
<br>
==== tsconfig.jsonファイルの生成 ====
<code>tsc --init</code> コマンドを実行すると、コメント付きのデフォルト設定を持つtsconfig.jsonファイルが自動生成される。<br>
<br>
 tsc --init
<br>
<u>生成されたファイルには、多数のオプションがコメントアウトされた状態で含まれており、必要なオプションのコメントを外して有効化する形式になっている。</u><br>
プロジェクトの要件に合わせて内容を編集する。<br>
<br><br>

== 主要なコンパイラオプション ==
==== strict ====
<code>strict</code> は、複数の厳格な型チェックオプションを一括で有効化するオプションである。<br>
新規プロジェクトでは、<u>true</u> に設定することを推奨する。<br>
<br>
<center>
{| class="wikitable"
|+ strict: true で有効化されるオプション
! オプション !! 説明
|-
| <code>strictNullChecks</code> || <u>null</u> と <u>undefined</u> の型を厳密に区別する。
|-
| <code>noImplicitAny</code> || 型が推論されない値を <u>any</u> として暗黙的に扱わない。
|-
| <code>strictFunctionTypes</code> || 関数の型チェックを厳格に行う。
|-
| <code>strictBindCallApply</code> || bind、call、applyの引数型を厳格にチェックする。
|-
| <code>strictPropertyInitialization</code> || クラスプロパティの初期化を強制する。
|-
| <code>noImplicitThis</code> || thisの型が暗黙的に <u>any</u> になることを防ぐ。
|-
| <code>useUnknownInCatchVariables</code> || catch節の変数をunknown型として扱う。
|-
| <code>alwaysStrict</code> || 全てのファイルにuse strictを付与する。
|}
</center>
<br>
===== strictNullChecks =====
<code>strictNullChecks</code> を有効にすると、<u>null</u> と <u>undefined</u> が独立した型として扱われる。<br>
<br>
 <syntaxhighlight lang="typescript">
 // strictNullChecks : true の場合
 let name: string = null;  // エラー: nullはstringに代入不可
 
 // nullを許容するにはユニオン型を使用する
 let name: string | null = null;  // 正常
 
 // undefinedも同様
 let value: number | undefined = undefined;  // 正常
 </syntaxhighlight>
<br>
このオプションを有効にすることで、<code>NullPointerException</code> 相当のバグを型チェックの段階で事前に発見できる。<br>
<br>
===== noImplicitAny =====
<code>noImplicitAny</code> を有効にすると、TypeScriptが型を推論できない箇所で暗黙的に <code>any</code> 型を割り当てることを禁止する。<br>
<br>
 <syntaxhighlight lang="typescript">
 // noImplicitAny : true の場合
 function greet(name) {  // エラー: nameの型注釈が必要
    return "Hello, " + name;
 }
 
 // 型注釈を明示する必要がある
 function greet(name: string) {  // 正常
    return "Hello, " + name;
 }
 </syntaxhighlight>
<br>
全てのパラメータと変数に明示的な型注釈が必要となるため、型安全性が向上する。<br>
<br>
==== target ====
<code>target</code> は、コンパイル後に生成されるJavaScriptのバージョンを指定する。<br>
<br>
<center>
{| class="wikitable"
|+ targetの主な選択肢
! 値 !! 説明
|-
| <code>ES3</code> || 最も古いバージョン<br>広い互換性が必要な場合
|-
| <code>ES5</code> || IEを含む幅広いブラウザ対応が必要な場合
|-
| <code>ES2015</code> || アロー関数、クラス、let / const等が使用可能
|-
| <code>ES2020</code> || Optional chaining、Nullish coalescing等が使用可能 (推奨)
|-
| <code>ES2022</code> || クラスフィールド、top-level await等が使用可能
|-
| <code>ESNext</code> || 最新のECMAScript仕様に準拠
|}
</center>
<br>
モダンプロジェクトでは、ES2020以上を推奨する。<br>
ターゲットが高いほど、コンパイル後のコードが簡潔になり、ポリフィルの必要性が減る。<br>
<br>
==== module ====
<code>module</code> は、出力するJavaScriptのモジュールシステムを指定する。<br>
<br>
<center>
{| class="wikitable"
|+ moduleの主な選択肢
! 値 !! 説明
|-
| <code>CommonJS</code> || Node.jsのデフォルトモジュール形式 (require / exports)
|-
| <code>ES2015</code> / <code>ES2020</code> || ESモジュール形式 (import / export)
|-
| <code>ESNext</code> || 最新のESモジュール<br>Vite環境で推奨
|-
| <code>AMD</code> || 非同期モジュール定義 (Webブラウザ向け旧形式)
|-
| <code>UMD</code> || CommonJSとAMDの両方に対応するユニバーサル形式
|}
</center>
<br>
Viteを使用するフロントエンドプロジェクトでは、ESNextを推奨する。<br>
Node.jsプロジェクトでは、<u>CommonJS</u> または <u>NodeNext</u> を使用する。<br>
<br>
==== moduleResolution ====
<code>moduleResolution</code> は、<code>import</code> 文のモジュール解決アルゴリズムを指定する。<br>
<br>
<center>
{| class="wikitable"
|+ moduleResolutionの選択肢
! 値 !! 説明
|-
| <code>bundler</code> || TypeScript 5.0以降推奨<br>Vite / esbuild等のバンドラ向け<br>拡張子の省略が可能
|-
| <code>node</code> || Node.js (CommonJS) の解決アルゴリズム
|-
| <code>node16</code> / <code>nodenext</code> || ESMに対応したNode.js向け解決アルゴリズム
|-
| <code>classic</code> || TypeScript旧来の解決方法<br>現在は非推奨
|}
</center>
<br>
<u>Viteプロジェクトでは <code>bundler</code> を指定することにより、Viteのバンドラ動作に最適化した解決が行われる。</u><br>
<br>
==== jsx ====
<code>jsx</code> は、<u>.tsxファイル</u> 内のJSX構文の処理方法を指定する。<br>
<br>
<center>
{| class="wikitable"
|+ jsxの主な選択肢
! 値 !! 説明
|-
| <code>react-jsx</code> || React 17以降推奨<br><code>jsx()</code> ヘルパー関数に変換<br><code>import React</code> が不要
|-
| <code>react</code> || 従来の形式<br><code>React.createElement()</code> に変換<br>各ファイルで <code>import React</code> が必要
|-
| <code>preserve</code> || JSXをそのまま保持<br>後段のバンドラがJSXを処理する場合に使用
|}
</center>
<br>
React 17以降では、<code>react-jsx</code> を推奨する。<br>
各ファイルへの <u>import React from 'react'</u> の記述が不要になるため、ソースコードが簡潔になる。<br>
<br>
==== paths ====
<code>paths</code> は、インポートパスのエイリアスを定義する。<br>
<code>baseUrl</code> と組み合わせて使用する。<br>
<br>
 <syntaxhighlight lang="json">
 {
    "compilerOptions": {
       "baseUrl": ".",
       "paths": {
          "@/*": ["src/*"],
          "@components/*": ["src/components/*"],
          "@utils/*": ["src/utils/*"]
       }
    }
 }
 </syntaxhighlight>
<br>
上記の設定により、長い相対パスを簡潔なエイリアスで記述できる。<br>
<br>
 <syntaxhighlight lang="typescript">
 // pathsエイリアス使用前
 import { Button } from '../../../components/Button';
 
 // pathsエイリアス使用後
 import { Button } from '@components/Button';
 </syntaxhighlight>
<br>
<u>ただし、Viteプロジェクトでは <code>vite.config.tsファイル</code> 側にも同様のエイリアス設定が必要な点に注意する。</u><br>
<br>
==== その他の重要なオプション ====
===== lib =====
<code>lib</code> は、コンパイル時に利用可能なライブラリの型定義セットを指定する。<br>
<br>
 <syntaxhighlight lang="json">
 {
    "compilerOptions": {
       "lib": ["ES2020", "DOM", "DOM.Iterable"]
    }
 }
 </syntaxhighlight>
<br>
下表に、よく使用される値を示す。<br>
<br>
<center>
{| class="wikitable"
|+ lib オプションのよく使用される値
! 値 !! 説明
|-
| <code>ES2020</code> || ES2020の標準APIの型定義
|-
| <code>DOM</code> || ブラウザのDOM APIの型定義 (document、window等)
|-
| <code>DOM.Iterable</code> || NodeList等のDOM要素を <code>for...of</code> でイテレート可能にする型定義
|-
| <code>ESNext</code> || 最新のECMAScript APIの型定義
|}
</center>
<br>
===== outDir と rootDir =====
<code>outDir</code> は、コンパイル後のJavaScriptファイルの出力先ディレクトリを指定し、<code>rootDir</code> はソースファイルのルートディレクトリを指定する。<br>
<br>
 <syntaxhighlight lang="json">
 {
    "compilerOptions": {
       "rootDir": "./src",
       "outDir": "./dist"
    }
 }
 </syntaxhighlight>
<br>
* <code>rootDir</code>
*: ソースファイルのルートとして <u>./src</u> を指定した場合、<u>src/ディレクトリ</u> 以下のディレクトリ構造を維持したまま出力される。
* <code>outDir</code>
*: コンパイル後のファイルが <code>./distディレクトリ</code> に出力される。
<br>
<u>Viteプロジェクトでは <code>noEmit: true</code> を設定し、tscは型チェックのみを担当させることが一般的である。</u><br>
<br>
===== include と exclude =====
<code>include</code> はコンパイル対象のファイルをグロブパターンで指定し、<code>exclude</code> は除外するファイルを指定する。<br>
<br>
 <syntaxhighlight lang="json">
 {
    "include": ["src/**/*"],
    "exclude": ["node_modules", "dist", "**/*.test.ts"]
 }
 </syntaxhighlight>
<br>
* <code>include</code>
*: 指定しない場合は、<code>exclude</code> に含まれない全てのTypeScriptファイルがコンパイル対象になる。
* <code>exclude</code>
*: デフォルトで <u>node_modules</u>、<u>bower_components</u>、<u>jspm_packages</u> および <u>outDir</u> が除外される。
<br>
===== esModuleInterop =====
<code>esModuleInterop</code> を <u>true</u> に設定すると、ESモジュールとCommonJSモジュールの相互運用が改善される。<br>
<br>
 <syntaxhighlight lang="typescript">
 // esModuleInterop : falseの場合 (CommonJSモジュールのインポート)
 import * as express from 'express';
 
 // esModuleInterop : trueの場合 (より自然な記述が可能)
 import express from 'express';
 </syntaxhighlight>
<br>
<u>express等のCommonJSモジュールをESモジュール構文でインポートする場合に必要となる。</u><br>
<br>
===== isolatedModules =====
<code>isolatedModules</code> を <u>true</u> に設定すると、各ファイルを独立して処理できないコード構成を禁止する。<br>
<br>
esbuildやSWCは単一ファイルを個別にトランスパイルするため、ファイルをまたいだ型情報を参照できない。<br>
このオプションを有効にすることで、これらのツールとの互換性を確保できる。<br>
<br>
 <syntaxhighlight lang="typescript">
 // isolatedModules : true の場合、型のみの再exportは明示が必要
 export { SomeType } from './types';       // エラー : 型のみのexportには、export typeを使用する必要がある。
 
 // 正しい記述
 export type { SomeType } from './types';  // 型専用export構文を明示的に使用
 </syntaxhighlight>
<br>
Viteプロジェクトでは <u>true</u> を推奨する。<br>
<br><br>

== Tauri + Viteプロジェクトでの推奨設定 ==
==== tsconfig.jsonファイルの推奨設定 ====
Tauri + Viteプロジェクトでの推奨設定を以下に示す。<br>
<br>
 <syntaxhighlight lang="json">
 {
    "compilerOptions": {
       "target": "ES2020",
       "module": "ESNext",
       "lib": ["ES2020", "DOM", "DOM.Iterable"],
       "moduleResolution": "bundler",
       "jsx": "react-jsx",
       "strict": true,
       "esModuleInterop": true,
       "isolatedModules": true,
       "skipLibCheck": true,
       "forceConsistentCasingInFileNames": true,
       "resolveJsonModule": true,
       "noEmit": true
    },
    "include": ["src"]
 }
 </syntaxhighlight>
<br>
==== 各オプションの選定理由 ====
下表に、各オプションを選定した理由を示す。<br>
<br>
<center>
{| class="wikitable"
|+ 各オプションの選定理由
! オプション !! 選定理由
|-
| <code>target: "ES2020"</code> || TauriがサポートするWebViewがES2020を十分にサポートしているため、<br>モダンな構文を利用できる。
|-
| <code>module: "ESNext"</code> || ViteはESモジュールを前提として最適化を行うため、ESNextが最適である。
|-
| <code>lib: ["ES2020", "DOM", "DOM.Iterable"]</code> || WebブラウザAPIとES2020の標準APIを使用するフロントエンド開発に必要な型定義を含む。
|-
| <code>moduleResolution: "bundler"</code> || Viteのバンドラ動作に最適化されており、<br>拡張子の省略や <code>exports</code> フィールドの解決に対応する。
|-
| <code>jsx: "react-jsx"</code> || React 17以降の推奨形式であり、各ファイルへの <code>import React</code> が不要になる。
|-
| <code>strict: true</code> || 最大レベルの型安全性を確保し、潜在的なバグを早期に検出する。
|-
| <code>esModuleInterop: true</code> || CommonJSモジュールをESモジュール構文でインポートできるようにし、<br>既存ライブラリとの互換性を確保する。
|-
| <code>isolatedModules: true</code> || Viteがesbuildでトランスパイルするため、各ファイルを独立して処理できる構成を強制する。
|-
| <code>skipLibCheck: true</code> || 外部ライブラリの型定義ファイル (.d.ts) の型チェックをスキップし、<br>ビルド速度を向上させる。
|-
| <code>forceConsistentCasingInFileNames: true</code> || ファイル名の大文字/小文字の一貫性を強制し、<br>大文字・小文字を区別しないファイルシステムでの問題を防ぐ。
|-
| <code>resolveJsonModule: true</code> || JSONファイルをモジュールとしてインポートできるようにする。
|-
| <code>noEmit: true</code> || tscはJavaScriptファイルを生成せず、型チェックのみを行う。<br>実際のトランスパイルはViteが担当する。
|}
</center>
<br><br>

== tsconfigの継承 (extends) ==
==== 基本的な使用方法 ====
<code>extends</code> プロパティを使用することにより、別のtsconfig.jsonファイルから設定を継承できる。<br>
<br>
継承元の設定をベースとして、継承側で必要なオプションのみを上書きすることが可能である。<br>
<br>
 <syntaxhighlight lang="json">
 {
    "extends": "./tsconfig.base.json",
    "compilerOptions": {
       "jsx": "react-jsx",
       "lib": ["ES2020", "DOM", "DOM.Iterable"]
    }
 }
 </syntaxhighlight>
<br>
継承における重要なルールを以下に示す。<br>
* <code>compilerOptions</code> のプロパティはマージされる。
*: 継承側で同じプロパティを再定義すると、そのプロパティが上書きされる。
* <u>files</u>、<u>include</u>、<u>exclude</u> は継承側で指定すると完全に上書きされる。
*: マージではなく置換となるため注意が必要である。
<br>
また、npmパッケージとして配布されている公式の基本設定を使用することもできる。<br>
<br>
 npm install --save-dev @tsconfig/node18
<br>
 <syntaxhighlight lang="json">
 {
    "extends": "@tsconfig/node18/tsconfig.json",
    "compilerOptions": {
       "outDir": "./dist"
    }
 }
 </syntaxhighlight>
<br>
==== 設定ファイルの分割例 ====
大規模なプロジェクトでは、複数の環境向けに設定ファイルを分割することが有効である。<br>
<br>
フロントエンドとバックエンドを含むモノリポ構成での分割例を以下に示す。<br>
<br>
* tsconfig.base.json (共通設定)
*: <syntaxhighlight lang="json">
 {
    "compilerOptions": {
       "target": "ES2020",
       "module": "ESNext",
       "strict": true,
       "esModuleInterop": true,
       "forceConsistentCasingInFileNames": true,
       "skipLibCheck": true
    }
 }
 </syntaxhighlight>
*: <br>
* tsconfig.app.json (フロントエンド用)
*: <syntaxhighlight lang="json">
 {
    "extends": "./tsconfig.base.json",
    "compilerOptions": {
       "moduleResolution": "bundler",
       "jsx": "react-jsx",
       "lib": ["ES2020", "DOM", "DOM.Iterable"],
       "isolatedModules": true,
       "noEmit": true
    },
    "include": ["src"]
 }
 </syntaxhighlight>
*: <br>
* tsconfig.node.json (Node.jsツール用)
*: <syntaxhighlight lang="json">
 {
    "extends": "./tsconfig.base.json",
    "compilerOptions": {
       "module": "CommonJS",
       "moduleResolution": "node",
       "lib": ["ES2020"],
       "outDir": "./dist"
    },
    "include": ["scripts", "vite.config.ts"]
 }
 </syntaxhighlight>
<br>
<u>この分割により、アプリケーションコードとNode.jsツールでそれぞれ最適な設定を適用できる。</u><br>
<br><br>

== 関連情報 ==
* [[TypeScriptの基礎 - 概要と開発環境]]
* [[TypeScriptの基礎 - 型注釈とプリミティブ型]]
* [[TypeScriptの基礎 - 型推論]]
<br><br>


{{#seo:
|title={{PAGENAME}} : Exploring Electronics and SUSE Linux | MochiuWiki
|keywords=MochiuWiki,Mochiu,Wiki,Mochiu Wiki,Electric Circuit,Electric,pcb,Mathematics,AVR,TI,STMicro,AVR,ATmega,MSP430,STM,Arduino,Xilinx,FPGA,Verilog,HDL,PinePhone,Pine Phone,Raspberry,Raspberry Pi,C,C++,C#,Qt,Qml,MFC,Shell,Bash,Zsh,Fish,SUSE,SLE,Suse Enterprise,Suse Linux,openSUSE,open SUSE,Leap,Linux,uCLnux,電気回路,電子回路,基板,プリント基板
|description={{PAGENAME}} - 電子回路とSUSE Linuxに関する情報 | This page is {{PAGENAME}} in our wiki about electronic circuits and SUSE Linux
|image=/resources/assets/MochiuLogo_Single_Blue.png
}}

__FORCETOC__
[[カテゴリ:Rust]][[カテゴリ:TypeScript]]