Repository navigation
Add engines Entry to package.json to Specify Required Node.js Versions #30547
Description
Which @angular/* package(s) are relevant/related to the feature request?
core
Description
Hello Angular Team,
When starting a new Angular project, it's not immediately clear which Node.js versions are compatible—especially when working with older Angular versions. Unless developers check the Version Compatibility documentation, they may unknowingly use an unsupported Node.js version, leading to confusing errors.
Proposed solution
A simple and effective solution would be to include an engines field in the generated package.json:
{
// ...
"engines": {
"node": "^20.19.0 || ^22.12.0 || ^24.0.0"
},
}This is a standard Node.js feature that many tools and platforms (e.g., DigitalOcean, Vercel) can use to select the appropriate runtime environment during deployment or CI builds.
Alternatives considered
Optionally, generating an .nvmrc file could help local development, but the engines field provides broader support and clearer intent.
Activity
dgp1130 commentedon Sep 22, 2025
Had a quick discussion on the team about this today.
@angular/*packages already include their ownenginesfield, meaning you get a warning or error (depending on your package manager) when installing an Angular package incompatible with your current Node version. This doesn't require anenginesfield in the Angular application/library itself.An independent benefit of
enginesis that it can be useful for cloud providers to pick a supported Node runtime when attempting to build and run the application and might be worth including for that reason.Unfortunately managing this field after initial project generation gets a bit complicated. If we do nothing, then each time you upgrade Angular, you're potentially invalidating an older Node major version which no longer works with the newer version of Angular.
We could fix that with
ng updateto delete any older version no longer supported by Angular. This can actually bit a little complicated given the flexibility of the syntax in that field (ex.>= 20.0.0style), but is potentially solvable. The bigger problem is that we can't add new versions toengines. Just because Angular adds support for Node v26 doesn't mean the rest of the project has. So it's generally not safe to add|| ^26.0.0to theenginesfield.This effectively creates a hazard. If developers leave the
enginesfield alone and justng updatetheir projects a few times, eventually they will hit the point where that update fails because Angular has moved past the latest Node version generated in that field.Our intuition is that the friction from generating
enginesis not quite worth the benefit of enabling cloud providers to pick a somewhat safer default Node version and we'd rather not move that direction.Separately, both Yarn and pnpm error and fail when installing a dependency with an incompatible
enginesvalue, but NPM only warns unless you enable theengine-strictflag. We like the additional strictness and think that's probably a good default (and one the other package managers have clearly moved towards). So we think it would be useful to generate this option by default for new projects by default, to ensures devs don't accidentally run packages with the wrong Node version and just miss the warning.I filed #31271 to look into enabling
engine-strictby default: #31271angular-automatic-lock-bot commentedon Oct 23, 2025
This issue has been automatically locked due to inactivity.
Please file a new issue if you are encountering a similar or related problem.
Read more about our automatic conversation locking policy.
This action has been performed automatically by a bot.