tsconfig.json について

tsconfig.json とは？

tsconfig.jsonをアプリケーションのルートディレクトリに指定うすることで、typscriptをどのようにコンパイルするかを指定することができます。

またこの記事では公式サイトを参考に記述しております。

ファイルの指定

このセクションではファイルをコンパイル対象、または除外する設定について説明します。

Exclude

excludeを指定することでコンパイル対象となるfileを除外することができます。

{
  "exclude": "test.ts",
}

extends

すでに存在している tsconfig.json ファイルを継承することができます。

例えば base.json というファイルがあり

{
  "compilerOptions": {
    "noImplicitAny": true,
    "strictNullChecks": true
  }
}

これを tsconfig.json ファイルで

{
  "extends": "./base"
}

の様に書くことで base.json を継承することができます。

複数の tsconfig.json があり、共通機能を切り出したいときに便利ですね。

files

プロジェクトに含むファイルをファイル名で指定することができます。

{
  "compilerOptions": {},
  "files": [
    "core.ts",
    "sys.ts",
    "types.ts",
    "scanner.ts"
  ]
}

小さなプロジェクトなど、余分なファイルを含みたくないときに便利ですね。

include

上記の files はファイル名で単一ファイルを指定していましたが、 include では正規表現を使い複数のファイルを一括で指定することができます。

{
  "include": ["src/**/*", "tests/**/*"]
}

include で使用できる正規表現は下記になります。

* : 0または1以上の任意の文字(但し / は含みません)
? : 1以上の任意の文字(但し / は含みません)
**/ : 任意の入れ子状のディレクトリ

また拡張子を指定しなかった場合、デフォルトで .ts, .tsx, .d.ts ファイルを含めます。 allowJS を指定して場合、 .js, .jsx を含めます。

references

プロジェクトリファレンスはプロジェクトを論理的に分割し、ビルド時間や編集を最適化することができます。プロジェクトリファレンスの説明については別記事で書きたいと思います。

typeAcquisition

Javascriptをエディタで開いているときに, Typescriptでは自動で DefinitelyTyped の @types を node_modules へ追加します。このような処理を automatic type acquisition といい、 typeAcquisition にてカスタマイズすることができます。

もしこの機能をoffにしたければ下記のように設定します。

{
  "typeAcquisition": {
    "enable": false
  }
}

node_modules にはないが @types を含めたい場合は下記のように設定します。

{
  "typeAcquisition": {
    "include": ["jest"]
  }
}

また逆に自動で含めたくないモジュールがあったときは下記のように設定します。

{
  "typeAcquisition": {
    "exclude": ["jquery"]
  }
}

プロジェクトオプション

このセクションではコンパイル時のTypescriptの挙動制御についての説明を行います。

allowJs

typescriptのモジュール内で js 拡張子モジュールのインポートを制御します。

たとえば下記のような test.js ファイルがあったとします。

export const TEST = "TEST";

これを main.ts という typescriptモジュール内で読み込んだ時エラーが発生します。

import { TEST } from "./test";

このような状況を防ぐためにこのオプションがあります。

checkJs

上記の allowJS と組み合わせて使用することができます。このオプションを使用することで、それぞれ javascriptファイルに // @ts-check を埋め込んだ状態と同義にすることができ、javascriptモジュールで型チェックを行うことができます。

composite

TODO: check

declaration

.d.ts ファイルを自動で生成します。ちなみにこの d.tsファイルはモジュール内の関数、変数の型を定義したファイルです。

例えば

export let test = "test";

というファイルをコンパイルすると

export let test = "test";

というファイルと

export declare let test: string;

という javascriptファイルの型を定義した d.ts ファイルが生成されます。

declarationMap

d.ts ファイルのソースマップを生成します。

TODO: 更に詳しく

downlevelIteration

TODO: 詳しく書く

importHelpers

incremental

isolatedModules

jsx

.tsx 拡張子のファイルアウトプットの挙動を変更できます。

preserve : .jsx 拡張子で出力します。(但しjsxのシンタックスシュガーは変わりません)
react : React.createElement へ変換された js拡張子ファイルが出力されます
preserve : .js 拡張子で出力します。(但しjsxのシンタックスシュガーは変わりません)

lib

Typescriptでは埋め込みAPI(math)や使用されるブラウザーにて用いる document などの型をデフォルトで定義しています。また target にES6以上を指定したときに、新たに Map などの型が加わります。

