Node.jsチートシート - CLI・モジュール・標準APIリファレンス

概要

Node.js は V8 JavaScript エンジン上で動作するサーバーサイド JavaScript ランタイムです。非同期 I/O、イベントループ、豊富な組み込みモジュールを提供し、Web サーバー、CLI ツール、ビルドツール、スクリプト自動化など幅広い用途で使われています。本チートシートでは、現行 LTS（v20 / v22）で利用できる主要な API・CLI オプションを整理します。

ECMAScript Modules（ESM, import/export）と CommonJS（require/module.exports）の両方をサポートしますが、新規プロジェクトでは ESM が推奨です。package.json の "type": "module" で切り替えるのが基本的な方法です。

CLI コマンド

実行系

実行モード関連オプション

モジュールシステム

ESM（推奨）

// package.json: { "type": "module" }
import fs from 'node:fs/promises';
import { fileURLToPath } from 'node:url';
import path from 'node:path';

const __filename = fileURLToPath(import.meta.url);
const __dirname = path.dirname(__filename);

export function greet(name) {
  return `Hello, ${name}`;
}
export default greet;

CommonJS

const fs = require('node:fs');
const path = require('node:path');

function greet(name) {
  return `Hello, ${name}`;
}

module.exports = greet;
module.exports.greet = greet;

動的インポート

組み込みモジュール接頭辞

公式ドキュメントは node: プレフィックス付き表記を推奨します。これにより npm パッケージとの混同を避けられます。

組み込みモジュール

fs / fs/promises

path

process

http / https

import http from 'node:http';

const server = http.createServer((req, res) => {
  res.writeHead(200, { 'Content-Type': 'application/json' });
  res.end(JSON.stringify({ message: 'ok' }));
});

server.listen(3000, () => {
  console.log('Listening on http://localhost:3000');
});

url

crypto

events

stream

import { pipeline } from 'node:stream/promises';
import { createReadStream, createWriteStream } from 'node:fs';
import { createGzip } from 'node:zlib';

await pipeline(
  createReadStream('input.txt'),
  createGzip(),
  createWriteStream('input.txt.gz'),
);

child_process

import { spawn, execFile } from 'node:child_process';

const ls = spawn('ls', ['-la']);
ls.stdout.on('data', (data) => console.log(data.toString()));

execFile('node', ['--version'], (err, stdout) => {
  if (err) throw err;
  console.log(stdout);
});

worker_threads

import { Worker, isMainThread, parentPort } from 'node:worker_threads';

if (isMainThread) {
  const worker = new Worker(new URL(import.meta.url));
  worker.on('message', (m) => console.log('from worker:', m));
} else {
  parentPort.postMessage('hello');
}

実用例

1. JSON ファイルを安全に読み書き

import fs from 'node:fs/promises';

async function readJson(path) {
  const text = await fs.readFile(path, 'utf8');
  return JSON.parse(text);
}

async function writeJson(path, data) {
  await fs.writeFile(path, JSON.stringify(data, null, 2) + '\n');
}

2. ディレクトリを再帰的に走査

import fs from 'node:fs/promises';
import path from 'node:path';

async function* walk(dir) {
  for (const entry of await fs.readdir(dir, { withFileTypes: true })) {
    const full = path.join(dir, entry.name);
    if (entry.isDirectory()) yield* walk(full);
    else yield full;
  }
}

for await (const file of walk('./src')) {
  console.log(file);
}

3. 標準入力から1行ずつ読む

import readline from 'node:readline';

const rl = readline.createInterface({ input: process.stdin });
for await (const line of rl) {
  console.log('got:', line);
}

4. 環境変数のロード（v20.6+）

5. fetch（v18+ で組み込み）

6. AbortController でタイムアウト

const ac = new AbortController();
const timer = setTimeout(() => ac.abort(), 3000);
try {
  const res = await fetch(url, { signal: ac.signal });
  // ...
} finally {
  clearTimeout(timer);
}

7. シンプルな HTTP サーバー

import http from 'node:http';

http.createServer(async (req, res) => {
  if (req.method === 'GET' && req.url === '/health') {
    res.writeHead(200).end('OK');
    return;
  }
  res.writeHead(404).end('Not Found');
}).listen(8080);

8. CLI 引数のパース（標準 util.parseArgs）

import { parseArgs } from 'node:util';

const { values, positionals } = parseArgs({
  options: {
    name: { type: 'string', short: 'n' },
    verbose: { type: 'boolean', short: 'v' },
  },
  allowPositionals: true,
});
console.log(values, positionals);

9. 組み込みテストランナー

// test/sum.test.js
import { test } from 'node:test';
import assert from 'node:assert/strict';

test('1 + 2 = 3', () => {
  assert.equal(1 + 2, 3);
});

node --test

10. 終了時のクリーンアップ

11. ストリームでの巨大ファイル処理

import { createReadStream } from 'node:fs';
import { createInterface } from 'node:readline';

const rl = createInterface({ input: createReadStream('huge.log') });
let count = 0;
for await (const line of rl) {
  if (line.includes('ERROR')) count++;
}
console.log('errors:', count);

12. 非同期処理の並列制御

13. パフォーマンス計測

14. EventEmitter で once を Promise 化

15. ファイルから JSON Lines を読む

import { createReadStream } from 'node:fs';
import { createInterface } from 'node:readline';

const rl = createInterface({ input: createReadStream('events.jsonl') });
for await (const line of rl) {
  if (!line.trim()) continue;
  const event = JSON.parse(line);
  console.log(event.type);
}

npm スクリプト連携

{
  "type": "module",
  "scripts": {
    "start": "node src/index.js",
    "dev": "node --watch --env-file=.env src/index.js",
    "test": "node --test",
    "lint": "eslint .",
    "build": "node scripts/build.js"
  }
}

よく使うオプション早見表

トラブルシューティング

Tips & ベストプラクティス

• 新規プロジェクトは ESM ("type": "module") を選択し、node: プレフィックスで標準モジュールを import する。
• fs.promises を使い、コールバック API より async/await を優先する。
• LTS バージョンを使う。nvm や volta、fnm でバージョン管理する。
• 環境変数は --env-file=.env を活用し、dotenv への依存を減らす。
• HTTP クライアントは標準 fetch で十分なケースが多い。タイムアウトは AbortSignal.timeout(ms) で簡潔に書ける。
• テストは node --test で外部依存なしに開始できる。
• パフォーマンスが必要な箇所は worker_threads を検討する。CPU バウンド処理を別スレッドへ。
• process.exit() を多用しない。書き込み中ストリームを切るとデータ欠落が起こる。
• 例外は process.on('uncaughtException') ではなく、各境界で try/catch して構造化ログに残す。
• 依存ツリーは npm ls や npm audit で定期的に確認する。

参考リソース

• Node.js 公式 API ドキュメント
• Node.js CLI オプション一覧
• Node.js ESM ドキュメント
• Node.js Test Runner
• MDN: JavaScript リファレンス