diff --git a/docs/dependency-maintenance.md b/docs/dependency-maintenance.md index c186340..d37c7e7 100644 --- a/docs/dependency-maintenance.md +++ b/docs/dependency-maintenance.md @@ -10,6 +10,8 @@ opens reviewable pull requests; it must not auto-merge dependency changes. - Review major updates quarterly and migrate them separately. - Coordinate Node.js changes across `package.json`, CI, Docker, Vercel, and contributor documentation instead of allowing a single-file runtime bump. + `package.json#engines.node` is the source of truth; see + [Vercel Node.js runtime source of truth](./vercel-deployment.md#nodejs-runtime-source-of-truth). ## Update boundaries diff --git a/docs/vercel-deployment.md b/docs/vercel-deployment.md index 10fdf3e..cd3fc33 100644 --- a/docs/vercel-deployment.md +++ b/docs/vercel-deployment.md @@ -14,7 +14,7 @@ Connect `FullAgent/fulling` to a Vercel project and keep these settings: - Install command: Vercel default (`npm install` from `package-lock.json`) - Build command: `npm run build` - Output directory: Vercel default -- Node.js: 24.x, enforced by `package.json` +- Node.js: 24.x (Project Settings), matching `package.json#engines.node` - Production branch: `main` No `vercel.json` file or application environment variables are required for this @@ -24,6 +24,35 @@ are handled by the application itself. `output: 'standalone'` remains enabled because the Docker image consumes it. Vercel uses its native Next.js output. +## Node.js runtime source of truth + +`package.json#engines.node` is the repository-owned source of truth for the +Node.js major used by Vercel builds and Functions. Vercel documents that +`engines.node` overrides the project dashboard selection, so a dashboard value +that disagrees with the repository produces a version override warning even when +the deployment succeeds. + +Keep these locations on the same major (currently **24**): + +| Location | Role | +| -------- | ---- | +| `package.json#engines.node` | Authoritative for Vercel and local installs | +| `package-lock.json` root `engines` | Must match `package.json` after `npm install` | +| `.github/workflows/ci.yml` `NODE_VERSION` | CI and release verification pin | +| `Dockerfile` `FROM node:-alpine` | Container build/runtime image | +| Vercel Project Settings → Node.js Version | Dashboard mirror of the same major | +| This document | Operator guidance | + +When changing the Node.js major, update every row in one pull request and verify +a clean Preview deploy (and Docker build) before merge. Do not add a separate +`.nvmrc` or `.node-version` unless the team deliberately changes this policy. + +To silence an override warning without a code change: set Vercel Project +Settings → Node.js Version to the same major as `package.json` (currently `24.x`). +A dashboard default that still points at a different major (for example Node.js +22 or 24 while the repository declares another) will keep warning until both +sides match. + ## Zero-configuration behavior Without the legacy Auth and database variables: