📝

tsconfig.json 設定項目備忘録

2022/11/20に公開

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

型検査オプション

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

リンタオプション

型推論結果には影響を及ぼさず、エラー条件だけを定めるもの。そのうち、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
  • outDir
  • 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. importHelperstslib, @babel/plugin-transform-runtime@babel/runtime への依存を発生させる。役割は似ているが等価ではない。 ↩︎

Discussion