このオプションではこうした型の定義を含めるかどうか調整することができます。

例えばブラウザでは使わないのに dom などを使用したくないときには有用ですね。

module

出力ファイルのモジュール import 構文を下記種類を指定することで変更することができます。 CommonJSが好きな人とかには良いですね。

・CommonJS ・UMD ・AMD ・System ・ESNext ・ES2020

noEmit

出力するかを指定することができます。 babelやswcなどサードパーティーのコンパイラーを用いるときに有効ですね。

outDir

出力先ディレクトリを指定することができます。

例えば

{
  "compilerOptions": {
    "outDir": "dist"
  }
}

と指定すれば、出力ファイルは ./dist 配下に生成されます。

outFile

このオプションが指定されたときに全てのグローバルファイルが一つのファイルへまとめられます。

plugins

複数の言語に対しlintチェックなどをエディタで行えるようにするため指定できます。

主に下記のプラグインがあります。

・ ts-sql-plugin : SQLのlintチェックができる・ typescript-styled-plugin : CSSのlintチェックができる・ typescript-eslint-language-service : eslintのlintチェックを行い、コンパイル時にeslintでエラーになっているものをfixし出力する。・ ts-graphql-plugin : GraphQLのlintチェック及び自動フォーマット

removeComments

出力時にコメントを削除できます。

rootDir

この値を元に出力ファイルのディレクトリ構成が変わります。

例えば

MyProj
├── tsconfig.json
├── test
│   ├── a.ts
│   ├── b.ts
│   ├── sub
│   │   ├── c.ts
├── types.d.ts

というディレクトリ構成であった場合、 rootDir が指定されていない時、デフォルト値は d.ts ファイルを含まないファイルの中で、最も長い共通パスになります。この場合 test/ になるため、 outDir が dist の時、出力は

MyProj
├── dist
│   ├── a.ts
│   ├── b.ts
│   ├── sub
│   │   ├── c.ts

となります。

もし出力を

MyProj
├── dist
│   ├── test
│   │   ├── a.js
│   │   ├── b.js
│   │   ├── sub
│   │   │   ├── c.js

と test をルートととしたい場合 rootDir を . と指定することで実現します。

sourceMap

ソースマップファイルの生成を制御できます。

target

出力するjavascriptファイルのESバージョンを指定することができます。基本的に最新のブラウザーは ES6 をサポートしているため、こちらを指定するのが無難です。

厳密なチェック

alwaysStrict

ECMAScriptの strict mode でJavascriptを出力します。またこの時ファイルには “use strict” が付与されます。

ECMAScriptの strict mode は ES5から導入されており、普段は無視してしまう記法でも、パフォーマンスを向上することを目的として実行時にエラーを投げるようになります。

noImplicitAny

Typescriptでは型を指定されておらず、また推測できないときにデフォルトで any 型を指定します。

しかしこの様に暗黙的に指定された方は下記のようなバグが発生してしまいます。

function fn(s) {
  // ここではエラーが起きないが
  console.log(s.subtr(3));
}

// fn内では引数としてstringを想定しているため、 number を渡すとエラーが発生してしまう
fn(42);

このような予期せぬバグを防ぐため noImplicitAny を trueにすると、暗黙的な any を使用できない、つまり型宣言を強制することができます。

noImplicitThis

strict

strictBindCallApply

strictFunctionTypes

strictNullChecks

strictPropertyInitialization

モジュールの解決

allowSyntheticDefaultImports

allowUmdGlobalAccess

baseUrl

esModuleInterop

moduleResolution

paths

preserveSymlinks

rootDirs

typeRoots

types

ソースマップ

inlineSourceMap

inlineSources

mapRoot

sourceRoot

Linterチェック

noFallthroughCasesInSwitch

noImplicitReturns

noUnusedLocals

noUnusedParameters

実験的機能

emitDecoratorMetadata

experimentalDecorators

コマンドライン

preserveWatchOutput

pretty

ウォッチオプション

fallbackPolling

watchDirectory

watchFile

応用

allowUnreachableCode

false を設定すると、 return 以降到達しないコードが合った場合でも警告を出さないようになります。

allowUnusedLabels

false を設定すると使用していない label があった場合でも警告を出さないようになります。そもそもJavascriptで label を使用するのは稀ですが笑

assumeChangesOnlyAffectDirectDependencies

このオプションを変更することで型チェックを犠牲にビルド時間を短縮することができます。