Skip to content

fix: lower published engines.node to >=18 (release 0.3.1) - #9

Merged
eagle-head merged 2 commits into
mainfrom
fix/published-engines-floor
Jun 27, 2026
Merged

fix: lower published engines.node to >=18 (release 0.3.1)#9
eagle-head merged 2 commits into
mainfrom
fix/published-engines-floor

Conversation

@eagle-head

Copy link
Copy Markdown
Owner

Summary

Release 0.3.1 (patch). Separates the development Node requirement from the consumer requirement, using the official npm field for each, and relaxes the published floor that 0.3.0 set too high.

0.3.0 shipped engines.node >=22 on the published packages. But the shipped dist targets es2022 and uses no Node-22-only API — so that floor needlessly warned (or, under engine-strict / pnpm / yarn, blocked) installs on Node 18/20 with no runtime benefit. The strict Node 22 is really a toolchain requirement (Vitest 4 etc.), not a runtime one.

Changes

  • Published core + react: engines.node >=22>=18 (the consumer-facing field).
  • Private workspace root: replace engines.node >=22 with devEngines.runtime ({ name: node, version: >=22, onFail: error }) — the field npm documents for "people interacting with the source code", validated before install/ci/run.
  • packages/core/README.md: "Supported runtimes" → Node.js 18+ (the only consumer doc that stated a Node minimum). CONTRIBUTING.md / RELEASING.md intentionally keep Node 22 as the development requirement.
  • Release: lockstep bump core + react to 0.3.1 (react → core ^0.3.1); [0.3.1] changelog section in all three changelogs.

Why this is correct per the official docs

Per npm package.json docs: engines is "designed to alert the user when a dependency uses a different node version than the project it's being used in" (consumer), whereas devEngines "is used to alert people interacting with the source code of a project" (dev). So engines = >=18 (consumer) + devEngines.runtime = >=22 (dev) is the documented split.

Verification

  • 🔴→🟢 devEngines is actually enforced: forcing devEngines.runtime >=99.0.0 fails npm install with EBADDEVENGINES; >=22 passes on Node 22. npm here is 10.9.8.
  • bin/quality-gate.sh --full — green (build · format · lint · typecheck · 420 core + 18 react). The gate runs npm run, which also exercises the devEngines validation.
  • npm run docs:build — green.
  • package-lock.json reflects only the engines/version changes — no dependency churn.

Note

SemVer: relaxing the engine floor is backward-compatible (wider install surface, no API change) → patch. The npm publish stays gated behind the npm-publish environment manual approval after the v0.3.1 tag is pushed.

Separate the development Node requirement from the consumer requirement,
using the official npm fields for each.

- Published packages (`core`, `react`): lower `engines.node` from `>=22`
  to `>=18`. The shipped `dist` targets es2022 and uses no Node-22-only
  API, so the previous floor needlessly warned (or, under
  `engine-strict`, blocked) installs on Node 18/20 with no runtime gain.
- Private workspace root: replace `engines.node >=22` with
  `devEngines.runtime` (`name: node`, `version: >=22`, `onFail: error`)
  — the field npm documents for alerting people working on the source.
  Verified that npm 10.9.8 enforces it: an impossible version fails
  `npm install` with EBADDEVENGINES, while Node 22 passes.
- Align the core README "Supported runtimes" to Node.js 18+ (the only
  consumer-facing doc that stated a Node minimum). CONTRIBUTING/RELEASING
  intentionally keep Node 22 as the development requirement.
Lockstep bump of core + react to 0.3.1 (react -> core ^0.3.1) and cut the [0.3.1] changelog section. The release contains the published engines.node >=18 relaxation.
@eagle-head eagle-head self-assigned this Jun 27, 2026
@eagle-head
eagle-head merged commit eaf9a24 into main Jun 27, 2026
1 check passed
@eagle-head
eagle-head deleted the fix/published-engines-floor branch June 27, 2026 02:12
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant