Node.26 対応(26/11予定) / npm 12 への移行

[KentaHizume]

結論

Node.26 が 2026/11 頃に Active LTS になるので、その際に対応する

Problem Statement

npm 12 は、依存パッケージのインストールスクリプトを既定で遮断し、Git 由来および URL 由来の依存の解決を既定で禁止します。
これは 2025 年から続いたサプライチェーン攻撃で悪用された経路を閉じる変更であり、開発標準として取り込む価値があります。

しかし現時点では採用を見送りました。理由は npm 12 がどの Node.js リリースにも同梱されていないことです。

調査時点の状況は次のとおりでした。

Node.js	同梱される npm
v24.19.0（最新 LTS）	11.17.0
v24.15.0	11.12.1
v26.0.0	11.12.1
v22.22.2	10.9.7

npm 12 を採用すると、次の負担が恒久的に発生します。

• Node.js のインストール後にグローバルで npm を更新する手順を、すべての開発者に課す必要がある
• CI ワークフローでも Node.js のセットアップ後に npm を更新するステップが必要になる
• engines に npm 12 を指定すると、Node.js インストーラーの既定状態の開発者にバージョン警告が出る

一方で、npm 11.16 以降は npm 12 で導入される制限を警告として先行提供しているため、移行の準備は npm 11 系のままでも進められます。

Solution

Node.js が npm 12 を同梱するようになった時点で、開発標準を npm 12 系に移行します。

移行時に必要な作業を洗い出し、着手可能になったかを定期的に確認します。

User Stories

1. 開発者として、依存パッケージのインストールスクリプトが既定で遮断される状態で開発したい。そうすればサプライチェーン攻撃の主要な経路を閉じられる。
2. 開発者として、Node.js をインストールするだけで開発標準が要求する npm のバージョンが揃ってほしい。そうすれば追加の更新手順を覚える必要がない。
3. 開発者として、npm install の際に許可していないインストールスクリプトの一覧を確認したい。そうすれば承認すべきものを判断できる。
4. 開発者として、承認したインストールスクリプトが構成管理の対象として記録されてほしい。そうすればチーム内で同じ判断を共有できる。
5. ガイドの読者として、npm 12 で npm init の出力が変わることを知りたい。そうすれば生成された内容が正しいか判断できる。
6. ガイドの読者として、E2E テスト用のブラウザーバイナリが取得される仕組みを知りたい。そうすればインストールスクリプトが遮断されても対処できる。
7. ガイドの保守担当者として、Node.js が npm 12 を同梱したかを定期的に確認したい。そうすれば移行の機会を逃さない。
8. サンプルアプリケーションの保守担当者として、CI が npm 12 で動作することを確認したい。そうすれば開発者の手元との差異が生じない。

Implementation Decisions

着手の判断基準

Node.js の LTS 版が npm 12 を同梱した時点で着手します。
Node.js のリリース情報を定期的に確認します。

同梱を待たずに前倒しで移行する場合は、グローバル更新手順と CI ステップの追加という恒久的な負担を受け入れる判断が別途必要です。

移行時に対応が必要な箇所

先行する調査で判明している変更点です。

• npm init の既定ライセンスが変更され、生成される package.json から author と license の行が出力されなくなる。プロジェクト作成手順の出力例を更新する必要がある
• 依存パッケージのインストールスクリプトが既定で遮断される。インストールスクリプトの警告に関する説明を、警告から遮断への変更に合わせて書き換える必要がある
• 警告のラベルと案内されるコマンドが変わる。npm 11 系では npm approve-scripts 系のコマンドが案内されるが、npm 12 では npm install-scripts 系のコマンドが案内される
• Git 由来および URL 由来の依存の解決が既定で禁止される
• 未知のオプション、省略形のオプション、単一ハイフンの複数文字省略形がエラーになる
• ルートプロジェクトの preinstall が依存パッケージのインストール前に実行されるようになる
• npm shrinkwrap が削除される
• engines の npm のバージョン指定を更新する必要がある

先行する調査で影響がないことを確認済みの項目です。

• プロジェクト初期化コマンドに指定しているオプションは npm 12 でも従来どおり動作する
• ワークスペースを指定する短縮オプションは正規の短縮形であるため影響を受けない
• E2E テスト用のブラウザーバイナリは、create-vue が生成する prepare スクリプトによって取得される。ワークスペース構成でルートプロジェクトから npm install を実行した場合も prepare は実行されるため、インストールスクリプトを承認する必要はない

対応範囲

移行時には、ガイド本体だけでなく次の範囲も対象になります。

• ローカル開発環境の構築ガイド（npm のバージョン確認手順）
• サンプル実装の engines
• CI ワークフロー（npm のバージョンに依存する挙動の確認）

Testing Decisions

シーム

既存のシームを使います。新しいシームは設けません。

• ドキュメントの Lint ワークフロー（markdownlint / yamllint / textlint）
• ドキュメントのビルドワークフロー（MkDocs）
• サンプル実装の CI ワークフロー

自動化されていない検証

npm 12 の環境でプロジェクトを作成し、インストール・リンター・フォーマット・型検査・ビルド・単体テスト・E2E テストがすべて成功することを実測で確認します。

特にインストールスクリプトが遮断された状態で E2E テスト用のブラウザーバイナリが取得されるかは、ローカルと CI の両方で確認します。
先行する調査ではローカルのキャッシュが存在する状態でしか確認できていないため、キャッシュのない環境での検証が必要です。

Out of Scope

• create-vue のバージョン追随
• Node.js が npm 12 を同梱する前の前倒し移行（実施する場合は判断を改めて行う）

Further Notes

移行を待つ間も、npm 11.16 以降では npm 12 で導入される制限が警告として出力されます。
この警告に対する説明は先行する対応でガイドに追加済みであるため、読者が警告の意味を理解できない状態にはなっていません。

着手時期が外部要因に依存するため、この Issue は定期的な確認が必要な状態で保持します。

---

先行する対応: #5409