Skip to content

chore: eliminate the Vercel Node.js version override warning #187

Description

@Che-Zhu

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:

  1. Keep engines.node as the repository-owned source of truth and set Vercel Project Settings to the same major.
  2. Make Vercel Project Settings authoritative for deployment and use a separate repository tool-version file for local development.
  3. 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

Metadata

Metadata

Assignees

No one assigned

    Labels

    enhancementNew feature or request

    Type

    No type

    Fields

    No fields configured for issues without a type.

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions