Glossary / Version constraints

Version constraints

Version constraints define which versions of a runtime, package, tool, or peer environment a project claims to support or allows a resolver to select. They appear in dependency ranges, engines, package peer ranges, browser targets, CI matrices, and tool version files; each constraint has a different purpose and enforcement level.

Constraint types

A dependency range permits package-manager resolution within a set of package versions. engines.node expresses a package's Node.js compatibility expectation, but enforcement may be advisory unless configured strictly. A peer range states compatible host versions. Browser target configuration guides transpilation and bundling; it does not necessarily control runtime API polyfills. CI matrices test selected versions but cannot prove every value in a range.

Constraints interact. A package may declare Node 20+, use syntax supported from Node 22, and test only Node 20 and 24; that leaves a gap. Tool constraints (packageManager, .nvmrc, Volta, CI setup) help make builds reproducible but should not be mistaken for consumers' runtime requirements.

Engineering guidance

Document supported ranges, enforce them where practical, and test oldest supported plus current versions. Keep dependency peer ranges aligned with actual compatibility tests. Use feature detection for optional runtime capabilities instead of assuming version numbers when behavior can vary by environment. Review constraints during releases and deprecations.

Interview questions

  1. What does engines do? Declares runtime compatibility; enforcement depends on package-manager settings and context.
  2. Are dependency ranges runtime constraints? They constrain package versions resolved at install time, not runtime capabilities directly.
  3. How establish support for a range? Test boundary and representative versions, and document evidence.
  4. Why not rely solely on version checks? Backports, flags, embedded runtimes, and feature variation can make capabilities differ.
  5. What does a browser target do? Guides transforms/optimization; missing APIs may still need separate polyfills.

References