マイグレーションガイド: v1.6.0

このガイドはv1.5.xからv1.6.0へのアップグレードを支援します。バージョン1.6.0では、公開されているすべてのパッケージで Node.js 22 以降が必須になります。アプリケーションロジックへの影響はありませんが、ローカル環境、CI、Lambda ランタイム、Docker イメージを Node.js 22 に移行する必要があります。

リリース日

2026-11-03

破壊的変更の概要

変更内容	影響	必要なアクション
Node.js 22 以降が必須	全パッケージの engines.node が >=22 に。Node.js 18 / 20 では npm install が EBADENGINE を報告	アプリ、Lambda 関数、Docker イメージを Node.js 22.23.4 以降で実行
nodemailer 10 (core)	nodemailer が独自の型を同梱し、デフォルトエクスポートが名前空間ではなくなった	nodemailer の型を名前付きでインポートし、@types/nodemailer を削除（nodemailer を直接使用している場合のみ）
CLI テンプレート（新規プロジェクトのみ）	新規プロジェクトは NODEJS_22_X、node:22-bookworm-slim、node:22-alpine、nodejs22.x を使用	既存プロジェクトは任意: 同じ箇所を手動で更新

なぜ Node.js 22 なのか

Node.js 18 と 20 はサポート終了（EOL）のため、Node.js に同梱されている Brotli デコーダーのリモートコード実行脆弱性 CVE-2026-111497（Node2Shell）の修正が提供されません。修正は Node.js 22.23.4、24.22.1、26.12.1 で提供されています。また @mbc-cqrs-serverless/core は nodemailer 10 に依存するようになり、nodemailer 10 自体も Node.js 20 以降を必要とします。フレームワークの CI は Node.js 22 と 24 でテストしています。

移行前チェックリスト

アップグレード前に以下を確認してください：

• ローカルに Node.js 22.23.4 以降がインストールされている
• CI ワークフローが Node.js 22 以降を使用している
• Lambda 関数とレイヤーが nodejs22.x ランタイムを使用している
• Docker イメージが Node.js 22 のイメージをベースにしている
• コードベースで nodemailer の型の直接使用と @types/nodemailer の有無を確認
• アップグレード後にフルテストスイートを実行

破壊的変更1: Node.js 22 以降が必須

変更内容

公開されているすべての @mbc-cqrs-serverless/* パッケージで engines.node が >=22 になりました。Node.js 18 または 20 では npm install が EBADENGINE 警告を報告し、engine-strict が有効な場合はインストールが失敗します。

npm warn EBADENGINE Unsupported engine {
npm warn EBADENGINE   package: '@mbc-cqrs-serverless/core@1.6.0',
npm warn EBADENGINE   required: { node: '>=22' },
npm warn EBADENGINE   current: { node: 'v20.x.x', npm: '10.x.x' }
npm warn EBADENGINE }

移行手順

Step 1: ローカル開発環境

Node.js 22.23.4 以降をインストールします。nvm を使用している場合：

nvm install 22
nvm use 22
node --version # Must be v22.23.4 or later (v22.23.4 以降であること)

プロジェクトに .nvmrc、.node-version、engines フィールドがある場合は、それらも更新します：

{
  "engines": {
    "node": ">=22"
  }
}

Step 2: CI

CI ワークフローの Node.js バージョンを更新します：

- name: Set up Node.js
  uses: actions/setup-node@v4
  with:
    node-version: '22.x'

Step 3: Lambda ランタイム

Lambda 関数とレイヤーのランタイムを更新します。

AWS CDK:

// Before (v1.5.x)
compatibleRuntimes: [cdk.aws_lambda.Runtime.NODEJS_20_X],
runtime: cdk.aws_lambda.Runtime.NODEJS_20_X,

// After (v1.6.0)
compatibleRuntimes: [cdk.aws_lambda.Runtime.NODEJS_22_X],
runtime: cdk.aws_lambda.Runtime.NODEJS_22_X,

Serverless Framework（infra-local/serverless.yml を含む serverless.yml）:

provider:
  name: aws
  runtime: nodejs22.x

serverless-offline を使ったローカル開発では、nodejs22.x ランタイムに対応した serverless-offline ^13.9.0 以降を使用してください。

npm install --save-dev serverless-offline@^13.9.0

CDK パイプライン（infra/libs/pipeline-stack.ts）:

スキャフォールドした CDK パイプラインでデプロイしている場合は、CodeBuild の Node.js バージョンを固定してください。固定しないと npm ci、テスト、synth、レイヤーのビルドが CodeBuild イメージ既定の Node.js（変更されることがあります）で実行されます:

const pipeline = new CodePipeline(this, idName + 'PipelineV3', {
  selfMutation: true,
  // Pin every CodeBuild project in the pipeline to Node.js 22 (パイプラインのすべての CodeBuild プロジェクトを Node.js 22 に固定)
  codeBuildDefaults: {
    partialBuildSpec: BuildSpec.fromObject({
      phases: { install: { 'runtime-versions': { nodejs: '22' } } },
    }),
  },
  // ...
})

Step 4: Docker イメージ

Docker イメージを Node.js 22 のベースイメージに移行します。アプリケーションイメージを node:22-bookworm-slim に切り替え、Prisma を使用している場合は、Prisma を実行するすべてのステージに openssl をインストールしてください。Prisma のクエリエンジンは libssl を必要としますが、bookworm-slim には含まれていません。

# Before (v1.5.x)
FROM node:20-bullseye-slim

# After (v1.6.0)
FROM node:22-bookworm-slim

# Prisma's query engine needs libssl, which bookworm-slim does not ship (Prisma のクエリエンジンは libssl が必要ですが、bookworm-slim には含まれていません)
RUN apt-get update -y && apt-get install -y --no-install-recommends openssl && rm -rf /var/lib/apt/lists/*

infra-local/ 配下のローカルエミュレーター用イメージ（例: cognito-local、appsync-simulator）は node:22-alpine に移行できます：

# Before
FROM node:18-alpine

# After
FROM node:22-alpine

破壊的変更2: nodemailer 10 の型

変更内容

@mbc-cqrs-serverless/core は nodemailer 10 に依存するようになりました。nodemailer 10 は独自の型定義を同梱し、デフォルトエクスポートは名前空間ではなくなったため、nodemailer.SendMailOptions のような型参照はコンパイルできなくなります。

備考

アプリケーションが @mbc-cqrs-serverless/core の EmailService のみを使用している場合、コード変更は不要です。

移行手順

Step 1: 使用箇所を確認

grep -rn -E "nodemailer\.(SendMailOptions|Transporter|SentMessageInfo)" --include="*.ts" src/ test/
grep -n "@types/nodemailer" package.json

検索結果が見つからない場合は、対応不要です。

Step 2: 型を名前付きでインポート

変更前:

// Before (v1.5.x, nodemailer 9 with @types/nodemailer)
import nodemailer from 'nodemailer';

const mailOptions: nodemailer.SendMailOptions = {
  from: 'noreply@example.com',
  to: 'user@example.com',
  subject: 'Hello',
};

変更後:

// After (v1.6.0, nodemailer 10)
import nodemailer, { SendMailOptions } from 'nodemailer';

const mailOptions: SendMailOptions = {
  from: 'noreply@example.com',
  to: 'user@example.com',
  subject: 'Hello',
};

Transporter と SentMessageInfo にも同じ変更を適用します。

Step 3: @types/nodemailer を削除

npm uninstall @types/nodemailer

CLI テンプレート（新規プロジェクトのみ）

v1.6.0 の mbc new で作成したプロジェクトは、最初から Node.js 22 を使用します。既存プロジェクトは変更されません。追従する場合は、以下の箇所を手動で更新してください：

ファイル	Before	After (v1.6.0)
infra/libs/infra-stack.ts	NODEJS_20_X	NODEJS_22_X
Dockerfile	node:20-bullseye-slim	node:22-bookworm-slim + openssl
infra-local/cognito-local/Dockerfile, infra-local/appsync-simulator/Dockerfile	node:18-alpine	node:22-alpine
infra-local/serverless.yml	nodejs18.x	nodejs22.x
package.json (serverless-offline)	^13.3.2	^13.9.0
infra/libs/pipeline-stack.ts	CodeBuild イメージの既定	runtime-versions nodejs: 22
package.json, infra/package.json (@types/node)	^20	^22.20.5

テンプレートの依存関係 overrides で proxy-addr 2.0.8、body-parser 1.20.9 / 2.4.0、multer 2.5.0 も固定し、qs を ^6.16.1（修正版の body-parser が要求する最小版）に引き上げました。既存プロジェクトにも同じ overrides を追加すると、これらの脆弱性を解消できます。

アップグレード手順

Step 1: Node.js 22 に切り替え

ローカル開発環境、CI、Lambda、Docker について 破壊的変更1 の手順に従ってください。

Step 2: 依存関係を更新

npm install \
  @mbc-cqrs-serverless/core@^1.6.0 \
  @mbc-cqrs-serverless/tenant@^1.6.0 \
  @mbc-cqrs-serverless/master@^1.6.0 \
  @mbc-cqrs-serverless/sequence@^1.6.0 \
  @mbc-cqrs-serverless/task@^1.6.0 \
  @mbc-cqrs-serverless/cli@^1.6.0

Step 3: コード修正を適用

1. nodemailer の型を使用している場合は名前付きでインポートし、@types/nodemailer を削除（破壊的変更2 を参照）

Step 4: テストとデプロイ

npm run test:cov

デプロイ後、AWS Lambda コンソールで関数が nodejs22.x ランタイムで動作していることを確認してください。

v1.6.0 のセキュリティ修正

• 本番依存関係の High / Critical 脆弱性を解消: proxy-addr 2.0.8、body-parser 1.20.9 / 2.4.0、multer 2.5.0、nodemailer 10.3.1、@modelcontextprotocol/sdk 1.32.2、zod 4.6.7

サポート

移行中に問題が発生した場合：

• GitHub Issues
• ドキュメント

関連ドキュメント

• 変更履歴 v1.6.0 - v1.6.0 リリースノート
• インストール - システム要件
• メールサービス - EmailService によるメール送信
• デプロイガイド - AWS へのデプロイ