node-best-practices

使用するタイミング

Node.js のコードを扱う際は、堅牢で高パフォーマンス、かつ保守しやすい Node.js アプリケーションを構築するために、ドメイン固有の知識を得る目的でこのスキルを使用してください。

型の消去を使った TypeScript

Node.js 用に TypeScript を記述する際は、ts-node や tsx などのビルドツールではなく、型の消去（Node.js 22.6 以降）を使用してください。型の消去では、トランスパイルせずに実行時に型注釈を取り除くことで、TypeScript を直接実行できます。

型の消去との互換性に関する主な要件：

• 型のみのインポートには import type を使用する
• enum の代わりに const オブジェクトを使用する
• 名前空間とパラメータープロパティは避ける
• インポートでは .ts 拡張子を使用する

最小限の例 — 型の消去が有効な TypeScript ファイル：

// greet.ts
import type { IncomingMessage } from 'node:http';

const greet = (name: string): string => `Hello, ${name}!`;
console.log(greet('world'));

次のコマンドで直接実行できます：

node greet.ts

設定と例の詳細については、rules/typescript.md を参照してください。

一般的なワークフロー

複数の手順があるプロセスでは、該当するルールファイルを確認する前に、次の大まかな手順に従ってください。

グレースフルシャットダウン：シグナルハンドラーを登録する（SIGTERM/SIGINT）→ 新しい処理の受け付けを停止する → 処理中のリクエストを完了させる → 外部接続（DB、キャッシュ）を閉じる → 適切なコードで終了する。rules/graceful-shutdown.md を参照してください。

エラー処理：共通のエラーベースクラスを定義する → エラーを分類する（運用上のエラーとプログラマーエラー）→ 非同期境界のハンドラー（process.on('unhandledRejection')）を追加する → 呼び出しスタックを通じて型付きエラーを伝播する → 応答またはクラッシュの前に、コンテキストを含めてログに記録する。rules/error-handling.md を参照してください。

不安定なテストの診断：--test-only でテストを分離する → 共有状態やタイマーへの依存を確認する → 非同期のティアダウン順序を調べる → 一時的な診断手順として再試行ロジックを追加する → 根本原因を修正する。rules/flaky-tests.md を参照してください。

処理が遅い箇所のプロファイリング：現実的な負荷の下で再現する → --cpu-prof で CPU プロファイルを取得する → ホット関数を特定する → ストリームのバックプレッシャーや不要なシリアライズがないか確認する → ベンチマークで改善を検証する。rules/profiling.md と rules/performance.md を参照してください。

使い方

詳しい説明とコード例については、各ルールファイルを読んでください。

• rules/error-handling.md - Node.js のエラー処理パターン
• rules/async-patterns.md - Async/await と Promise のパターン
• rules/streams.md - Node.js ストリームの使用方法
• rules/modules.md - ES Modules と CommonJS のパターン
• rules/testing.md - Node.js アプリケーションのテスト戦略
• rules/flaky-tests.md - node:test を使った不安定なテストの特定と診断
• rules/node-modules-exploration.md - node_modules ディレクトリの調査と分析
• rules/performance.md - パフォーマンス最適化の手法
• rules/caching.md - キャッシュのパターンとライブラリ
• rules/profiling.md - プロファイリングとベンチマークのツール
• rules/logging.md - ロギングとデバッグのパターン
• rules/environment.md - 環境設定とシークレット管理
• rules/graceful-shutdown.md - グレースフルシャットダウンとシグナル処理
• rules/typescript.md - Node.js の TypeScript 設定と型の消去