diff --git a/.agents/skills/dep-upgrade/instructions.md b/.agents/skills/dep-upgrade/instructions.md index c73cb98a4..a98092efb 100644 --- a/.agents/skills/dep-upgrade/instructions.md +++ b/.agents/skills/dep-upgrade/instructions.md @@ -19,6 +19,7 @@ Fetch the official migration guide via WebFetch. For each breaking change, grep Key areas to check: - Runtime requirements (`engines.node` in `package.json`) +- Node.js runtime bumps: follow the file set of `ac78bee2`, and also update Vercel Dashboard > Project Settings > Build and Deployment > Node.js Version (not in the repo). - Config file format changes (flat config vs legacy, etc.) - Deprecated/removed APIs used in `src/` - Directive comments that become errors in the new version (e.g., `/* eslint-env */` in ESLint v10) diff --git a/docs/dev-notes/2026-01-27/bump-nodejs-from-v22-to-v24/plan.md b/docs/dev-notes/2026-01-27/bump-nodejs-from-v22-to-v24/plan.md deleted file mode 100644 index 529fba11a..000000000 --- a/docs/dev-notes/2026-01-27/bump-nodejs-from-v22-to-v24/plan.md +++ /dev/null @@ -1,375 +0,0 @@ -# Node.js v22 → v24 アップグレード計画 - -**作成日**: 2026-01-27 - -**対象バージョン**: - -- Node.js: v22.x → v24.x (LTS) -- pnpm: v10.28.2（互換性あり） - -**ステータス**: ✅ 完了 - ---- - -## 目次 - -1. [背景](#背景) -2. [破壊的変更と影響](#破壊的変更と影響) -3. [新機能](#新機能) -4. [実装戦略](#実装戦略) -5. [設定変更](#設定変更) -6. [pnpm v10対応](#pnpm-v10対応) -7. [検証チェックリスト](#検証チェックリスト) -8. [参考資料](#参考資料) - ---- - -## 背景 - -Node.js 24 LTS は 2024年度後半にリリースされ、2028年4月まで長期サポートが提供されます。現在のプロジェクトは v22 LTS を使用していますが、v24 への段階的なアップグレードを計画します。 - -**アップグレードの目的**: - -- 最新の Node.js 機能を活用 -- セキュリティアップデート（OpenSSL 3.5）の適用 -- ネイティブアドオン互換性の確保（V8 13.6） -- 将来の依存関係アップデートに対応 - ---- - -## 破壊的変更と影響 - -### 1. OpenSSL 3.5 セキュリティレベル 2 - -| 項目 | 内容 | -| -------------------- | ------------------------------------------------------ | -| **変更** | RSA/DSA/DH キー < 2048 bits 禁止、RC4 暗号スイート禁止 | -| **プロジェクト影響** | ✅ **無 (no impact)** | -| **理由** | レガシーな短いキーを使用する箇所なし | - -### 2. `url.parse()` ランタイム deprecation - -| 項目 | 内容 | -| -------------------- | ---------------------------------------------------------- | -| **変更** | `url.parse()` が非推奨に | -| **プロジェクト影響** | ✅ **無 (no impact)** | -| **理由** | `url.parse()` 使用箇所なし、`URL` 標準オブジェクトを使用中 | - -### 3. `fetch()` より厳密なコンプライアンス - -| 項目 | 内容 | -| -------------------- | ------------------------------------------------------------- | -| **変更** | HTTP リクエスト検証がより厳格化 | -| **プロジェクト影響** | ⚠️ **要確認 (needs verification)** | -| **対象** | AtCoder API、AOJ API、外部 API 通信 | -| **ファイル** | `src/lib/clients/atcoder_problems.ts`, `aizu_online_judge.ts` | -| **対応** | ビルド・テスト実行で検証 | - -### 4. C/C++ ネイティブアドオン - V8 13.6 要件 - -| 項目 | 内容 | -| -------------------- | --------------------------------------------------------------------- | -| **変更** | V8 13.6 ネイティブアドオン API 更新 | -| **対象パッケージ** | `esbuild`, `lightningcss`, `@rolldown/binding`, `jsdom`, `playwright` | -| **プロジェクト影響** | ⚠️ **要確認 (needs verification)** | -| **対応** | ビルド・テスト実行で検証 | - -### その他の deprecations（自動対応） - -- ✅ `dirent.path` → `dirent.parentPath` (fs使用なし) -- ✅ `fs.truncate()` with fd (使用なし) -- ✅ `process.assert()` (使用なし) - ---- - -## 新機能 - -Node.js 24 LTS の便利な機能（将来的な活用機会）: - -| 機能 | 説明 | 優先度 | -| ----------------------------------------------------- | ---------------------------- | ------ | -| **`URLPattern` グローバル可用性** | URL パターンマッチング標準化 | 低 | -| **`--permission` フラグ簡素化** | プロセス権限管理の改善 | 低 | -| **Test Runner 改善** | テスト実行時の自動待機 | 低 | -| **`Error.isError()`** | エラー判定の標準化 | 低 | -| **`RegExp.escape()`** | 正規表現エスケープ | 低 | -| **Explicit Resource Management (`using` キーワード)** | リソース自動解放 | 低 | - -→ 現在のアップグレードでは必須ではなく、将来の機能強化時に検討 - ---- - -## 実装戦略 - -### Phase 1: 設定更新 - -開発環境・CI・ドキュメントの Node.js バージョンを v24 に統一 - -### Phase 2: ビルド・テスト検証 - -```bash -pnpm install -pnpm build -pnpm test:unit -pnpm test:integration -pnpm exec prisma generate -``` - -### Phase 3: エラー検査と対応 - -ネイティブアドオンビルドエラーが発生した場合、`pnpm-workspace.yaml` の `onlyBuiltDependencies` に追加 - -### Phase 4: ドキュメント確定 - -検証結果を本計画に記録して完了 - ---- - -## 設定変更 - -### 1. Dockerfile - -```dockerfile -ARG NODE_VERSION=24 # 22 → 24 -``` - -**影響範囲**: DevContainer 開発環境 - -### 2. GitHub Actions CI Workflow (`.github/workflows/ci.yml`) - -```yaml -# build job - matrix strategy -node-version: [24] # [22, 24] → [24] - -# preview job -node-version: 24 # 22 → 24 - -# production job -node-version: 24 # 22 → 24 -``` - -**影響範囲**: CI/CD パイプライン - -### 3. CONTRIBUTING.md - -```markdown -- Node.js v24.x # v22.x → v24.x -``` - -**影響範囲**: 開発ガイドライン - -### 4. package.json - engines フィールド - -```json -"engines": { - "node": "24.x" # >=20.0.0 → 24.x（固定） -} -``` - -**影響範囲**: Node.js バージョン要件 - -### 5. Vercel 設定 - -**構成**: Vercel Dashboard > Project Settings > Build and Deployment > Node.js Version を `24` に設定 - -**注**: `svelte.config.js` の `runtime` オプションは deprecated のため削除 - -**状態**: ✅ Vercel v24 対応確認済み（Dashboard 設定） -**影響範囲**: 本番環境デプロイ - ---- - -## pnpm v10 対応 - -### onlyBuiltDependencies の現状 - -プロジェクトの `pnpm-workspace.yaml` には既に以下が設定済み： - -```yaml -onlyBuiltDependencies: - - '@prisma/client' - - '@prisma/engines' - - esbuild - - lefthook - - prisma - - puppeteer -``` - -### Node.js 24 ビルド時の監視対象 - -以下のパッケージについて、ビルド時エラーの有無を確認： - -| パッケージ | タイプ | 現状 | 対応 | -| ------------------- | ------------------------------------ | ----------- | -------------- | -| `@prisma/client` | ネイティブアドオン | ✅ 設定済み | - | -| `esbuild` | ネイティブアドオン | ✅ 設定済み | - | -| `lightningcss` | ネイティブアドオン | ❌ 未設定 | エラー時に追加 | -| `@rolldown/binding` | ネイティブアドオン (Tailwind CSS v4) | ❌ 未設定 | エラー時に追加 | -| `playwright` | postinstall script | ❌ 未設定 | エラー時に追加 | -| `jsdom` | ネイティブアドオン (テスト環境) | ❌ 未設定 | エラー時に追加 | - -**対応方針**: ビルド・テスト実行時にエラーが発生したパッケージのみ `onlyBuiltDependencies` に追加 - ---- - -## 検証チェックリスト - -### ローカル検証 - -- [ ] **Node.js 24 インストール**: nvm / fnm / 直接インストール -- [ ] **依存関係インストール**: `pnpm install` 成功 -- [ ] **プロダクションビルド**: `pnpm build` 成功 -- [ ] **ユニットテスト**: `pnpm test:unit` 合格 -- [ ] **統合テスト**: `pnpm test:integration` 成功 -- [ ] **Prisma 生成**: `pnpm exec prisma generate` 成功 - -### ネイティブアドオン検証 - -- [ ] **esbuild**: ビルドでエラーなし -- [ ] **lightningcss**: ビルドでエラーなし -- [ ] **@rolldown/binding**: ビルドでエラーなし -- [ ] **jsdom**: ユニットテストでエラーなし -- [ ] **playwright**: 統合テストでエラーなし - -### API 通信検証 - -- [ ] **AtCoder API**: テスト通信成功 -- [ ] **AOJ API**: テスト通信成功 -- [ ] **外部 API**: 通信エラーなし - -### 最終確認 - -- [ ] `onlyBuiltDependencies` への追加が必要か判定 -- [ ] すべてのテストが緑 ✅ -- [ ] 本計画ドキュメントに検証結果を記録 - ---- - -## 実装進捗 - -### Phase 1: 設定更新 - -**ステータス**: ✅ 完了 - -- ✅ Dockerfile: `NODE_VERSION=22` → `NODE_VERSION=24` -- ✅ CONTRIBUTING.md: Node.js v22.x → v24.x -- ✅ `.github/workflows/ci.yml`: build, preview, production jobs で v24 に統一 -- ✅ package.json engines: `>=20.0.0` → `24.x` - -### Phase 2: ビルド・テスト検証 - -**ステータス**: ✅ 完了 - -**検証結果**: - -- ✅ `pnpm install`: 成功 (Prisma postinstall スクリプト実行) -- ✅ `pnpm build`: 成功 (Svelte v5 互換性警告のみ、機能的問題なし) -- ✅ `pnpm test:unit`: 1787 tests passed -- ✅ `pnpm exec playwright install`: 成功 (Node v24 で正常にブラウザをダウンロード) -- ✅ `pnpm exec playwright install-deps`: 成功 (システム依存関係インストール) - -**ネイティブアドオン検証**: - -- ✅ `esbuild`: ビルド成功、エラーなし -- ✅ `@prisma/client`: ビルド成功、エラーなし -- ✅ `jsdom`: ユニットテスト成功、エラーなし -- ✅ その他のパッケージ: すべてビルド成功 - -### Phase 3: エラー検査と対応 - -**ステータス**: ✅ 完了 - -`onlyBuiltDependencies` 追加結果： - -- **追加不要**: Node v24 との互換性に問題なし -- 既存設定（`@prisma/client`, `esbuild`, `lefthook`, `prisma`, `puppeteer`）で十分 - -### Phase 4: ドキュメント確定 - -**ステータス**: ✅ 完了 - -**最終ステータス**: ✅ アップグレード完了・検証済み - ---- - -## 教訓・学び - -### 成功のポイント - -1. **段階的な検証方法** ✅ - - 設定→ビルド→テスト→デプロイ の順序は効果的 - - 各ステップで即座にエラーを検出可能 - -2. **ネイティブアドオンの互換性** ✅ - - Node v22 → v24 へのアップデートには V8 13.6 対応が必須 - - `esbuild`, `@prisma/client` など主要パッケージは既に対応済み - -3. **pnpm + Playwright 連携** ✅ - - Playwright ブラウザのダウンロードが Node v24 で正常に動作 - - システム依存関係の明確なエラーメッセージが支援 - -4. **チェックリスト駆動アップグレード** ✅ ⭐ **重要** - - plan.md の設定変更セクションは網羅的な計画表として有効 - - 複数ファイルの更新は必ず一度すべて洗い出す必要がある - - CI/CD 設定は見落としやすいため特に注意 - -5. **SvelteKit Vercel Adapter API 設定確認** ✅ ⭐ **重要** - - `@sveltejs/adapter-vercel` v6.3.1 の `runtime` オプションは deprecated - - `nodejs24.x` は無効な値（v6.3.1 では `nodejs20.x`, `nodejs22.x` のみ有効） - - **正しい方法**: `package.json` の `engines.node` と Vercel Dashboard で Node.js バージョンを指定 - - **修正内容**: - - `package.json`: `"engines": { "node": "24.x" }` で v24 を明示的に固定 - - `svelte.config.js`: `runtime` オプションを完全削除 - - Vercel Dashboard: Project Settings > Node.js Version = 24 で設定 - - **推奨事項**: SvelteKit/フレームワーク整合性確認は公式 API ドキュメント最優先 - -### 遭遇した問題と対応 - -1. **CI/CD 設定の見落とし** - - 最初の実装では GitHub Actions CI Workflow を未更新 - - **対応**: plan.md の設定変更セクションを完全にカバーする必要性を認識 - - **今後**: チェックリスト式で各ファイルを確認してから実装 - -2. **Playwright ブラウザ不在** - - 最初のテスト実行時に検出 - - `pnpm exec playwright install` で解決 - - システム依存関係も同時にインストール - -3. **SvelteKit Adapter Vercel v6.3.1 の非対応値** - - `runtime: 'nodejs24.x'` 指定後にテスト実行を試みたが未検証 - - **実査**: `@sveltejs/adapter-vercel` v6.3.1 では `nodejs24.x` が無効値 - - **問題**: Deprecated オプションを使用 + 無効値を指定 - - **根本原因**: 公式 API ドキュメント（NPM ページ）未読 - - **対応**: オプション削除 + package.json engines で v24 固定 + Dashboard 設定に委譲 - - **学習**: フレームワーク設定は必ず公式 README/API ドキュメント確認必須 - -4. **Svelte v5 互換性警告** - - Runes mode の状態参照に関する警告 - - **機能的問題なし** → 無視して問題なし - - 次の Svelte バージョンで修正予定 - -### 推奨アクション（今後） - -- ✅ 本番環境へデプロイ: Vercel v24 対応確認済み（Dashboard 設定済み） -- 📋 Svelte コンポーネント: `$derived` 等への段階的移行検討 -- 📋 pnpm v11 移行: `onlyBuiltDependencies` → `allowBuilds` の検討 -- 📋 SvelteKit/Adapter: v7 リリース時に deprecated オプション削除の正式廃止確認 - ---- - -## 参考資料 - -- [Node.js v22 to v24 Migration Guide](https://nodejs.org/en/blog/migrations/v22-to-v24) -- [Node.js 24 LTS Release Notes](https://nodejs.org/blog/release/v24.13.0) -- [Vercel Node.js Runtime Support](https://vercel.com/docs/functions/serverless-functions/node-js-runtime) -- [pnpm v10 Breaking Changes](https://github.com/pnpm/pnpm/releases/tag/v10.0.0) -- [OpenSSL 3.5 Security Changes](https://github.com/openssl/openssl/releases/tag/openssl-3.5.0) - ---- - -## 補足 - -### 将来の検討事項 - -- **pnpm v11 移行**: `allowBuilds` への設定移行検討（後日） -- **Node.js v26 トライアル**: 実験的対応（v24 安定化後）