ts-node の使い方 — Node.js で TypeScript を直接実行する

一言でいうと

ts-node は、TypeScript を事前コンパイルなしに Node.js 上で直接実行できるランタイム環境です。JIT（Just-In-Time）でトランスパイルを行い、ソースマップやREPLもサポートしています。

どんな時に使う？

• 開発中にTypeScriptスクリプトをサクッと実行したい — tsc でビルドしてから node で実行する手間を省きたい場合
• TypeScriptのREPLで対話的にコードを試したい — ちょっとした型の挙動確認やAPIの動作検証に
• テストランナーやCLIツールでTypeScriptを直接読み込ませたい — Mocha、Jest、その他のツールと組み合わせて使う場合

インストール

# npm
npm install -D typescript ts-node

# yarn
yarn add -D typescript ts-node

# pnpm
pnpm add -D typescript ts-node

# 必要に応じて追加
npm install -D tslib @types/node

注意: ts-node は typescript パッケージに依存しています。必ずセットでインストールしてください。

ts-node の基本的な使い方

最もシンプルな使い方は、コマンドラインから .ts ファイルを直接実行することです。

// hello.ts
const greet = (name: string): string => {
  return `Hello, ${name}!`;
};

console.log(greet("TypeScript"));

# 実行
npx ts-node hello.ts
# => Hello, TypeScript!

プログラムからの利用

既存の Node.js プロセスに ts-node を登録して、require() で .ts ファイルを読み込めるようにすることもできます。

// register.ts
// -r ts-node/register フラグと同等の処理をプログラムから行う
require('ts-node').register({
  transpileOnly: true,
  compilerOptions: {
    module: 'commonjs',
  },
});

// これ以降、require() で .ts ファイルを読み込める
const { add } = require('./math');
console.log(add(1, 2));

# -r フラグで登録する方法（よく使うパターン）
node -r ts-node/register src/index.ts

よく使うAPI・オプション

1. --transpileOnly / transpileOnly — 型チェックをスキップ

型チェックを省略して高速に実行します。開発中のスクリプト実行で最も頻繁に使うオプションです。

npx ts-node --transpileOnly script.ts

# ショートカットコマンドも用意されている
npx ts-node-transpile-only script.ts

tsconfig.json で設定する場合：

{
  "ts-node": {
    "transpileOnly": true
  },
  "compilerOptions": {
    "target": "ES2020",
    "module": "commonjs"
  }
}

2. --esm — ESM（ECMAScript Modules）モードで実行

Node.js のネイティブ ESM ローダーを使って TypeScript を実行します。

npx ts-node --esm script.ts

# ショートカット
npx ts-node-esm script.ts

// script.ts (ESMモード)
import { readFile } from 'node:fs/promises';

const content = await readFile('./package.json', 'utf-8');
console.log(JSON.parse(content).name);

注意: ESM モードでは package.json に "type": "module" を設定するか、tsconfig.json の module を "ESNext" / "NodeNext" にする必要があります。

3. --swc — SWC トランスパイラで高速実行

Rust 製の SWC を使うことで、トランスパイル速度を大幅に向上させます。

# SWCプラグインのインストールが必要
npm install -D @swc/core @swc/helpers

npx ts-node --swc script.ts

tsconfig.json で設定する場合：

{
  "ts-node": {
    "swc": true
  }
}

4. -e / --eval — ワンライナー実行

コマンドラインから直接 TypeScript コードを評価します。

# コードを実行
npx ts-node -e 'const x: number = 42; console.log(x * 2)'

# -p で結果を出力
npx ts-node -p -e '"Hello".toUpperCase()'
# => HELLO

5. --project — tsconfig.json のパスを指定

デフォルト以外の tsconfig.json を使いたい場合に指定します。

npx ts-node --project tsconfig.scripts.json seed.ts

// プログラムから利用する場合
import { register } from 'ts-node';

const service = register({
  project: './tsconfig.scripts.json',
  transpileOnly: true,
  compilerOptions: {
    strict: true,
  },
});

// 登録後は require で .ts を読み込める

tsconfig.json での推奨設定

ts-node 固有のオプションは tsconfig.json の "ts-node" キーにまとめて書くのが推奨されています。

{
  "ts-node": {
    "transpileOnly": true,
    "files": true,
    "compilerOptions": {
      "module": "commonjs"
    }
  },
  "compilerOptions": {
    "target": "ES2020",
    "module": "ESNext",
    "moduleResolution": "node",
    "strict": true,
    "esModuleInterop": true,
    "outDir": "./dist"
  }
}

類似パッケージとの比較

補足: 近年は tsx が「設定不要で高速」という点で人気を集めています。型チェックが不要で速度重視なら tsx、型チェックやREPL、細かい設定が必要なら ts-node という使い分けが一般的です。

注意点・Tips

1. paths / baseUrl はそのままでは解決されない

tsconfig.json の paths エイリアスは ts-node 単体では解決されません。tsconfig-paths を併用してください。

npm install -D tsconfig-paths
npx ts-node -r tsconfig-paths/register src/index.ts

2. transpileOnly を使わないと遅い

デフォルトでは型チェックが有効なため、大規模プロジェクトでは起動が遅くなります。開発時のスクリプト実行には transpileOnly: true または --swc を強く推奨します。

3. ESM 利用時のハマりポイント

ESM モードでは以下のエラーに遭遇しやすいです：

• ERR_REQUIRE_ESM — CommonJS モードで ESM パッケージを require しようとした場合。--esm フラグを付けるか、tsconfig.json の module 設定を見直してください。
• ERR_UNKNOWN_FILE_EXTENSION — Node.js の ESM ローダーが .ts 拡張子を認識できない場合。--esm フラグまたは ts-node-esm コマンドを使ってください。

4. 本番環境では使わない

ts-node はあくまで開発用ツールです。本番環境では tsc でコンパイルした JavaScript を node で実行してください。

# 本番用
tsc && node dist/index.js

5. Watch モードは外部ツールと組み合わせる

ts-node 自体にはファイル監視機能がありません。nodemon と組み合わせるのが定番です。

// nodemon.json
{
  "watch": ["src"],
  "ext": "ts",
  "exec": "ts-node --transpileOnly src/index.ts"
}

npx nodemon

まとめ

ts-node は、Node.js 上で TypeScript を直接実行するためのデファクトスタンダードなツールです。--transpileOnly や --swc オプションを活用すれば開発体験を大幅に改善できます。ただし、近年は tsx など軽量な代替ツールも台頭しているため、プロジェクトの要件に応じて使い分けるのがベストです。