依存関係を入れる前に、非対応のNode.jsを検出する

パッケージは宣言することができる "node": ">=20" そして、いくつかのコマンドを実行した後も開発者に曖昧な失敗を残すことになります。ランタイムバージョンを実行可能な契約として扱ってください：それを明記し、確認し、依存関係をインストールする前に修復手順で停止してください。

小さなチェック

依存関係なしのスクリプトを追加 scripts/check-node-version.mjs:

const requiredMajor = 20;
const actualMajor = Number.parseInt(process.versions.node.split(".")[0], 10);

if (!Number.isInteger(actualMajor) || actualMajor < requiredMajor) {
  console.error(
    `Node.js ${requiredMajor}+ is required; found ${process.versions.node}. ` +
    "Install an active LTS release, then rerun npm install."
  );
  process.exit(1);
}

console.log(`Node.js ${process.versions.node} satisfies the Node.js ${requiredMajor}+ requirement.`);

通常のインストール経路の前に実行する：

{
  "engines": { "node": ">=20" },
  "scripts": { "preinstall": "node scripts/check-node-version.mjs" }
}

この engines フィールドは、パッケージマネージャーやホスティングシステムが要件を検査できるようにします。このスクリプトは、エンジンの不一致について警告するだけのパッケージマネージャーを使用している人にも同じ要件を見えるようにします。

ドキュメントが同じ真実の情報源を使うようにする

クイックスタートではチェックが正確に何を強制するかを示すべきです：

### Prerequisite

- Node.js 20 or newer (`node --version`)

If the install stops at the runtime check, install an active Node.js LTS
release and run `npm install` again.

「最近のNode.jsバージョン」のようなフレーズはテストできず、製品が新しい基準を採用するとすぐにずれる。

ランタイムを変更せずに両方のブランチをテスト

回帰テストがサポートされているバージョンとサポートされていないバージョンの両方をカバーできるように、比較を純粋関数に抽出してください:

export function supportsNode(version, requiredMajor = 20) {
  const major = Number.parseInt(version.split(".")[0], 10);
  return Number.isInteger(major) && major >= requiredMajor;
}

import assert from "node:assert/strict";
import { supportsNode } from "./supports-node.mjs";

assert.equal(supportsNode("18.20.8"), false);
assert.equal(supportsNode("20.0.0"), true);
assert.equal(supportsNode("22.19.0"), true);
assert.equal(supportsNode("not-a-version"), false);

このチェックは意図的に狭く設定されています。通常のテストスイートは依然として最新の主要リリース間の互換性を保持しています。このチェックは宣言された最小値、最初のコマンド、およびクイックスタートが相互に矛盾しないように保ちます。

受入チェックリスト

• Node.js 18でのクリーンインストールは、依存関係のインストール前に停止し、必要なバージョンを指定。
• Node.js 20でのクリーンインストールは、パッケージマネージャまで進む。
• package.json、チェックとクイックスタートはすべて同じ最小値を示しています。
• 依存関係のないテストは、境界値と不正な入力をカバーします。

これは独立したサンプルであり、第三者のリポジトリで検証した実績を示すものではありません。コードと記載内容は、AIの支援を受けて作成した後に人が確認しています。