TypeScript + Node.js プロジェクトのはじめかた

TypeScript + Node.js プロジェクトのはじめかた:

TL;DR

https://github.com/nobutakaoshiro/typescript-node-base をコピペして使ってね

この記事の趣旨

以下の設定を適用した TypeScript + Node.js のプロジェクトを作成します。

項目	パッケージ
コンパイラ(トランスパイラ)	typescript
開発サポート	ts-node / ts-node-dev / rimraf / npm-run-all
エディター設定	EditorConfig
バージョン管理	git

動作環境

node と npm はインストール済みとします。

$ node -v 
v10.15.1 
$ npm -v 
6.4.1 

また、今回の記事はmacOSにて検証しております。

$ uname -v 
Darwin Kernel Version 18.2.0: Thu Dec 20 20:46:53 PST 2018; root:xnu-4903.241.1~1/RELEASE_X86_64 
 
$ sw_vers 
ProductName:    Mac OS X 
ProductVersion: 10.14.3 
BuildVersion:   18D42 

Linux環境だと手順はほぼ同じだと思いますが、Windows環境の場合は読み替えが必要になるかもしれません。

初期設定

TypeScript + Node.js プロジェクトを作成していきます。

1. プロジェクトディレクトリの作成

~/

mkdir typescript-node-base 
cd typescript-node-base 

2. git 初期化

~/typescript-node-base

git init 

.gitignore の生成

不要なファイルを Git にコミットしないようにするため、 .gitignore ファイルを生成します。

~/typescript-node-base

cat > .gitignore 

以下をコピペして Ctrl+D を押下します。

~/typescript-node-base/.gitignore

# macOS 
### https://raw.github.com/github/gitignore/07c730e1fccfe0f92b29e039ba149d20bfb332e7/Global/macOS.gitignore 
.DS_Store 
.AppleDouble 
.LSOverride 
Icon 
._* 
.DocumentRevisions-V100 
.fseventsd 
.Spotlight-V100 
.TemporaryItems 
.Trashes 
.VolumeIcon.icns 
.com.apple.timemachine.donotpresent 
.AppleDB 
.AppleDesktop 
Network Trash Folder 
Temporary Items 
.apdisk 
 
# Linux 
### https://raw.github.com/github/gitignore/07c730e1fccfe0f92b29e039ba149d20bfb332e7/Global/Linux.gitignore 
*~ 
.fuse_hidden* 
.directory 
.Trash-* 
.nfs* 
 
# Windows 
### https://raw.github.com/github/gitignore/07c730e1fccfe0f92b29e039ba149d20bfb332e7/Global/Windows.gitignore 
Thumbs.db 
ehthumbs.db 
ehthumbs_vista.db 
*.stackdump 
[Dd]esktop.ini 
$RECYCLE.BIN/ 
*.cab 
*.msi 
*.msm 
*.msp 
*.lnk 
 
# node.js 
### https://raw.github.com/github/gitignore/07c730e1fccfe0f92b29e039ba149d20bfb332e7/Node.gitignore 
logs 
*.log 
npm-debug.log* 
yarn-debug.log* 
yarn-error.log* 
pids 
*.pid 
*.seed 
*.pid.lock 
lib-cov 
coverage 
.nyc_output 
.grunt 
bower_components 
.lock-wscript 
build/Release 
node_modules/ 
jspm_packages/ 
typings/ 
.npm 
.eslintcache 
.node_repl_history 
*.tgz 
.yarn-integrity 
.env 
.next 

(オプション) または gibo を使って .gitignore を生成する

• gibo: fast access to .gitignore boilerplate - https://github.com/simonwhitaker/gibo
  

.gitignore を生成するツール gibo を利用している場合は、以下のコマンドで前述の .gitignore と同じ内容が生成できます。

~/typescript-node-base

gibo dump macos linux windows node > .gitignore 

あとは必要に応じて .gitignore を修正してください。

3. (オプション) EditorConfig の設定

