Node.js アプリに TypeScript を導入する

April 19, 2019

既存の Node.js アプリケーションを徐々に TypeScript 化していく場合の導入方法のメモです。

Migrating from JavaScript | TypeScript オフィシャルサイトのこちらのぺージが参考になりますが、クライアントサイドを例書かれているので、サーバーサイドは勝手が違います。

typescript と ts-node のインストール

まず typescriptts-node しましょう。 ts-node はコンパイルせずに直接 ts ファイルを実行できます。

1
$ npm install -g typescript ts-node

または -g ではなく --save-dev としてローカルにインストールします。

tsconfig.json の生成

1
2
$ tsc --init
message TS6071: Successfully created a tsconfig.json file.

tsconfig.json 生成されるので、 "target": "es2018", allowJs: true, "outDir": "./dist" にそれぞれ変更します。理由は Promise などを使えるようにするため、JavaScriptファイルはそのまま使うため、コンパイルしたものを dist ディレクトリに出力するためです。

tsconfig.json

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
{
"compilerOptions": {
/* Basic Options */
"target": "es2018", /* Specify ECMAScript target version: 'ES3' (default), 'ES5', 'ES2015', 'ES2016', 'ES2017', 'ES2018', 'ES2019' or 'ESNEXT'. */
"module": "commonjs", /* Specify module code generation: 'none', 'commonjs', 'amd', 'system', 'umd', 'es2015', or 'ESNext'. */
// "lib": [], /* Specify library files to be included in the compilation. */
"allowJs": true, /* Allow javascript files to be compiled. */
// "checkJs": true, /* Report errors in .js files. */
// "jsx": "preserve", /* Specify JSX code generation: 'preserve', 'react-native', or 'react'. */
// "declaration": true, /* Generates corresponding '.d.ts' file. */
// "declarationMap": true, /* Generates a sourcemap for each corresponding '.d.ts' file. */
// "sourceMap": true, /* Generates corresponding '.map' file. */
// "outFile": "./", /* Concatenate and emit output to single file. */
"outDir": "./dist", /* Redirect output structure to the directory. */
// "rootDir": "./", /* Specify the root directory of input files. Use to control the output directory structure with --outDir. */
// "composite": true, /* Enable project compilation */
// "incremental": true, /* Enable incremental compilation */
// "tsBuildInfoFile": "./", /* Specify file to store incremental compilation information */
// "removeComments": true, /* Do not emit comments to output. */
// "noEmit": true, /* Do not emit outputs. */
// "importHelpers": true, /* Import emit helpers from 'tslib'. */
// "downlevelIteration": true, /* Provide full support for iterables in 'for-of', spread, and destructuring when targeting 'ES5' or 'ES3'. */
// "isolatedModules": true, /* Transpile each file as a separate module (similar to 'ts.transpileModule'). */

/* Strict Type-Checking Options */
"strict": true, /* Enable all strict type-checking options. */
// "noImplicitAny": true, /* Raise error on expressions and declarations with an implied 'any' type. */
// "strictNullChecks": true, /* Enable strict null checks. */
// "strictFunctionTypes": true, /* Enable strict checking of function types. */
// "strictBindCallApply": true, /* Enable strict 'bind', 'call', and 'apply' methods on functions. */
// "strictPropertyInitialization": true, /* Enable strict checking of property initialization in classes. */
// "noImplicitThis": true, /* Raise error on 'this' expressions with an implied 'any' type. */
// "alwaysStrict": true, /* Parse in strict mode and emit "use strict" for each source file. */

/* Additional Checks */
// "noUnusedLocals": true, /* Report errors on unused locals. */
// "noUnusedParameters": true, /* Report errors on unused parameters. */
// "noImplicitReturns": true, /* Report error when not all code paths in function return a value. */
// "noFallthroughCasesInSwitch": true, /* Report errors for fallthrough cases in switch statement. */

/* Module Resolution Options */
// "moduleResolution": "node", /* Specify module resolution strategy: 'node' (Node.js) or 'classic' (TypeScript pre-1.6). */
// "baseUrl": "./", /* Base directory to resolve non-absolute module names. */
// "paths": {}, /* A series of entries which re-map imports to lookup locations relative to the 'baseUrl'. */
// "rootDirs": [], /* List of root folders whose combined content represents the structure of the project at runtime. */
// "typeRoots": [], /* List of folders to include type definitions from. */
// "types": [], /* Type declaration files to be included in compilation. */
// "allowSyntheticDefaultImports": true, /* Allow default imports from modules with no default export. This does not affect code emit, just typechecking. */
"esModuleInterop": true /* Enables emit interoperability between CommonJS and ES Modules via creation of namespace objects for all imports. Implies 'allowSyntheticDefaultImports'. */
// "preserveSymlinks": true, /* Do not resolve the real path of symlinks. */

/* Source Map Options */
// "sourceRoot": "", /* Specify the location where debugger should locate TypeScript files instead of source locations. */
// "mapRoot": "", /* Specify the location where debugger should locate map files instead of generated locations. */
// "inlineSourceMap": true, /* Emit a single file with source maps instead of having a separate file. */
// "inlineSources": true, /* Emit the source alongside the sourcemaps within a single file; requires '--inlineSourceMap' or '--sourceMap' to be set. */

/* Experimental Options */
// "experimentalDecorators": true, /* Enables experimental support for ES7 decorators. */
// "emitDecoratorMetadata": true, /* Enables experimental support for emitting type metadata for decorators. */
}
}

main ファイルを .ts にする

例えばメインファイルの app.js を app.ts にリネームして、 tsc で実行します。

1
2
3
4
5
$ tsc app.ts
app.ts:1:13 - error TS2580: Cannot find name 'require'. Do you need to install type definitions for node? Try `npm i @types/node`.

1 const foo = require('./lib/foo')

上記のように require が失敗するので、 メッセージ通り @types/node を追加します。

1
$ npm install --save-dev @types/node

ts ファイルを js ファイルにコンパイルする

下記の通り、再度コンパイルすると app.js が生成されます。

1
2
3
$ tsc app.ts
$ cat app.js
var foo = require('./lib/foo');

ts ファイルを直接実行する

1
$ ts-node app.ts

そのまま実行できます。これで最低限の導入が完了です。

アプリケーションのコンパイル

1
$ tsc

これで tsconfig.json に従って、 ./dist ディレクトリ以下に ts ファイル (及び js ファイル)はコンパイルされます。

ソースディレクトリを分けるかどうか

最初に載せたページでは、 ts-loader/webpack による逐次コンパイルが前提のため src ディレクトリが出てきますが、 ts-node の登場によってコンパイルを意識せずに実行できるようになるため、 ./src に既存の JS ファイルを全て移動する必要はないと考えます。
但し Web アプリケーション等のようにアセットファイルや設定ファイルを置くディレクトリなどがある場合は、 ソースディレクトリを切った方が対象ファイルの指定が楽になると思います。

Node.js TypeScript

tilfin freelance software engineer