Skip to content

improvement: pin Node.js version via .node-version and engines field#1611

Open
trishtzy wants to merge 1 commit intoPortkey-AI:mainfrom
trishtzy:improvement/pin-node-version
Open

improvement: pin Node.js version via .node-version and engines field#1611
trishtzy wants to merge 1 commit intoPortkey-AI:mainfrom
trishtzy:improvement/pin-node-version

Conversation

@trishtzy
Copy link
Copy Markdown

Align local dev and CI on a single Node.js version pinned in .node-version, so contributors using
fnm/nvm/asdf/nodenv/mise pick up a compatible runtime automatically and CI no longer drifts
from the version contributors run locally. Matches the Node 20 runtime already used by the Dockerfile
(node:20-alpine).

Description: (required)

  • Add .node-version (20.20.2, the latest 20.x LTS patch at time of writing). Consumable by nvm,
    fnm, asdf-nodejs, nodenv, and mise. Uses a full MAJOR.MINOR.PATCH so it resolves
    out-of-the-box across all listed managers (nodenv and asdf-nodejs do not resolve partial versions by
    default — see Allow setting version by major version number only nodenv/nodenv#240 / Support x.x format version strings nodenv/nodenv#53).
  • Add "engines": { "node": ">=20.9.0" } to package.json so npm install surfaces a warning on
    mismatch. 20.9.0 is the first active-LTS release of the Node 20 line — same idiom as Next.js
    (>=20.9.0) and Hono (>=16.9.0). The upper bound is intentionally left open; the Node 24 crash
    tracked in fix: Node.js v24 crash — 'Failed to find Response internal state key' #1604 is a dependency bug that should be fixed in @hono/node-server, not papered over here.
  • Update .github/workflows/check_code_formatting.yml and .github/workflows/npm_publish.yml to read
    node-version-file: '.node-version' instead of hardcoding node-version: '20.x', giving the repo a
    single source of truth for Node across local dev and CI. Bumps actions/setup-node from v2v4 and
    v3v4 respectively (required: node-version-file was added in v3).
  • Document the pin in docs/installation-deployments.md under the NodeJS Server section so new
    contributors know where the version comes from.

Tests Run/Test cases added: (required)

  • No runtime code changes — no unit/integration tests added.
  • Verified .node-version satisfies the engines.node range locally (20.20.220.9.0).
  • Verified actions/setup-node@v4 supports node-version-file per upstream
    docs
    .
  • Ran npm run format:check — passes on package.json (repo's format glob excludes .md /
    .node-version / .yml, so no Prettier impact there).
  • CI will exercise the two updated workflows on this PR — confirming Check Prettier Formatting
    runs green against the pinned version.

Type of Change:

  • Bug fix (non-breaking change which fixes an issue)
  • New feature (non-breaking change which adds functionality)
  • Breaking change (fix or feature that would cause existing functionality to not work as expected)
  • Documentation update
  • Refactoring (no functional changes)

Note on "Breaking change": adding engines.node is technically observable for consumers of the
@portkey-ai/gateway npm package who have engine-strict=true in their .npmrc and run Node
<20.9.0. Given the gateway is deployed as a server (not imported as a library) and both the
Dockerfile and CI already assume Node 20, the practical impact is zero. Flagging for transparency —
happy to re-categorize if maintainers prefer.

Align local dev with the Node.js runtime already used in CI
(.github/workflows/*.yml pin 20.x) and the Dockerfile (node:20-alpine),
so new contributors using fnm/nvm/asdf/nodenv/mise pick up a compatible
version automatically.
@trishtzy trishtzy marked this pull request as ready for review April 16, 2026 08:14
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