use-vercel-deploy-in-monorepo

Vercel deployment for monorepos and standalone repositories

Scope of application and exclusions

Used for deploying Nuxt, Nitro, Vite, UniApp H5, etc. in a pnpm workspace or standalone repository. One Git repository can be linked to multiple Vercel Projects, but each Project must be accepted separately.

Does not handle GitHub Actions, GitHub Workflow, or other self-built CI deployments. Without user authorization, do not commit, push, modify real cloud configuration, unlink, or delete team resources.

Non-skippable discipline

The formal delivery chain is Vercel Git Integration. Only the target Project deployment triggered by Git push counts as formal acceptance; local CLI upload, MCP triggers, and Prebuilt are only used for build diagnostics, artifact verification, or an explicitly authorized emergency auxiliary chain.
Local link is a single-slot binding. Every time you switch the target Project, or before running an interactive local deployment in any directory, first run vercel link --project <project-name> --yes, then in the same execution directory read .vercel/project.json, and compare projectId and orgId exactly against the remote values of the target Project and target team respectively. If a field is missing or inconsistent, stop immediately; do not judge only by project name or directory name.vercel link It only binds the local CLI Project and never proves that the Vercel Project is connected to a Git repository.
Decide Node first, then design the build. Before writing the Build Command, Turbo dependencies, and remote settings, based on engines.node, version files, package manager, dependency compatibility, remote nodeVersion and the current officially supported range, make an evidence-based choice between 22.x and 24.x; when both are usable, follow the repository baseline, and do not upgrade without sufficient evidence.
All remote writes require read-after-write verification. Settings are fixed as GET → compare → minimal PATCH → GET → inspect; Shared Environment Variables are fixed as GET → precise identification → conflict check → incremental PATCH → GET. If permissions, fields, or read-back fail, stop and do not guess success.
Do not leak or substitute team resources. Do not print tokens, secret values, or private authentication files; ordinary project variables are not equivalent to a Shared Environment Variable link. By default, only fill in explicitly declared missing links; unlink requires explicit authorization, and deletion is prohibited by default.

P0 phase gate

Reconnoiter the target repository, production branch, target team/Project, Root Directory, Git connection, and current deployment source.
Clarify that Git Integration is the formal main chain; confirm that local Prebuilt is only auxiliary.
Establish or verify the Git repository connection and Production Branch separately for each target Project. For a new Project, import the Git repository from the Dashboard; for an existing Project, connect/change the repository in Settings and set the Production Branch. When the public documentation does not stably describe an API, you must stop at the Dashboard manual gate and mark it as blocked until read-back is complete; for the full path and evidence, seeGit deployment and diagnostics。
Decide on Node 22.x or 24.x, and write down the basis and the current remote value.
If local manual operation is needed, complete the CLI single-slot link and projectId/orgId dual-ID gate (seeCLI and remote reading）。
Read, compare, and minimally update Project Settings (seeSettings write-back). Root Directory is not in the default PATCH allowlist; modifying it requires separate user authorization and re-evaluation of commands and artifacts.
Audit the project variables and Shared Environment Variables for Production, Preview, and Development separately; only pershared variablescomplete the actual team variable linking.
Run the build locally and check .vercel/output, but do not equate it with Git main-chain success.
After obtaining push authorization, trigger a Git deployment with an identifiable commit SHA, and completeGit E2E。
update the target project README and the existing AI memory (seeproject deployment documentation）。

P1 delivery quality gate

Review .vercelignore, to avoid ignoring the workspace, build inputs, runtime files, or incorrectly excluding .vercel/output。
Triage logs across six layers: upload, install, build, artifacts, runtime, and domain; first confirm whether the deployment source is Git clone, CLI upload, or Prebuilt.
For Nitro, verify serverDir against the real directory, functions artifacts, and API smoke tests; for Turbo, use dependsOn and outputs to express cross-package dependencies; do not replace the task graph with multi-step shell chaining.
Verify the Production, Preview, and Development scopes separately; retain item-by-item evidence from the first E2E rather than just checking boxes.

Git main chain and local auxiliary chain

The evidence order for the Git main chain is: push commit → Vercel clones/checks out the repository → Install → Build → Output → READY → target URL smoke test. In the logs, Cloning or an equivalent Git checkout, plus a matching commit SHA, is required to prove the Git main chain;Downloading deployment files can only prove the file upload or Prebuilt path.

Local Prebuilt can only verify the local build and .vercel/output, or help distinguish local code issues from cloud Git environment issues. Local READY cannot close any Git E2E item. For complete triage and E2E, seeGit deployment and diagnostics。

Write and capability routing

The priority is fixed as: CLI-specific commands → vercel api → direct REST API → MCP → Dashboard.

CLI is used for link, project inspect, deployment, and logs; first probe vercel api --help, then decide whether the API can be called.
vercel api or direct REST API is used for scenarios such as Settings and Shared Variable that have no CLI-specific write command; the REST token is read-only for VERCEL_TOKEN environment variables.
MCP only assists with reading projects, deployments, and logs; it is not a substitute for writing Settings or Shared Variables, and in particular it must not be claimed that MCP can Link Shared Variable. For capability boundaries, seeMCP operations。
When none of the above automatic write paths are available, provide the Dashboard operation location and mark it as blocked; do not fabricate that the configuration has been written.

Build, artifacts, and framework routing

Permonorepo deployment modefirst choose mode A (root .vercel/output) or mode B (subpackage direct artifacts), and keep Root Directory, Build Command, Install Command, and Output Directory on the same basis.

Use copyable templates according to the actual framework, and at the same time choose the corresponding Turbo task template:

Nuxt script / Nuxt Turbo
Nitro script / Nitro Turbo
Vite script / Vite Turbo
UniApp H5 script / UniApp H5 Turbo
Standalone Nitro
When root artifact relocation is needed, also refer to Transfer task。

When Nitro's server source is not in the default location, first read nitro.config.*, and verify serverDir and the directory's existence; after building, check the functions artifacts, and the first Git E2E covers the API provided by that directory. Do not substitute build success for runtime verification.

Symlink artifact transfer (mode A only)

move-vercel-output-to-root is responsible for moving the subpackage's .vercel/output to the .vercel/outputthat Vercel reads at the repository root. Its --dereference is a copy strategy switch, not a Nitro, pnpm/Corepack, or runtime configuration switch, and it must remain off by default.

Parameter	Default value	Semantics and boundaries
`--root-dir <path>`	Automatically discover the workspace root	Only explicitly specify the monorepo root when auto-discovery is not applicable
`--source-dir <path>`	Subpackage `.vercel/output`	must be the source directory actually written by this build
`--target-dir <path>`	Root `.vercel/output`	must match the Project's Output Directory definition
`--skip-clean`	`false`	Only use when it has been verified that multiple independent artifacts need to be merged; it cannot be used to bypass stale functions
`--dry-run`	`false`	Only displays the resolved path and strategy, does not copy or clean; it cannot replace actual artifact checks
`--dereference`	`false`	Copies the entity files/directories pointed to by symlinks to the target; only enable for trusted artifacts based on evidence

Programmatic API uses dereference?: boolean; the resolution result and build log must record the final boolean value.

Before enabling, confirm in order:

Vercel uses mode A, and the root .vercel/output is the final read directory; mode B or an independent repository should not add root transfer.
Run the real build:vercel, and check the subpackage and root directory .vercel/output/functions。
Use lstat or equivalent checks to confirm the .func item to be transferred is indeed a symlink, and keep the reproducible function topology, routes, or consumption failure evidence when not dereferenced.
Confirm that both the link and its target come from this trusted build artifact; content outside controlled directories must not be brought into the deployment.
After enabling, confirm the target .func in the root output has been materialized, and read the resolution result from the Vercel Git build log, then complete the target API smoke test.

Only when all the above conditions are simultaneously met, add --dereferenceto the atomic transfer task. Normal file copy behavior should remain unchanged;--dry-run must show dereference, and must not copy or clean. Do not enable it because of ERR_PNPM_META_FETCH_FAIL, Corepack/Node drift, Nitro compatibilityDate not being confirmed, or API runtime 5xx: these belong to the installation, Nitro configuration, or runtime layer respectively and should be investigated at the corresponding layer.

README and AI memory wrap-up

Deployment facts must be written back to the target project README, and equivalently update the existing AGENTS.md、CLAUDE.md、GEMINI.md. If all three AI memories are missing, hand off to init-ai-md, and do not create a project-specific deployment skill. For fields and security boundaries, seeproject deployment documentation。

First Git E2E checklist

The Git repository, production branch, target team/Project, and Root Directory have been verified.
Each Project has independently completed Git repository connection and Production Branch setup; the Project GET's link actual fields and Dashboard Branch Tracking evidence have been read back, and missing items are marked as blockers.
The Node 22.x/24.x selection and rationale have been recorded, and the remote nodeVersion has been compared.
If performing local operations,vercel link --project after .vercel/project.json the projectId、orgId is already exactly consistent with the remote target.
Settings has completed the minimal PATCH, GET read-back, and vercel project inspect cross-validation, or it is explicitly recorded that no changes are needed.
Project variables and Shared Environment Variables have both covered the three environments; the Shared link has no project variable with the same name shadowing it and has been read back.
.vercelignore、Turbo DAG、Nitro serverDir and .vercel/output have been checked.
It has been confirmed that Root Directory, Output Directory, and the root .vercel/output of Mode A are consistent in definition; the .func link status of the subpackage and root output has been recorded, and the basis for dereference being true or false has been explained.
If --dereferenceis enabled, it has been confirmed that the source artifacts are trusted, the root output has been materialized, and it does not escape the controlled directory; the parsed values in the Git build logs are consistent with expectations.
After authorization was obtained, an identifiable commit has been pushed, and the formal Git E2E has been completed with the SHA, Git checkout logs, READY, and URL smoke test.
The README and existing AI memory have been finalized; no tokens, secrets, or local private paths have been recorded.