tsconfig.json 設定項目備忘録

TypeScript: TSConfig Reference - Docs on every TSConfig option を自分が設定するときに便利な順番で分類。

※TypeScript 4.9時点

ターゲットオプション

トランスパイルターゲットの指定。多くは型検査のルールにも影響するため、Babelを使う場合もオプションを揃えておくのが望ましい。

Babelのドキュメントにも対応関係表がある。

TypeScript	Babel
⭐target downlevelIteration	env targets
⭐useDefineForClassFields	typescript allowDeclareFields
experimentalDecorators	decorators legacy: true
emitDecoratorMetadata	typescript-metadata[1]
jsx	react runtime react development
jsxFactory	react pragma + typescript jsxPragma
jsxFragmentFactory	react pragmaFrag + typescript jsxPragmaFrag
jsxImportSource	react importSource
⭐isolatedModules	なし[2]
⭐module	env modules
alwaysStrict	parserOptions.strictMode
importsNotUsedAsValues preserveValueImports[3]	typescript onlyRemoveTypeImports
preserveConstEnums	なし[4]
⭐esModuleInterop	commonjs importInterop
allowSyntheticDefaultImports	なし[5]

型推論オプション

型推論の結果が変わるもの。

• ⭐strict ... 以下のセット
  • alwaysStrict
  • strictNullChecks
    • T | null や T | undefined が T に縮退しなくなる。 例
  • strictBindCallApply
    • Function の各種メソッドが any に縮退しなくなる。 例
  • strictFunctionTypes
    • コールバック関数の引数が共変でもunifyするようになる結果、型変数の推論優先度が変わることがある。 例
  • strictPropertyInitialization
  • noImplicitAny
    • 宣言型がない場合にflow typeが使われる機会が増える。 例
  • noImplicitThis
    • thisの宣言型がない場合に文脈から型が決定される機会が増える。 例
  • useUnknownInCatchVariables
    • catch (e) の型が unknown になる。
    • 普通は型推論の影響範囲はcatch節内にとどまるが、そうでない例も作れる。 例
• ⭐exactOptionalPropertyTypes
  • x?: T と x?: T | undefined が区別される。 in などの挙動に影響がある。 例
• ⭐noUncheckedIndexedAccess
  • array[index] の戻り値に | undefined がつくようになる。 例

型検査オプション

型推論結果には影響を及ぼさず、エラー条件だけを定めるもの。そのうち、一般的にLinterで代替されないものは以下の通り。

• strict
  • strictPropertyInitialization
• allowUmdGlobalAccess
• ⭐noImplicitOverride
• ⭐noPropertyAccessFromIndexSignature

リンタオプション

型推論結果には影響を及ぼさず、エラー条件だけを定めるもの。そのうち、Linter (ESLint + TypeScript ESLint など)で代替する余地があるものは以下の通り。 (全く同じ挙動をするわけではない)

TypeScript	ESLint
!allowUnreachableCode	no-unreachable
!allowUnusedLabels	no-unused-labels
noFallthroughCasesInSwitch	no-fallthrough
noImplicitReturns	consistent-return
noUnusedLocals noUnusedParameters	@typescript-eslint/no-unused-vars

プロジェクトオプション

モジュール解決

他のモジュール解決を行うプログラム (Node.jsやWebpackなど) と設定を合わせておく必要があります。

TypeScript	Node.js	Webpack
baseUrl		resolve.modules or tsconfig-paths-webpack-plugin
paths		tsconfig-paths-webpack-plugin
⭐moduleResolution		fullySpecified etc.
moduleSuffixes		extensionAlias etc.
noResolve
resolveJsonModule
rootDirs
preserveSymlinks	--preserve-symlinks	resolve.symlinks
forceConsistentCasingInFileNames		case-sensitive-paths-webpack-plugin[6]

プロジェクト

• ルート設定
  • files
  • include
  • exclude
• compilerOptions
  • allowJs
  • ⭐composite
  • incremental
  • tsBuildInfoFile
  • disableReferencedProjectLoad
  • disableSolutionSearching
  • disableSourceOfProjectReferenceRedirect

型検査対象の決定

• checkJS
• skipDefaultLibCheck
• ⭐skipLibCheck

型定義解決

• typeRoots
• types

出力オプション

全般

• ⭐noEmit
  • Babelなどのトランスパイラを併用するときに便利。
  • このオプションのかわりに emitDeclarationOnly を使うこともある。
• noEmitOnError
• ⭐rootDir
  • Babel CLIでディレクトリを指定した場合に相当。
  • 入力ファイルの rootDir からの相対パス = 出力ファイルの outDir からの相対パス
• ⭐outDir
  • Babel CLIの --out-dir に相当。
• outFile
  • Webpackなどのmodule bundlerの役割に近い。
  • ただし、 outFile でできるのは非モジュールコードの連結処理だけで、モジュールベースのプロジェクトには適用できない。

トランスパイラ

主に *.js の出力結果を制御するオプション。

「ターゲットオプション」の項目も参照。

TypeScript	Babel
⭐importHelpers	transform-runtime[7]
noEmitHelpers	なし
removeComments	comments
sourceMap inlineSourceMap	sourceMaps
inlineSources	なし
sourceRoot	sourceRoot
mapRoot	なし
newLine	なし
emitBOM	なし

型定義

*.d.ts の出力結果を制御するオプション。

• declaration
• declarationDir
• declarationMap
• ⭐emitDeclarationOnly
• stripInternal

脚注

1. babel-plugin-typescript-metadataはコミュニティープラグインでBabelの一部ではない。

2. isolatedModules はBabelの制約 (1ファイルごとのトランスパイル) を表現したものであるため、Babel併用時は常に有効化するのが望ましい

3. importsNotUsedAsValues はimport文の副作用に関心がある一方、 preserveValueImports はimport文内の指示子のリストに関心がある。BabelとTypeScriptではimport elisionの挙動が少しずつ異んあっており、オプションも厳密に1対1対応しない。

4. isolatedModules下ではデフォルトで有効なので、厳密に対応するオプションはない。ただし、BabelではoptimizeConstEnumsオプションによって部分的にconst enumの最適化を許すことができる。

5. allowSyntheticDefaultImportsは型チェックにのみ影響する。Babelの挙動に合わせるなら、基本的にはオンにしておいてよい。

6. forceConsistentCasingInFileNamesは単なる追加の検査のため、両方で有効にする必要はない。

7. importHelpers は tslib, @babel/plugin-transform-runtime は @babel/runtime への依存を発生させる。役割は似ているが等価ではない。