• EditorConfig - https://editorconfig.org/
  

様々なエディターでの文字コードや改行コード、タブorスペース等の設定を共通化できる、 EditorConfig の設定を追加します。

~/typescript-node-base

cat > .editorconfig 

以下をコピペして Ctrl+D を押下します。

~/typescript-node-base/.editorconfig

root = true 
 
[*] 
charset = utf-8 
end_of_line = lf 
insert_final_newline = true 
indent_size = 2 
indent_style = space 
trim_trailing_whitespace = true 
 
[Makefile] 
indent_size = 4 
indent_style = tab 
 
[*.{md,markdown}] 
insert_final_newline = false 
trim_trailing_whitespace = false 
 
[*.json] 
insert_final_newline = false 

.editorconfig はお好みで書き換えてください。

3. package.json の生成

~/typescript-node-base

npm init -y 

npm init で package.json を生成するとバージョン番号がデフォルトで 1.0.0 になります。

個人的な好みですが、開発中は セマンティック バージョニング 2.0.0に合わせてバージョンを 0.1.0 としておきます。

~/typescript-node-base/package.json

{ 
  "name": "typescript-node-base", 
- "version": "1.0.0", 
+ "version": "0.1.0", 
  "main": "index.js", 
... 

4. typescript パッケージの追加

~/typescript-node-base

npm install typescript 
npm install -D @types/node 

tsconfig.json 生成

~/typescript-node-base

npx tsc --init 

tsc --init を実行すると、 tsconfig.json が生成されます。

プロジェクトに合わせて tsconfig.json を修正します(以下はコメントを除いて表記しています)。

~/typescript-node-base/tsconfig.json

{ 
  "compilerOptions": { 
-   "target": "es5", 
+   "target": "ES2018", 
    "module": "commonjs", 
+   "sourceMap": true, 
+   "outDir": "./dist", 
    "strict": true, 
    "esModuleInterop": true, 
- } 
+ }, 
+ "include": [ 
+   "src/**/*" 
+ ], 
} 

5. Hello, World!

動作確認のため TypeScript の簡単なプログラムを作ってみます。

~/typescript-node-base

mkdir src 
touch src/index.ts 

src/index.ts をエディターで開き、以下の内容を入力して保存します。

~/typescript-node-base/src/index.ts

function hello(name: string) { 
  return `Hello, ${name}!`; 
} 
 
console.log(hello("World")); 

src/index.ts ファイルを保存したら、typescript パッケージに同梱する tsc コマンドを実行します。

~/typescript-node-base

npx tsc 

すると、 tsconfig.json の設定に従って TypeScript から JavaScript への変換が行われ、dist/index.js と dist/index.js.map が生成されます。

~/typescript-node-base

ls dist 
#=> index.js      index.js.map 

生成された index.js を実行してみましょう。

~/typescript-node-base

node dist/node.js 

以下のメッセージが表示されれば成功です。

実行結果

Hello, World! 

6. 開発の効率をあげる (ts-node & ts-node-dev)

tsc コマンドでコンパイルして node でプログラムが実行できるようになりました。

しかし、ソースコードを修正するたびに tsc を実行し、さらにそのあと node コマンドを実行するのは手間がかかりますね。

開発効率をあげるため、 tsc -> node の実行を自動的に行ってくれる ts-node パッケージを追加します。

ts-node パッケージの追加

~/typescript-node-base

npm install -D ts-node 

パッケージが追加されたら ts-node コマンドを実行してみましょう。

~/typescript-node-base

npx ts-node src/index.ts 

実行結果

Hello, World! 

通常の node コマンドで JavaScript を実行するかのように、ts-node で TypeScript ファイルが実行できました。

ts-node-dev パッケージの追加

ts-node で少し効率があがりました。ただ、ソースコードを修正するたび、毎回手動で実行する必要があります。

さらに開発効率をあげるため、ソースコードの変更を検知するたびに自動的に再実行してくれる ts-node-dev パッケージを追加します。

