skip to content

In an npm package's package.json, what does `engines` do when a consumer's Node.js is outside its range, and what makes npm refuse?

level: middleimportance: should knowfreq 12%

answer

  1. a declaration, not a guard
  2. warning when installed as a dependency
  3. engine-strict config
  4. --force overrides even strict mode
  5. install by name prefers compatible versions

basics

~20 s

The engines field declares the Node.js (and npm) versions a package supports; by default a mismatch only prints a warning and the install continues. Setting engine-strict=true makes npm refuse with EBADENGINE, and --force overrides even that.

solid answer

~40 s

`engines`, for example `"engines": { "node": ">=22" }` in `@fleetline/charts`, states which runtime versions the package supports. npm treats it as **advisory**: when the package is installed as a dependency on an unsupported Node.js, npm warns and installs it anyway. Setting the `engine-strict` config to `true`, usually in the consuming project's `.npmrc`, makes npm refuse such packages with an `EBADENGINE` error naming the required and actual versions; `--force` still pushes past it. When you install by name without a version, npm also prefers the newest version whose `engines` matches the running Node.js, so `npm install <pkg>` can pick an older release than `latest`. For contributors' own tooling, the separate `devEngines` field checks the environment before `install`, `ci` and `run`.

go deeper

for a junior

Recall that engines lists supported Node.js versions and that npm only warns about a mismatch unless engine-strict is set.

for a middle

Explain where engine-strict is configured, what EBADENGINE reports, and why npm install <name> can choose an older compatible version.

for a senior

Decide whether a project enforces engine-strict, and treat raising a library's engines floor as a breaking change for consumers.

for a principal

Align a Node.js support policy across libraries and apps so engines, CI test matrices and runtime images move together on one schedule.

## What `engines` declares The `engines` field in `package.json` lists the runtime versions a package works on. The keys npm reads are `node` and `npm`, and each value is a semver range: ```json { "name": "@fleetline/charts", "engines": { "node": ">=22" } } ``` Leaving `engines` out, or writing `"*"`, means any version will do. For a library the field is a statement to its consumers: "this code is tested and supported on these runtimes". It is checked when someone installs the package, not when the code runs; nothing in `engines` stops a project from starting on an older Node.js. ## The default: a warning, not a refusal npm's documentation is explicit that, unless the user has set `engine-strict`, the field is **advisory only** and produces **warnings** when the package is installed as a dependency. So when the dispatch dashboard, still on Node.js 20, installs `@fleetline/charts` from its lockfile: - npm installs the package and prints a warning naming it and its required range. - The install exits successfully, and CI stays green. - The first sign of trouble may be a runtime error from an API that Node.js 20 does not have. - The check compares against the Node.js that is running npm, so it is the build machine's runtime that gets checked, not the production server's; a CI image on a different Node.js than production can hide real warnings or show ones that do not apply. This is why a warning about engines in an install log deserves attention rather than being scrolled past. ## Making npm refuse with `engine-strict` The `engine-strict` config defaults to `false`. Set to `true`, npm refuses to install, or even consider installing, any package that claims to be incompatible with the current Node.js version. 1. Put `engine-strict=true` in the **consuming project's** `.npmrc` and commit it, so every developer and CI job gets the same behaviour. 2. An incompatible package now fails the install with **`EBADENGINE`**, and npm prints the package, the `Required` engines and the `Actual` Node.js and npm versions. 3. `--force` overrides this: its description includes installing packages whose `engines` require a different Node.js version even when `engine-strict` is enabled. Treat a forced install as a recorded exception, not a habit. Note where the switch lives: the library declares `engines`, but only the **consumer** decides whether the declaration is enforced. ## Installing by name prefers compatible versions There is a second, quieter effect. When you run `npm install <name>` without a version or tag, npm prioritises versions whose `engines` match the running Node.js. If `latest` requires a newer runtime, npm installs the newest compatible version instead. To get `latest` regardless, ask for it explicitly with `npm install <name>@latest`, which then installs with the usual warning (or fails under `engine-strict`). This explains a common puzzle: two developers on different Node.js versions run the same `npm install <name>` and save different versions into `package.json`. ## Default, strict and forced side by side | Setup | Dependency outside its `engines` range | Typical use | |---|---|---| | defaults (`engine-strict=false`) | installed, with a warning | most projects | | `engine-strict=true` | install fails with `EBADENGINE` | teams that want unsupported packages caught at install | | `engine-strict=true` plus `--force` | installed despite the mismatch | a recorded, deliberate exception | | bare `npm install <name>` | newest compatible version chosen | adding a package by name | One neighbour is easy to confuse with `engines`: the separate `devEngines` field describes the tooling a contributor to *this* repository needs and is checked before `install`, `ci` and `run`; it does not affect anyone who installs the published package. ## Practical guidance - **Library authors** keep `engines.node` honest: the lowest version the test matrix covers, raised in a major release because dropping a runtime breaks consumers. - **App teams** that want unsupported packages caught at install time commit `engine-strict=true` instead of reading warnings in CI logs. - **CI images** run the same Node.js major as production, so the engines warnings in a build log describe the runtime that will actually execute the code. - **Everyone** reads an engines warning as information about a real incompatibility, not noise; it is the package author telling you the combination is untested. The interview answer worth giving: `engines` is a declaration that npm turns into a warning by default and into a hard failure only when the consumer opts into `engine-strict`.

  • Two developers run `npm install <name>` on the same day and save different versions. How can `engines` explain that?
    When installing by name without a version or tag, npm prefers the newest version whose `engines` match the running Node.js. A developer on an older runtime gets an older compatible release if `latest` requires a newer Node.js. Aligning Node.js versions, or installing `<name>@latest` explicitly, removes the difference.
  • Your library raises `engines.node` from `>=20` to `>=22`. Should that be a patch, minor or major release?
    Treat it as a major: consumers still on Node.js 20 now get warnings, or `EBADENGINE` failures if they enforce `engine-strict`, and the code may use APIs their runtime lacks. Dropping a supported runtime breaks a contract consumers relied on, so it belongs with other breaking changes.

  • engines blocks an incompatible install by default
  • engine-strict belongs in the library's package.json
  • engines stops the application from starting on an old Node.js
  • --force cannot override engine-strict
  • npm install <name> always installs the latest tag