Translated from Korean

NestJS 11 リリース：主要な変更点と実務上のアップグレードガイド

Node.jsエコシステムで広く利用されているバックエンドフレームワーク「NestJS」が、バージョン11になりました。今回のメジャーアップデートは、フレームワークの内部エンジンを最新のHTTPライブラリに適合させること、そしてコンテナ環境で繰り返されるボイラープレートコードを削減することに重点を置いています。

まず確認すべきはランタイムの最低要件です。NestJS 11からはNode.js 16および18のサポートが完全に終了し、Node.js 20以上が必須となりました。現在のLTSバージョン以上のランタイムを使用していない場合は、環境のチェックから始める必要があります。

Express 5のデフォルト採用とルートワイルドカードルールの変更

デフォルトのHTTPプラットフォームアダプターがExpress 5に切り替わりました。同時にFastify 5のサポートも公式化されています。この変更の影響を最も受けるのは、ルートパスにおけるワイルドカードの指定方法です。

Express 5ではパスのマッチングアルゴリズムが改善され、名前のない単独のワイルドカード（アスタリスク）構文が使用できなくなりました。これまですべてのパスをキャプチャするために使用していたワイルドカードルートは、名前を指定する形式に変更する必要があります。

コントローラーで下位パス全体を処理していた @Get('users/\*') 形式は @Get('users/\*splat') のような名前付きパラメーター形式に修正する必要があります。ミドルウェアの設定でよく記述していた forRoutes('\*') も同様に forRoutes('\{\*splat\}') のような明示的なワイルドカード構文に更新しなければサーバーが正常に起動しません。既存コードを検証せずに依存関係だけを更新すると、起動時にルートマッチングエラーが発生する可能性があります。

標準ConsoleLoggerによるJSON構造化ロギングのサポート

DockerコンテナやKubernetes環境へサーバーをデプロイする際、最も煩わしかった作業の一つがJSONログ出力の設定でした。以前のバージョンまでは、DatadogやCloudWatchといったログ収集サービスに適合させるために、外部のロギングライブラリをラップしたり、複雑なカスタムロガーを実装したりする必要がありました。

NestJS 11では、デフォルトのロガーであるConsoleLoggerにネイティブのJSON出力オプションが追加されました。複雑な外部依存関係を追加することなく、オプション一つでシリアライズされたログを生成できます。

NestJS 11における main.ts のブートストラップコードは以下のように記述します。

typescript

import { NestFactory } from '@nestjs/core';
import { ConsoleLogger } from '@nestjs/common';
import { AppModule } from './app.module';

async function bootstrap() {
  const app = await NestFactory.create(AppModule, {
    logger: new ConsoleLogger({
      json: true,
    }),
  });
  await app.listen(3000);
}
bootstrap();

このオプションを有効にすると、タイムスタンプ、ログレベル、コンテキスト、メッセージが標準的なJSON形式で標準出力に記録されます。ネストされたオブジェクトや配列、Map、Setなどの構造体も綺麗にフォーマットされるため、ログ分析パイプラインとの連携が容易になります。

動的モジュールローディング構造の改善による起動速度の短縮

大規模プロジェクトで多数の動的モジュールを宣言する際に発生していた起動の遅延問題も解決されました。以前のバージョンでは、フレームワークが動的モジュールのメタデータをすべて文字列としてシリアライズし、ハッシュ値を生成してモジュールの固有性を識別していました。この手法は、巨大な設定オブジェクトやファイルデータを注入する動的モジュールが増えるほど、CPU演算コストとメモリ消費を増大させていました。

NestJS 11では、メタデータのハッシングではなく、オブジェクトの参照を直接比較する方法でモジュール識別ロジックを簡素化しました。これにより、マイクロサービスやモノレポのように多数のモジュールを組み合わせて構成されるアプリケーションにおいて、コールドスタートやテストコンテキストの初期化速度が大幅に向上しました。

今すぐアップグレードすべきか

Node.js 20以上の環境でコンテナベースのサービスを運用しており、外部ロガーなしで標準化されたJSON出力が欲しいのであれば、今回のアップグレードには十分な価値があります。ルートパスでワイルドカードを多用していなければ、移行作業も比較的スムーズです。

ただし、Express 4のクエリ文字列パース動作に強く依存している場合や、レガシーなルーティングルールが複雑に絡み合っているプロジェクトでは、まずテストスイートを強化する必要があります。特にワイルドカードルートとミドルウェアのマッチングパスを全調査した上で、段階的に依存関係を更新していくことをお勧めします。

TrTrilon

Trilon Consulting - Announcing NestJS 11: What's New

Today I am excited to announce the official release of Nest 11: A progressive Node.js framework for building efficient and enterprise-grade, server-side applications.