Builds

A build turns your source code into the static assets and functions that get deployed. For most projects this is zero-config: Vercel detects the framework and runs the right command. This page covers what happens and the knobs worth knowing.

What the build step does

When a deployment is triggered, Vercel:

1. Clones your repository at the triggering commit.
2. Installs dependencies (detecting your package manager from the lockfile).
3. Runs the build command for your framework (e.g. next build).
4. Collects the output — static assets and function bundles — and uploads it.

You can override the install command, build command, output directory, and framework preset in project settings or in vercel.json. The build environment receives the environment variables scoped to the target environment.

Build limits

The build step has a maximum duration of 45 minutes; exceeding it fails the deployment. A CLI deployment can upload at most 15,000 source files. There's no hard cap on output files, but tens of thousands of them slow builds down. For large content sites, lean on ISR to pre-render a subset at build time and generate the rest on demand — this keeps build times down as the site grows.

Build cache

Vercel caches build artifacts (such as dependency installs and framework caches like Next.js's) between builds to speed up subsequent deployments. The cache is keyed per project and restored automatically. If a build misbehaves because of stale cache, you can redeploy without the cache from the deployment's menu (or vercel redeploy after clearing it). For monorepos especially, a correctly configured cache prevents unnecessary rebuilds.

Monorepos

Vercel supports multiple projects from a single repository. Each project sets a Root Directory pointing at its app within the repo, and builds only when relevant files change. This pairs naturally with tools like Turborepo. The key settings:

• Root Directory — the subfolder Vercel treats as the project root.
• Ignored Build Step — a command that decides whether a build should run at all (see below).
• Build cache — make sure it's configured so unaffected projects don't rebuild on every push.

Skipping unnecessary builds

The Ignored Build Step lets you skip a build when nothing relevant changed — useful in monorepos where a push might only touch an unrelated app. You provide a command that exits with code 1 to proceed with the build or 0 to skip it. Vercel also exposes a helper:

# Only build if files in the current project changed
npx turbo-ignore

or a custom check against the changed files using the VERCEL_GIT_* system environment variables. Skipping builds you don't need saves both time and usage.

System environment variables

During a build, Vercel injects metadata you can read — for example VERCEL_ENV (production, preview, or development), VERCEL_GIT_COMMIT_SHA, and VERCEL_REGION. These are handy for tagging releases, conditional logic, and instrumentation. They're available both at build time and at runtime.

Building locally

You can reproduce Vercel's build on your machine, which is the closest thing to "what will the cloud do":

vercel pull          # fetch project settings + env into .vercel/
vercel build         # build exactly as Vercel would, into .vercel/output
vercel deploy --prebuilt   # deploy that local build without rebuilding

See CLI: deploying for the full set of options.

Related

• Configuration (vercel.json)
• Deployment workflow
• Functions & compute
• Environment variables