chore(build): move the Admin UI toolchain to Node 24

[yuneng-berri]

TLDR

Problem this solves:

• Node 18 and 20 are both past end of life
• Release images and every CI lane still build on them
• min-release-age needs npm 11.10+; npm 10 discards it
• So the dependency cooldown has never actually applied
• A stale npm skips the gate with no signal

How it solves it:

• Every Node surface moves to 24.19.0, which ships npm 11.17.0
• engine-strict binds the engines floor, failing loudly
• Every build script reads .nvmrc, so the version has one home

Relevant issues

Linear ticket

Pre-Submission checklist

Please complete all items before asking a LiteLLM maintainer to review your PR

• I have added meaningful tests
• My PR passes all CI/CD checks (e.g., lint, format, unit tests)
• My PR's scope is as isolated as possible; it only solves 1 specific problem
• I have received a Greptile Confidence Score of at least 4/5 before requesting a maintainer review (Greptile reviews automatically once the PR is opened; only comment @greptileai to re-request a review after pushing changes)

On tests: this PR adds none, and that box is left unticked rather than argued around. It changes toolchain configuration, not behaviour, so what demonstrates it is the existing 6049-test dashboard suite running green on the new toolchain plus real image builds, both under Proof of Fix. An earlier revision did add a CI probe asserting the cooldown was live; it was dropped as redundant once engine-strict makes an unsupported npm fail at install time

The CI and Greptile boxes are unticked because neither has finished on the latest commit, not because they were skipped

Delays in PR merge?

If you're seeing a delay in your PR being merged, ping the LiteLLM Team on Slack (#pr-review).

Screenshots / Proof of Fix

This change does not touch the request path, so there is no LLM call to make against a live proxy; no code that serves /v1/chat/completions, /v1/responses, or /v1/messages is modified. What it does change is the toolchain that builds the shipped Admin UI and the gate on how dependency versions enter the lockfile, so the proof below exercises exactly those. All captured at cc62349349 unless noted

1. The image we actually ship builds on the new base. This is the ui-builder stage from the root Dockerfile, not a local approximation

$ docker build --target ui-builder -f Dockerfile -t uibuilder-check .
#10 [ui-builder 4/6] RUN --mount=type=cache,target=/root/.npm npm ci --prefer-offline
#10 15.50 added 833 packages in 15s
#12 11.99 ✓ Compiled successfully in 11.4s
#12 33.93 Route (app)
#13 naming to docker.io/library/uibuilder-check:latest done

2. Both pinned images really carry npm 11.17.0. An image shipping an older npm would fail engine-strict at npm ci, so this is checked rather than inferred from the Node version

$ docker run --rm node:24.19-alpine3.24@sha256:d32cdf619f63fe0471182d08996dd516c6275bb5fd31ae06e55a570bd9e1ad43 sh -c 'echo "node $(node -v) / npm $(npm -v)"'
node v24.19.0 / npm 11.17.0

$ docker run --rm cimg/node:24.19@sha256:8966565f07189a67d64d6808a2b127f31dafae566508e3547f55640e1070bfad sh -c 'echo "node $(node -v) / npm $(npm -v)"'
node v24.19.0 / npm 11.17.0

3. The cooldown is live on the new toolchain and was inert on the old one. A scratch project with an impossible cooldown is asked to resolve a package. npm 11 refuses; npm 10 resolves anyway, which is the silent failure this PR closes. The engines floor plus engine-strict is what prevents the npm 10 case from recurring, since an unsupported npm can no longer reach npm ci at all

$ printf 'min-release-age=999999\n' > "$probe/.npmrc"
$ (cd "$probe" && npm install --package-lock-only --no-audit --no-fund react)

  npm 11.17.0 -> npm error code ENOVERSIONS / No versions available   => gate PASSES
  npm 10.8.2  -> added 1 package                                      => gate FAILS

4. engine-strict refuses an unsupported npm instead of skipping quietly. Run against this branch's tree on the old toolchain

$ npm ci --no-audit --no-fund
npm error code EBADENGINE
npm error notsup Required: {"node":">=24.0.0","npm":">=11.10.0"}
npm error notsup Actual:   {"npm":"10.8.2","node":"v20.20.2"}

5. The dashboard suite on the new toolchain. Run on the merged tree at cc62349349 under Node 24.19.0

$ npx vitest run --reporter=dot
 Test Files  579 passed (579)
      Tests  6049 passed (6049)

Baseline for comparison, the same tree on Node 20 before this change: 579 files / 6049 tests, also green. One caveat worth stating rather than hiding: src/components/team/TeamInfo.test.tsx failed in two intermediate full runs during development while passing 43/43 in isolation on both Node 20 and Node 24, so it is a pre-existing flake under parallel load rather than anything this change introduces. It did not reproduce in the run above

6. make pre-commit exits 0 on Node 24, and exits non-zero with EBADENGINE on Node 20, which is the enforcement working on a developer machine

7. The enterprise Docker path, built both ways. No CI job reaches this path, so it was built directly with a temporary enterprise_colors.json to activate it. Same --target builder, base scripts versus this branch's

BASE (litellm_internal_staging):
  Building Custom Admin UI...
  Downloading and installing node v18.17.0...
  Now using node v18.17.0 (npm v9.6.7)
  Error: Failed to switch to Node.js v20. Deployment aborted.
  -> docker build exit=0

THIS BRANCH:
  Building Custom Admin UI...
  Downloading and installing node v24.19.0...
  Found '/app/ui/litellm-dashboard/.nvmrc' with version <24.19.0>
  Now using node v24.19.0 (npm v11.17.0)
  sh: next: not found
  Build failed. Deployment aborted.
  -> docker build exit=0

