Skip to content

ci: check the package on its minimum Node.js version - #154

Closed
Kikobeats wants to merge 1 commit into
masterfrom
Kikobeats/ci-engines-floor
Closed

Kikobeats wants to merge 1 commit into
masterfrom
Kikobeats/ci-engines-floor

Conversation

@Kikobeats

@Kikobeats Kikobeats commented Oct 29, 2026 •

Copy link
Copy Markdown
Owner

Adds .github/workflows/engines.yml, which checks that every published package installs and loads on the lowest Node.js version its engines.node allows. A dependency bump or new syntax that raises the real floor now turns CI red instead of breaking users on that version.

What it does

  1. Pack (Node LTS). pnpm install, then for each non-private workspace package (the root package in a single-package repo): run prepublishOnly if present, and pnpm pack it. The floor is read from that package's engines.node at run time. Nothing is hardcoded in the workflow. A range that is not >= x fails the job.
  2. Floor (one matrix job per package, on that floor). In an empty directory, npm install --engine-strict of the package tarball, plus the tarballs of the workspace packages it depends on. This is what a user does: production dependencies only, lifecycle scripts included. Any package in the tree whose engines excludes the floor fails the install with EBADENGINE. Without --engine-strict, npm only warns.
  3. Load. require every runtime entry in exports (or main when there is no exports). Entries that are import-only fall back to import(). Type-only entries and * patterns are skipped.

It runs as its own workflow on pull_request and on push to the default branch, so the release logic in main.yml is untouched.

Why npm on the floor side

pnpm needs Node 18 or later, so it cannot run on older floors, and npm ships with every Node.js version. The install happens in a fresh directory from tarballs, so devDependencies never enter the tree and the test toolchain (ava, c8, standard), which needs a newer Node, is not involved.

Limits

  • setup-node resolves a major-only floor such as >= 20 to the latest 20.x. The job cannot tell 20.0 from 20.12. A floor written with a minor, such as >= 20.19, is checked at the latest 20.19.x.
  • Loading an entry point runs its top-level code only. A dependency required lazily inside a function is covered by the engines check, not by the load.
  • bin scripts are not executed.
  • For a caret or tilde range, npm installs the newest version whose engines accept the running Node. A user on the floor can get an older dependency than a user on current Node, and the job checks the tree the floor user gets. It goes red only when no version in range supports the floor, which is the case that breaks users.

Proof that it catches a violation

On microlinkhq/keyvhq#294, @keyvhq/redis declares >= 20 and depends on ioredis@6, which requires >=20.0.0. A throwaway commit lowered @keyvhq/redis to >= 18:

  • Run with >= 18: Node 18 @keyvhq/redis fails, the other 15 packages pass.
    npm error code EBADENGINE
    npm error notsup Not compatible with your version of node/npm: ioredis@6.0.0
    npm error notsup Required: {"node":">=20.0.0"}
    npm error notsup Actual:   {"npm":"10.8.2","node":"v18.20.8"}
    
  • Run with the real >= 20, after dropping that commit: all 16 jobs pass.

🤖 Generated with Claude Code


Note

Low Risk
Adds CI-only workflow and smoke tests; no application, auth, or runtime deployment changes.

Overview
Adds a standalone engines GitHub Actions workflow (PRs and pushes to master) so release CI in main.yml stays unchanged.

The Pack job installs with pnpm on Node LTS, runs prepublishOnly when present, pnpm packs each non-private package, and builds a matrix from each package’s engines.node floor (only >= x ranges are allowed). Workspace dependencies / optionalDependencies are resolved into tarball closures for matrix installs.

Floor jobs run one per published package on that floor’s Node version: a clean consumer dir gets npm install --engine-strict from those tarballs (production-like install), then a smoke script requires or dynamic-imports every runtime exports entry (skipping types-only and * patterns).

Dependency or syntax that raises the real Node floor should fail CI with EBADENGINE or load errors instead of breaking users on the declared minimum.

Reviewed by Cursor Bugbot for commit 6891155. Bugbot is set up for automated code reviews on this repo. Configure here.

@coderabbitai

coderabbitai Bot commented Oct 29, 2026 •

Copy link
Copy Markdown

Review in Change Stack →

Warning

Review limit reached

You've used all free OSS reviews for now. Wait for the free limit to reset to keep reviewing this public repository.

Next included review available in 31 minutes.

Check out review usage here.

View limit details

Limit details: You’ve used all 2 included reviews currently available.

Learn how review limits work.

Review configuration:

Run configuration
  • Source mode: Auto
  • Repository: Unavailable
  • Branch: Unavailable
  • File: No configuration file from this repository applied
  • Commit: Unavailable
  • Layers: defaults
  • Review profile: CHILL
  • Plan: Advanced
  • Run ID: ff0edf63-3cb6-4fdb-9723-8297e9799f58
Commits

Reviewing files that changed from the base of the PR and between 488d180 and 6891155.

Files selected for processing: 1
  • .github/workflows/engines.yml

No actionable comments were generated in the recent review.

Recent review info
Run configuration
  • Source mode: Auto
  • Repository: Unavailable
  • Branch: Unavailable
  • File: No configuration file from this repository applied
  • Commit: Unavailable
  • Layers: defaults
  • Review profile: CHILL
  • Plan: Advanced
  • Run ID: 998431e8-9430-4e20-a90c-fa9c31bf7059
Commits

Reviewing files that changed from the base of the PR and between 86562b7 and 488d180.

Files selected for processing: 1
  • .github/workflows/engines.yml

Included review availability: This review used your included allowance. Your plan provides up to 2 included reviews per hour; 0 remain after this review.

Walkthrough

Adds a workflow that packs public workspace packages and tests their exported entry points at each package’s declared Node floor.

Changes: Node engine checks

Layer / File(s) Summary
Package packing and test matrix
.github/workflows/engines.yml
The workflow checks that public packages declare a Node engine floor using >=, runs prepublishOnly when present, and packs packages. It creates a matrix with each package’s floor and transitive workspace dependency tarballs.
Installation and export smoke test
.github/workflows/engines.yml
The matrix job installs each package and its workspace dependency tarballs with --engine-strict. It then loads eligible export entry points and fails on load errors or undefined results.

Priority: Normal

Estimated code review effort: 3 (Moderate) | ~20 minutes

Change: Other

Merge Risk: Minimal · previous review 488d1

No actionable merge-blocking risk was identified.

Pre-merge checks: Passed 4
Check name Status Explanation
Description Check Passed Check skipped - CodeRabbit’s high-level summary is enabled.
Title check Passed The title clearly and concisely describes the main change: adding CI coverage for each package's minimum supported Node.js version.
Linked Issues check Passed Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check Passed Check skipped because no linked issues were found for this pull request.
Finishing Touches
🧪 Generate unit tests (beta)
  • Commit to this branch
  • Create a new PR
  • Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

Comment @coderabbitai help to get the list of available commands.

@github-actions github-actions Bot left a comment •

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

cacheable-response

Details
Benchmark suite Current: 6891155 Previous: 86562b7 Ratio
cache hit 98.4 ms (96.2-100.3) 98.9 ms (96.5-99.3) 0.99
cache miss 79.2 ms (75.9-80) 77 ms (76-80.6) 1.03
cache hit 304 via If-None-Match 98.3 ms (93-99.1) 96.2 ms (93.8-97.4) 1.02
cache hit with brotli compression 180.4 ms (172.1-186.6) 179.9 ms (176.3-193.2) 1.00

This comment was automatically generated by workflow using github-action-benchmark.

@Kikobeats
Kikobeats force-pushed the Kikobeats/ci-engines-floor branch 2 times, most recently from c86543b to ce97920 Compare October 29, 2026 09:01
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@Kikobeats
Kikobeats force-pushed the Kikobeats/ci-engines-floor branch from ce97920 to 6891155 Compare October 29, 2026 09:04
@Kikobeats

Copy link
Copy Markdown
Owner Author

Closing: not pursuing the floor CI job.

@Kikobeats Kikobeats closed this Oct 29, 2026
@Kikobeats
Kikobeats deleted the Kikobeats/ci-engines-floor branch October 29, 2026 09:33
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