Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 2 additions & 0 deletions docs/dependency-maintenance.md
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand Down
31 changes: 30 additions & 1 deletion docs/vercel-deployment.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand All @@ -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:<version>-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:
Expand Down