【Node.js実戦習得】第6回：Node.jsプロジェクトへのTypeScript導入とtsconfig.jsonの設定

1. Node.jsにおけるTypeScript環境の「不都合な真実」

2. コラム：フロントの「拡張子（.tsx）」とNodeの「ツール（tsx）」の罠

単語	正体	主な役割・意味
.tsx（拡張子）	ファイル形式	TypeScriptのコードの中に、HTML風の構文（JSX）を混ぜて書くためのフロントエンド専用ファイル。
tsx（ツール名）	実行コマンド / CLIツール	TypeScript Execute の略。Node.jsでTypeScriptファイルをコンパイルしながら即座に実行するためだけの実行エンジン。

3. 【ハンズオン】Node.js × TS 開発環境をゼロから構築する

cd ~/nodejs-sample
mkdir node-ts-demo
cd node-ts-demo

# プロジェクトの初期化
npm init -y

npm install -D typescript tsx @types/node

4. 実務でそのまま使える！tsconfig.json の最適モダン設定

# tsconfig.jsonの雛形を自動生成
npx tsc --init

{
  "compilerOptions": {
    /* コンパイル後のJavaScriptのバージョン */
    "target": "ES2022",
    /* Node.jsのモダンな仕様（ESM/CJS自動判別）に対応 */
    "module": "NodeNext",
    /* 外部モジュールの依存関係を正しく解決する設定 */
    "moduleResolution": "NodeNext",
    /* 昔のCommonJSライブラリもimport構文でスムーズに読めるようにする */
    "esModuleInterop": true,
    /* ファイル名の大文字小文字を厳密に区別（MacとLinuxの差分での事故防止） */
    "forceConsistentCasingInFileNames": true,
    /* 厳格な型チェックを全て有効化（安全性の最大化） */
    "strict": true,
    /* node_modules内の外部型定義ファイルのチェックを省いて高速化 */
    "skipLibCheck": true
  },
  /* srcフォルダ配下のTSファイルだけをコンパイル対象にする */
  "include": ["src/**/*"]
}

5. package.json のアップデートと「tsx」での起動確認

{
  "name": "node-ts-core",
  "version": "1.0.0",
  "type": "module",
  "scripts": {
    "dev": "tsx src/index.ts"
  },
  "devDependencies": {
    "@types/node": "^26.x.x",
    "typescript": "^6.x.x",
    "tsx": "^4.x.x"
  }
}

mkdir src
touch src/index.ts

// src/index.ts
const greeting: string = 'Hello, TypeScript × Node.js!';
console.log(greeting);

import os from 'node:os';
console.log('現在使用中のOSプラットフォーム:', os.platform());

npm run dev

実行結果

Hello, TypeScript × Node.js!
現在使用中のOSプラットフォーム: linux (※環境によります)

6. 実践トラブルシューティング：本番ビルドで牙を剥く「TS2591」エラーの罠

src/index.ts:5:16 - error TS2591: Cannot find name 'node:os'. Do you need to install type definitions for node? Try `npm i --save-dev @types/node` and then add 'node' to the types field in your tsconfig.

/* tsconfig.json の修正 */
{
  "compilerOptions": {
    "target": "ES2022",
    "module": "NodeNext",
    "moduleResolution": "NodeNext",
    "types": ["node"],  /* 👈 これを明示的に追加して強制ロック！ */
    "esModuleInterop": true,
    "strict": true,
    "skipLibCheck": true
  },
  "include": ["src/**/*"]
}

7. 実務での注意点①：本番環境では「tsx」は絶対に使わない！

1. 開発時（ローカル）：
   tsx src/index.ts を使い、メモリ上で超高速コンパイルしながらガシガシコードを書く。
2. 本番デプロイ時（ビルド）：
   本番用に公式のコンパイルコマンド（npx tsc）を叩き、TypeScript（.ts）を本物のJavaScript（.js）ファイルとしてディスクに書き出す（←いま熊木くんがテスト成功させたやつね！）。
3. 本番稼働（ランタイム）：
   生成された純粋なJavaScriptを、Node.js本来のコマンド（node dist/index.js）で動かす。

8. 実務での注意点②：型アサーション（as）の乱用は「爆弾」を仕込む行為

フロントエンドなら、最悪それでも自分のブラウザが落ちるだけで済む幕引きになるかもしれないわ。

でもね、バックエンドでそれをやるのは『時限爆弾』をソースコードに埋め込むのと同じよ

 

型アサーション（as）は、コンパイラに対して『黙れ、私の言う型が絶対に正しいんだ』と脅迫する構文よ。

もし、外部のAPIやデータベースから予期せぬデータが飛んできて、中身の構造がスカスカだったとしても、as を使っているとTypeScriptはスルーしてしまう。

接着したフタを開けてみたら、実行時（ランタイム）に実体のないプロパティを参照した瞬間にエラーを吐き出して、稼働中のWebサーバー自体がその場で即死（クラッシュ）するわ。

 

Webサーバーが即死するということは、他のお客さん全員の通信も一瞬で遮断されるということ。

だから、バックエンドにおけるTypeScriptは、『コンパイルを通すための道具』ではなく、『動いているサーバーの命を守るための盾』。

データの構造が不確定な場合は as で誤魔化すんじゃなくて、後々教える『Zod』のようなバリデーションライブラリを使って、実行時にも泥臭くデータチェックを行うのがバックエンド開発の鉄則なのよ。

本日のまとめ

• Node.jsのTS実行： 本体はTSを直接実行できない。開発環境では、内部でメモリコンパイルを行う tsx ツールを導入して爆速で開発する。
• 拡張子とツールの違い： フロントの拡張子 .tsx と、Nodeの実行ツール tsx は名前が同じだけの別物。
• TS2591エラーの対策： tsc がNodeの型定義を見失う場合は、tsconfig.json の types に ["node"] を明示して強制読込させる。
• 本番環境の鉄則： 本番環境では tsx は使わない。事前に tsc で純粋なJavaScriptにビルドし、node コマンドで安全・軽量に動かす。
• バックエンドTSの覚悟： 型アサーション（as）でのエラー隠蔽はサーバー即死の引き金になる。型チェックは厳格に扱い、実行時エラーを徹底的に防ぐ！

次回：第7回「標準httpモジュールで自作する超シンプルWebサーバー（TS版）」に続く