Detecta una versión de Node.js incompatible antes de instalar

Un paquete puede declarar "node": ">=20" y aún así dejar a un desarrollador con un fallo vago varios comandos después. Trata la versión de tiempo de ejecución como un contrato ejecutable: indícala, verifícala, y detente con una instrucción de reparación antes de instalar dependencias.

La verificación pequeña

Agrega un script sin dependencias en 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.`);

Ejecutarlo antes de la ruta normal de instalación:

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

El engines el campo permite que los gestores de paquetes y los sistemas de alojamiento inspeccionen el requisito. El script hace que el mismo requisito sea visible para alguien que use un gestor de paquetes que solo advierte sobre incompatibilidades de motor.

Haga que la documentación use la misma fuente de verdad

El inicio rápido debería decir exactamente lo que la verificación aplica:

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

Una frase como “una versión reciente de Node.js” no puede ser probada, y se desplaza en cuanto el producto adopta una nueva línea base.

Pruebe ambas ramas sin cambiar los tiempos de ejecución

Extrae la comparación en una función pura para que la prueba de regresión pueda cubrir versiones soportadas y no soportadas:

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

Esta verificación es deliberadamente limitada. El conjunto de pruebas normal aún mantiene la compatibilidad con versiones principales más recientes. Esta verificación mantiene el mínimo declarado, el primer comando y el inicio rápido sin contradecirse entre sí.

Lista de verificación de aceptación

• Una instalación limpia en Node.js 18 se detiene antes de la instalación de dependencias y nombra la versión requerida.
• Una instalación limpia en Node.js 20 continúa con el gestor de paquetes.
• package.json, la comprobación y la guía rápida nombran el mismo mínimo.
• Una prueba sin dependencias cubre los límites y entradas malformadas.

Este ejemplo independiente no afirma haberse probado en un repositorio ajeno. El código y las afirmaciones se revisaron manualmente tras una redacción asistida por IA.