まえがき

TypeScriptを使う機会が多いので、設定ファイルであるtsconfig.jsonの中身を自分で設定できるよう本稿にまとめる。

前提整理

当たり前のことであるが改めてTypeScriptについて整理する。

TypeScript実行方法

以下の2STEPで実行される。

STEP1　hoge.ts（TypeScript） → hoge.js（JavaScript）にコンパイル　【npx tscコマンド】
STEP2　hoge.js（JavaScript）実行

・Node.js環境では、JSファイルはnodeコマンドで実行できる。
・npx tsc ---.tsをしてからnode ---.jsを毎回実行するのは面倒なので、これを1コマンドにまとめたts-nodeコマンドが存在する。

tsconfig.jsonとは？

（tscコマンドが「TS→JSにコンパイルするもの」を踏まえた上で）
・TSファイルをJSファイルにコンパイルするための設定ファイル。
・tscコマンド実行時にTSコンパイラは次の順番でtsconfig.jsonを探す。
　- the current directory
　- the parent direcotry chain
見つかったtsconfig.json内の設定情報をもとに、TSファイルのコンパイルを実行する。

tsconfig.jsonの設定項目

include

コンパイル対象のものを定義する。

拡張子を指定しない、もしくは拡張子にアスタリスクを使用する（hoge.*）場合、デフォルトでは下記の拡張子のファイルのみが対象になる。
・.ts
・.tsx
・.d.ts
ただし、compilerOptions.allowJsがtrueの場合は、下記の拡張子も含む。
・.js
・.jsx

exclude

コンパイル対象外のものを定義する。

なので、例えば exclude に hoge.ts を指定しても、 include に含まれている piyo.ts が hoge.ts を import していれば tsc は hoge.ts を読み込みます。
下記ドキュメントをご確認ください。

excludeは指定しない場合デフォルトで以下の値を含む。
・node_modules
・bower_components
・jspm_packages
・outDirオプションで指定しているディレクトリ配下のファイル
逆に言うと、tsconfig.jsonにexcludeオプションが指定されている場合は、outDirの中身も対象になってしまう。

extends

自分で1からtsconfig.json設定するの面倒じゃない？ということで、baseとなるtsconfig.jsonがGitHubで公開されている。自分が用意したtsconfig.jsonにて、extendsプロパティを定義することで参照できる。

Node14環境でJavaScriptを実行する場合、下記のように設定できる。

{
  "extends": "@tsconfig/node14/tsconfig.json",
  "compilerOptions": {
    "preserveConstEnums": true
  },
  "include": ["src/**/*"],
  "exclude": ["node_modules", "**/*.spec.ts"]
}

compilerOptions

プロパティ名	説明
target	出力するJavaScriptのバージョン指定。 Node.jsのバージョン毎に推奨されるtargetがある。設定値（ES5, ES6/ES2015〜ES12/ES2021）
lib	・targetで指定したESモジュールに含まれない、けど使いたいライブラリをここで指定する。・"組み込みライブラリ"という呼び方がしっくりくるかな。・targetで指定しているJSのバージョンに含まれているものは暗黙的に指定されるが、改めて指定してもよい。ブラウザ上で動かすJavaScriptなら`dom`を指定して`window, document`のような型情報を読み込む👍 ※参考
module	出力されるJavaScriptが、どのようにモジュールを読み込むか指定する。設定値・commonjs：バックエンド(NodeJS)の場合・esnext/es6：フロントエンド(JavaScript)の場合その他オプション
types	デフォルトでは、すべての表示されている@typesパッケージがコンパイル時にインクルードされる。 typesを設定すると、リストに列挙したパッケージのみがインクルードされる。 `"types": ["node"`の場合、`./node_modules/@types/node`のみコンパイルされる。参考
outDir	コンパイル結果の出力先ディレクトリ。未指定だとtsファイルと同ディレクトリに出力される。であれば設定値としては「.build」が良さそう。
outFile	コンパイル結果を一つのファイルにまとめる（true/false） outFileを指定した場合はoutDirオプションは無視される。パンドラ的機能だから使わない方がいい？参考
rootDir	コンパイル対象のソースコードが含まれるルートディレクトリ。参考
baseUrl	非絶対モジュール名を解決するためのベースディレクトリ。参考
removeComments	TS→JS変換時にコメントを削除する(true/false※デフォルト)
preserveConstEnums	`const enum`定義をJSコンパイル時に消すか残すか（true/false)
sourceMap	ソースマップファイルの生成を有効化(true/false)。コンパイル前後のマッピングJSONファイル。基本trueで良さそう？
allowJs	JavaScript（.js,.jsx）ファイルをコンパイルの対象へ含めるか(true/false) デフォルトだとts,tsxファイルのみコンパイルされる。モジュール含めコンパイル対象のJSファイルがある場合はtrueにするべき。
checkJs	allowJsと連携動作します。checkJsが有効化されている場合、JavaScript ファイル内のエラーが報告されるようになります。
moduleResolution	tscのモジュールの名前解決の方法設定値・classic（moduleの指定値がAMD・System・ES2015のいずれかである場合) ・node（NodeJSの場合これを選ぶ）
noEmit	JavaScript ソースコード、ソースマップ、型定義のファイルを出力しないようにする。じゃあ何をする？"型チェック"のみを行いたいときに「true」にする。参考
jsx	TypeScriptでJSXを使う場合のオプション。設定値・preserve（変換しない）・react（React17以前の旧変換）・react-jsxdev（React17の新変換inDEVビルド）・react-jsx（React17の新変換inPRODビルド）参考
skipLibCheck	型定義ファイル(*.d.ts)のチェックをスキップする（true/false） △型定義ファイルでエラーが出ても無視する。 ○各ライブラリの型定義ファイルのコンパイル時間の削減参考
allowSyntheticDefaultImports	デフォルトIMPORTできないやつをデフォルトIMPORTする時に、型チェックエラーにならないようにする。 `import * as React from 'react';` が `import React from 'react';`と書けるようになるただこの設定だけだとdefaultインポートしない状態のままなので、`esModuleInterop`をtrueにする。参考
esModuleInterop	defaultをエクスポートしていないモジュールを、ES Modules でデフォルトインポートできるように、コンパイル時にヘルパーメソッドを生成する。 interop(相互運用する)=モジュールをTypeScript(ECMAScript)で使えるようにコンパイルするということ。参考
forceConsistentCasingInFileNames
resolveJsonModule
isolatedModules	コンパイル対象のファイル間の関係性を一切無視して、全てのファイルを1つのモジュールとしてコンパイルする。つまり、コンパイル対象の全ファイルがexport構文を含んでいる必要がある。そうでないとコンパイル時にエラーを出すようにする。
noFallthroughCasesInSwitch
importsNotUsedAsValues
suppressImplicitAnyIndexErrors	オブジェクトへインデックスアクセスしたときの暗黙的anyについてのエラーを抑止する(true/false) `const obj = { x: 10 };` `console.log(obj["foo"]); // エラー`
noUnusedLocals	未使用のローカル変数がエラーになる（true/false）
noUnusedParameters	利用されていない関数の引数がエラーになる（true/false）
strict	これをONにすると以下のオプションが有効になる。 --noImplicitAny --noImplicitThis --alwaysStrict --strictBindCallApply --strictNullChecks --strictFunctionTypes --strictPropertyInitialization strictをtrueにした上で、任意のルールを一つずつfalseにすることが可能。参考
noImplicitAny	暗黙的にanyになる値をエラーにする(true/false)
noImplicitThis	使われているthisの型が暗黙的にanyになる場合にエラーにする。
alwaysStrict	"use strict";を必ず全てのファイルの先頭行に付与する。
strictBindCallApply	bind, call, applyを使用する際に、より厳密に型チェックが行われるようになる。
strictNullChecks	null・undefinedの代入がエラーとなる。下記のように型指定されていればOK。 `let name: string` \| `null;` `name = null; //OK` 参考
strictFunctionTypes	TypeScriptのデフォルトはBivariantlyな挙動だが、このオプションをtrueにするとContravariantlyに型チェックが走るようになる。
strictPropertyInitialization	クラス定義時、インスタンス変数の初期化が宣言時、もしくはコンストラクタのどちらでも行われていない場合にエラーになる。

