Problem
Vercel deployments currently emit a Node.js version override warning. The deployment succeeds, but the warning indicates that the repository and the Vercel project are expressing the runtime version through multiple sources with different semantics.
Vercel documents that package.json#engines.node takes precedence over the Node.js version selected in Project Settings. A new Vercel project currently defaults to Node.js 24, while Fulling intends to use Node.js 22.
Current context
The repository currently represents the Node.js baseline in several places:
package.json declares engines.node: "22.x".
- The root package entry in
package-lock.json still records the previous >=22.12.0 constraint.
.github/workflows/ci.yml pins Node.js 22.12.0.
- All Docker stages use the floating
node:22-alpine image.
docs/vercel-deployment.md says Vercel should use Node.js 22.x.
- Vercel Project Settings may still be using its Node.js 24 default, which is then overridden by
package.json during deployment.
This duplication makes it unclear which source is authoritative and produces avoidable noise in build logs.
Why this matters
- Deployment warnings should represent actionable risk rather than expected configuration.
- Build and Function runtimes should use the same intended Node.js major as CI and Docker.
- The committed lockfile should agree with
package.json.
- Future Node.js upgrades should have one explicit, repeatable update path.
Investigation direction
Choose and document one source-of-truth strategy for the Node.js major, then align every environment with it. Options to evaluate include:
- Keep
engines.node as the repository-owned source of truth and set Vercel Project Settings to the same major.
- Make Vercel Project Settings authoritative for deployment and use a separate repository tool-version file for local development.
- Validate Node.js 24 and update CI, Docker, package metadata, and documentation together.
The current project baseline favors Node.js 22, so the first option is the smallest likely change, but it should be verified against a fresh Vercel deployment rather than assumed. Also determine whether the lockfile mismatch contributes to installation or warning behavior and regenerate only the root metadata if needed.
Acceptance criteria
- A clean Vercel Preview deployment contains no Node.js version override warning.
- The effective Node.js major used by both the Vercel build and Functions is explicitly verified.
package.json and the root package metadata in package-lock.json agree.
- CI, Docker, local-development documentation, and Vercel Project Settings express the same supported Node.js policy.
- The chosen source of truth and upgrade procedure are documented.
npm ci, lint, tests, and the production build continue to pass.
Reference
Problem
Vercel deployments currently emit a Node.js version override warning. The deployment succeeds, but the warning indicates that the repository and the Vercel project are expressing the runtime version through multiple sources with different semantics.
Vercel documents that
package.json#engines.nodetakes precedence over the Node.js version selected in Project Settings. A new Vercel project currently defaults to Node.js 24, while Fulling intends to use Node.js 22.Current context
The repository currently represents the Node.js baseline in several places:
package.jsondeclaresengines.node: "22.x".package-lock.jsonstill records the previous>=22.12.0constraint..github/workflows/ci.ymlpins Node.js22.12.0.node:22-alpineimage.docs/vercel-deployment.mdsays Vercel should use Node.js 22.x.package.jsonduring deployment.This duplication makes it unclear which source is authoritative and produces avoidable noise in build logs.
Why this matters
package.json.Investigation direction
Choose and document one source-of-truth strategy for the Node.js major, then align every environment with it. Options to evaluate include:
engines.nodeas the repository-owned source of truth and set Vercel Project Settings to the same major.The current project baseline favors Node.js 22, so the first option is the smallest likely change, but it should be verified against a fresh Vercel deployment rather than assumed. Also determine whether the lockfile mismatch contributes to installation or warning behavior and regenerate only the root metadata if needed.
Acceptance criteria
package.jsonand the root package metadata inpackage-lock.jsonagree.npm ci, lint, tests, and the production build continue to pass.Reference