Détecter une version de Node.js incompatible avant l’installation

Un package peut déclarer "node": ">=20" et laisse encore un développeur avec un échec vague plusieurs commandes plus tard. Traitez la version du runtime comme un contrat exécutable : indiquez-la, vérifiez-la et arrêtez avec une instruction de réparation avant d’installer les dépendances.

La petite vérification

Ajouter un script sans dépendance à 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.`);

Exécutez-le avant le chemin d’installation normal :

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

Le engines le champ permet aux gestionnaires de paquets et aux systèmes d'hébergement d'inspecter la exigence. Le script rend la même exigence visible pour quelqu'un utilisant un gestionnaire de paquets qui avertit uniquement des incompatibilités de moteur.

Faites en sorte que la documentation utilise la même source de vérité

Le guide de démarrage rapide devrait dire exactement ce que la vérification impose :

### 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.

Une phrase telle que « une version récente de Node.js » ne peut pas être testée, et elle dérive dès que le produit adopte une nouvelle base.

Testez les deux branches sans changer les temps d'exécution

Extraire la comparaison dans une fonction pure afin que le test de régression puisse couvrir les versions prises en charge et non prises en charge :

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);

Cette vérification est délibérément restreinte. La suite de tests normale garantit toujours la compatibilité avec les nouvelles versions majeures. Cette vérification maintient le minimum déclaré, la première commande et le démarrage rapide sans contradiction.

Liste de contrôle d'acceptation

• Une installation propre sur Node.js 18 s'arrête avant l'installation des dépendances et indique la version requise.
• Une installation propre sur Node.js 20 continue jusqu'au gestionnaire de paquets.
• package.json, la vérification et le démarrage rapide mentionnent tous le même minimum.
• Un test sans dépendances couvre les entrées aux limites et mal formées.

Cet exemple indépendant ne prétend pas avoir été testé sur le dépôt d’un tiers. Le code et les affirmations ont été revus manuellement après une rédaction assistée par IA.