preserveConstEnums（TSコンパイル時にconst enum定義を消すか消さないか）

・Typescriptでは下記のようなconst enum文をサポートしているが、JavaScriptにコンパイルされると消えてしまう。

Typescript supports costant enumerables, declared through const enum.
This is usually just syntax sugar(糖衣構文) as the costant enums are inlined(1行にまとめられる) in compiled JavaScript.

const enum Tristate {
    True,
    False,
    Unknown
}

var something = Tristate.True;

compiles to

var something = 0;

JavaScriptにコンパイルしてもenum定義を残しておきたい場合に、tsconfig.jsonでpreserverConstEnumsをtrueに設定すると下記のようにコンパイルされる。

var Tristate;
(function (Tristate) {
    Tristate[Tristate["True"] = 0] = "True";
    Tristate[Tristate["False"] = 1] = "False";
    Tristate[Tristate["Unknown"] = 2] = "Unknown";
})(Tristate || (Tristate = {}));

var something = Tristate.True

テンプレート(フロントエンド/JavaScript)

{
  "compilerOptions": {
    "target": "es2020",
    "module": "esnext",
    "lib": ["es2020", "dom"],
    "jsx": "react",
    "sourceMap": true,
    "outDir": "./dist",
    "rootDir": "./src",
    "strict": true,
    "moduleResolution": "node",
    "baseUrl": "src",
    "esModuleInterop": true,
    "experimentalDecorators": true,
    "emitDecoratorMetadata": true,
    "skipLibCheck": true,
    "forceConsistentCasingInFileNames": true
  },
  "include": ["src/**/*"],
  "exclude": ["dist", "node_modules"],
  "compileOnSave": false
}

テンプレート(バックエンド/NodeJS)

{
  "compilerOptions": {
    "target": "es2020",
    "module": "commonjs",
    "lib": ["es2020"],
    "sourceMap": true,
    "outDir": "./dist",
    "rootDir": "./src",
    "strict": true,
    "moduleResolution": "node",
    "baseUrl": "src",
    "esModuleInterop": true,
    "experimentalDecorators": true,
    "emitDecoratorMetadata": true,
    "skipLibCheck": true,
    "forceConsistentCasingInFileNames": true
  },
  "include": ["src/**/*"],
  "exclude": ["dist", "node_modules"],
  "compileOnSave": false
}

Node.js(CommonJS)でESModules構文(import/export)を扱いたい場合のtsconfig.json

ExpressをTypeScriptで書きたい時に利用。以下最低限の設定。

{
  "compilerOptions": {
    "baseUrl": "./server",
    "module": "commonjs", // ES記法(import/export)で書いたものをTS→JS変換時にrequire構文に直してくれる!!
    "esModuleInterop": true
  }
}