TypeScript 的 tsconfig.json 簡介

tsconfig.json 是 TypeScript 編譯時看的編譯設定檔案，能幫助你指定編譯的 TypeScript 檔案，輸出目錄等工作事項，像我在使用 Atom 編輯器時，若你的資料夾裡面有 .ts 檔案，而且你也有裝 IDE 針對 TypeScript 的一些 package，他會幫你掃掃看有無 tsconfig.json，若沒有會給你提示訊息。

tsconfig.json，這個檔案完全允許空白，預設情況下，專案下的根目錄，以及子目錄下的 ts 都會被編譯。

允許空白不代表不可以沒有這個檔案哦! 會得到這個 error: (這裡使用 npm typescript 的 command-line compiler)

$ tsc
error TS6053: File 'tsconfig.json' not found.

你可以自己建立 tsconfig.json 或是透過 tsc --init 來建立 tsconfig.json。但他的 --init 也只是幫你 touch 一隻空的 json 檔案，跟你自己建立沒有不同。

cd 你的目錄
tsc --init

當你建立好 tsconfig.json 之後，可在目錄下執行 tsc 就會編譯相對應的 .js 檔案出來。

未編譯前的目錄結構，這目錄下有我隨意練習的幾隻 ts:
 win@windeMacBook-Air  /tmp/ts_t  tree -L 1
.
├── Person.ts
├── basic.ts
├── class.ts
├── company.ts
├── interface.ts
└── tsconfig.json

tsconfig.json 什麼都不做，執行 tsc: (此圖的 error 是因為語法上有問題，請忽略)

tsc
interface.ts(24,24): error TS2345: 
Argument of type '{ jobTitle: string; years: number; }' 
is not assignable to parameter of type 'Employee'.
Property 'name' is missing in type 
'{ jobTitle: string; years: number; }'.

編譯後再觀察一次目錄:

tree -L 1
.
├── Person.js
├── Person.ts
├── basic.js
├── basic.ts
├── class.js
├── class.ts
├── company.js
├── company.ts
├── interface.js
├── interface.ts
└── tsconfig.json

產生各自對應的 js 檔案。

tsconfig.json 示範:

為 tsconfig 加入一些設定。

{
  "compilerOptions": {
    "target": "es5",
    "module": "commonjs",
    "noImplicitAny": true,
    "removeComments": true,
    "preserveConstEnums": true,
    "outDir": "./dist",
    "sourceMap": true
  },
  "files": [
    "basic.ts",
    "class.ts",
    "company.ts",
    "interface.ts",
    "Person.ts"
  ]
}

compilerOptions

編譯的一些設定。最常用的大概就上面這些，如 outDir 編譯後的結果要輸出到哪裡，還有是否需要 sourceMap,target 是輸出 ECMAScript 版本，預設是 ES5，所以如果你也是 ES5，不寫也罷 :)。

我在我的資料夾底下新增一個 dist 的資料夾，用來放編譯後的結果，這樣 outFile ("outDir": "./dist") 的產出就會往這邊放。

• 另外也有 outFile 的設定，只有 modules 是 amd, system 有支援.

mkdir dist

更多的 compiler options 可以看 https://www.typescriptlang.org/docs/handbook/compiler-options.html。

files

若不指定 files 屬性，TypeScript 預設會編譯根目錄以及子目錄下的 .ts 或是 .tsx。但若指定 files，則只會編譯有指定的.ts 或是 .tsx。

exclude

還有一個很重要的設定是 exclude，用來排除哪些資料夾底下的 TypeScript 檔案。我在上面的示範沒有放，設定像這樣:

  "exclude": [
    "node_modules"
  ]

只不過 node_modules, bower_components, jspm_packages 預設就會被排除了，不用刻意自己增加。 (雖然我看 angular 2 的教學裡面還是有把 node_modules 寫進去 exclude )

include

剛好跟 exclude 相反，include 包含哪些資料夾或檔案，是個 Array:

"include": [
        "src/**/*"
],

files 跟 include 的差別

files 指定包含相對路徑或是絕對路徑的 ts 列表。include 指定一個文件的 glob 匹配表達路徑，如 src/*/.ts 尋找 src 底下所有的 ts 檔案。

files, include 都不是必填，反正預設就是找當下目錄跟子目錄下面的 TypeScript 檔案 (.ts, .d.ts, .tsx 都可)。

注意事項

1. 你不可以在 files 以及 exclude 指定重複的檔案或路徑，若發生，files 具有優先權。
2. 在 files 設定加入的 ts，若自己有參考到其他的 ts 檔，也會一併被參考到 compile 的項目。 比如: a.ts 裡面有 include b.ts 檔案， 那麼就不能把 B.ts 加到 exclude 的項目裡去，除非 a.ts 也在 exclude 裡面。

讓我先把剛剛編譯出來的 js 檔案先刪掉，現在我已經有 tsconfig.json 的詳細設定了，我想要讓他重新編譯，而且把檔案放到 dist 的資料夾底下：

如下:

cd DIR_PATH
DIR_PATH tsc
tree -L 2
.
├── Person.ts
├── basic.ts
├── class.ts
├── company.ts
├── dist
│   ├── Person.js
│   ├── Person.js.map
│   ├── basic.js
│   ├── basic.js.map
│   ├── class.js
│   ├── class.js.map
│   ├── company.js
│   ├── company.js.map
│   ├── interface.js
│   └── interface.js.map
├── interface.ts
└── tsconfig.json

compileOnSave

compileOnSave 也是還沒介紹到的一個屬性，(使用 IDE 時) 可以在儲存 ts 後編譯，但是，只有 Visual Studio 2015 以及 TypeScript 1.8.4 (tsc -v 查看) 以上，或是 atom-typescript 套件可 support。 (我是用 atom-typescript)

compileOnSave 要寫在 tsconfig.json 的第一行。

"compileOnSave": true,
"compilerOptions": {
    // 略
}

多隻 TypeScript 編譯為同一隻

利用 outFile 屬性可以把 ts 整在同一隻檔案，但是 module 的設定只能是 amd 或是 system，我在這裡把 module 改為 system，然後新增 outFile 指定整合出來的檔名為 app-build.js: (有 outFile 的話，outDir 就沒什麼用了。我發現同時有的話)

{
  "compileOnSave": true,
  "compilerOptions": {
    "module": "system",
    "target": "es5",
    "noImplicitAny": true,
    "removeComments": true,
    "preserveConstEnums": true,
    "outFile": "./dist/app-build.js",
    "sourceMap": true
  }

在 tsconfig.json 寫註解

1.8 版本後可在 tsconfig.json 寫註解:

{
  "compileOnSave": true,
  "compilerOptions": {
    "module": "system",
    "target": "es5",
    "noImplicitAny": true,
    "removeComments": true,
    "preserveConstEnums": true, // 單行註解
    "outFile": "./dist/app-build.js", // 全部整合在這一隻 js
    "sourceMap": true
  }
  /*
   * 多行註解
   */
}

結尾

簡單的介紹大概到這邊，刻意不加入 gulp 跟其他 build Tool 是因為 tsc 一些基本的設定先弄懂就應該蠻方便的了，通常我還會把 .ts 放到 src 的資料夾底下，只是在這個 sample 沒有特別擺到 src 資料夾。

與其他 Build Tool 的整合，像是 Gulp, Duo, Grunt, Browserify, webpack，可以參考 https://www.typescriptlang.org/docs/handbook/integrating-with-build-tools.html。