~/typescript-node-base

npm install -D ts-node-dev 

パッケージが追加されたら ts-node-dev コマンドを実行してみましょう。

注: APIサーバーのように一度実行すると動き続けるプログラムではなく、この記事のHello Worldプログラムのように1度実行するとプロセスが終了するプログラムの場合は、ts-node-dev に --respawn オプションをつけます。

npx ts-node-dev --respawn src/index.ts 

ts-node-dev が起動したら、エディターで src/index.ts を修正して保存します。

~/typescript-node-base/src/index.ts

function hello(name: string) { 
   return `Hello, ${name}!`; 
} 
 
- console.log(hello("World")); 
+ console.log(hello("TypeScript")); 

すると、ソースコードの変更を検知して、自動的にプログラムが再実行されます。

実行結果

Using ts-node version 8.0.2, typescript version 3.3.3 
Hello, World! 
[INFO] 15:19:41 Restarting: /Users/<USER_NAME>/typescript-node-base/src/index.ts has been modified 
Using ts-node version 8.0.2, typescript version 3.3.3 
Hello, TypeScript! 

自動で再実行されました！

ts-node-dev を終了する時は Ctrl+C を押下します。

^C 

npm-scripts に dev と dev:watch を追加する

ts-node と ts-node-dev を簡単に呼び出せるようにするため package.json を修正します。

~/typescript-node-base/package.json

{ 
  "name": "typescript-node-base", 
  "version": "0.1.0", 
  "main": "index.js", 
  "scripts": { 
-    "test": "echo \"Error: no test specified\" && exit 1" 
+    "dev": "ts-node src/index.ts", 
+    "dev:watch": "ts-node-dev --respawn src/index.ts" 
  }, 
  ... 

修正して保存したら動作確認を行います。

# 1回実行 
npm run dev 
 
# 変更検知 
npm run dev:watch 

これで TypeScript で Node.js のプログラムが開発できるようになりました。

7. rimraf npm-run-all パッケージの追加と npm-scripts に clean / tsc / build / start を追加

tsc でビルドを行ったファイルを一括削除できるように、rimraf パッケージを追加します。

また、複数のnpm-scriptsのコマンドを実行できるように npm-run-all パッケージも併せて追加します。

~/typescript-node-base

npm install -D rimraf npm-run-all 

そして、package.json を以下のように修正します。

~/typescript-node-base/package.json

{ 
  "name": "typescript-node-base", 
  "version": "0.1.0", 
-  "main": "index.js", 
+  "main": "dist/index.js", 
  "scripts": { 
    "dev": "ts-node ./src/index.ts", 
-    "dev:watch": "ts-node-dev --respawn src/index.ts" 
+    "dev:watch": "ts-node-dev --respawn src/index.ts", 
+    "clean": "rimraf dist/*", 
+    "tsc": "tsc", 
+    "build": "npm-run-all clean tsc", 
+    "start": "node ." 
  }, 
  ... 

package.json を修正したら動作確認をしましょう。

~/typescript-node-base

# TypeScript -> JavaScript に変換 
npm run build 
 
# 生成されたJavaScriptを実行 
npm run start 
## または 
npm start 
 
# 生成されたファイルを削除 
npm run clean 

最終的にはビルドで生成された JavaScript ファイルを Node.js で動作させることになります。
build と start はそのためのものです。

8. ソースコードのバージョン管理

これまでのコードをgitにコミットしましょう。

tscコマンド実行後に生成される /dist はgitの対象外としたいので、.gitignoreファイルに以下の1行を追加します。

~/typescript-node-base/.gitignore

# 最後に以下の行を追加 
/dist 

~/typescript-node-base

git status 
git add . 
git commit -m "First commit" 

これでgitへのコミットが完了しました。

あとは必要なパッケージや設定を行い、TypeScript + Node.js でのアプリケーション開発を楽しみましょう！

成果物

• https://github.com/nobutakaoshiro/typescript-node-base