Read that carefully, because it says something worth knowing. The Node pin is fixed and now resolves from .nvmrc, which is what this PR set out to do. But the customized enterprise UI build does not work on litellm_internal_staging today either: build_admin_ui.sh installs Node 18.17.0 and then calls build_ui.sh, which asks for nvm use v20, a version nobody installed, so it aborts. This branch gets one step further and then fails on a separate pre-existing problem, that build_ui.sh runs npm run build without ever installing node_modules in that path

Both failures are swallowed. set -e is commented out at the top of build_admin_ui.sh and nothing checks build_ui.sh's exit status, so docker build returns 0 and the image ships the default UI. So this PR neither introduces nor repairs that breakage; it removes a wrong Node pin from a path that was already not working. The remaining defect is tracked separately rather than folded in here, since making a silent failure fatal is a behavioural change that deserves its own review

One correction to the review comment that prompted this: the failure mode is not EBADENGINE. The enterprise path never reaches npm ci, so the engines floor is never consulted

Type

🚄 Infrastructure

Changes

Node 18 and Node 20 reached end of life on 2025-04-30 and 2026-04-30. The four UI build images, both CircleCI lanes, and the four GitHub Actions workflows all still built on them, so the release images shipped from an unsupported runtime. Node 24 is the current LTS through 2028-04-30

Node 24 is also the first supported line whose npm implements min-release-age, the dependency cooldown already present in this repo's .npmrc files. npm 10 does not recognise the option; it reads the key and discards it, while npm config get min-release-age still echoes the value back, which makes it look configured. The same setting was separately inert for a month in April when a 3d value parsed to NaN

Tightening engines and adding engine-strict=true turns the floor from advisory into binding, so an unsupported npm fails EBADENGINE rather than quietly skipping the gate. Worth calling out for reviewers: this is a real change in developer experience. Anyone still on Node 20 will get a hard failure from make bootstrap until they switch, and .nvmrc is there so nvm use does the right thing

Node 24's bundled undici tightened its brand check on RequestInit.signal. Under jsdom the Request global comes from Node while AbortSignal comes from jsdom, so new Request(url, { signal }) began rejecting every jsdom signal, breaking the two cases in src/lib/http/api.test.ts that rebase a request onto a runtime base url. tests/jsdomFetchEnv.ts delegates to the jsdom environment and then restores Node's native AbortController and AbortSignal so both come from one realm. Upgrading jsdom does not help; I tried 30.0.1 and it still does not own Request. The underlying testability smell is that api.ts reads globalThis.location at module scope, which is tracked separately rather than folded into this PR

The enterprise Docker path needed fixing too, and it is the part worth a reviewer's attention because no CI job can reach it. docker/build_admin_ui.sh runs only when enterprise/enterprise_ui/enterprise_colors.json is present, which it never is in this repo, and it pinned nvm to v18.17.0 before building a dashboard that now requires Node 24. A customized enterprise image would have failed EBADENGINE. All three UI build scripts now resolve the version from ui/litellm-dashboard/.nvmrc instead of carrying their own pin, so build_ui.sh comes off v20 and build_ui_custom_path.sh off v18.17.0 at the same time

.nvmrc carries the exact patch rather than a bare major so the workflows cannot float to whatever 24.x a runner has cached, and ui/Dockerfile is now pinned by digest like the other three build images. The lockfile changes are npm 11 normalising the engines range and dropping optional peer entries it no longer records

One sequencing note for whoever merges this: project-releaser builds this same dashboard on Node 20 in release-pypi-build.yml and .buildkite/pipeline.yml. Those need to be on Node 24 first, or the next wheel build fails EBADENGINE. That change is in flight separately

Final Attestation

• The tests check the right things, including the edge cases, and regressions in the respective real-world customer use-cases are not possible after this PR

[greptile-apps]

Greptile Summary

The PR centralizes the Admin UI toolchain on Node 24.19.0 and npm 11.17.0, enforcing the supported engine floor across local, CI, and container builds

• Reads the Node version from the dashboard .nvmrc in GitHub Actions and UI build scripts
• Updates CircleCI and Docker builder images to pinned Node 24 releases
• Adds strict engine enforcement and refreshes the npm lockfile
• Introduces a Vitest jsdom environment that restores Node-native abort globals for compatibility with Node's Request

Confidence Score: 5/5

The PR appears safe to merge because no blocking failure remains

The previously reported enterprise Node mismatch and unsound cooldown probe are fixed; the remaining outstanding concern is limited to the acknowledged repository instruction against modifying existing comments

Important Files Changed

Filename	Overview
ui/litellm-dashboard/package.json	Raises the dashboard engine requirements to Node 24 and npm 11.10 so strict installation rejects unsupported toolchains
ui/litellm-dashboard/.npmrc	Enables strict engine enforcement while retaining the local dependency release-age gate
docker/build_admin_ui.sh	Replaces the enterprise build's obsolete Node 18 pin with the centralized dashboard version
ui/litellm-dashboard/tests/jsdomFetchEnv.ts	Wraps Vitest's jsdom environment and restores Node-native abort constructors to keep them compatible with Node's Request implementation
.github/workflows/test-litellm-ui-build.yml	Moves the UI build workflow to the centralized Node version and removes the previously reported unsound cooldown probe
.circleci/config.yml	Updates both UI lanes and the directly installed Node runtime to pinned Node 24 releases

_{Reviews (2): Last reviewed commit: "fix(build): point every Admin UI build s..." | Re-trigger Greptile}

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!

[yuneng-berri]

@greptileai