Customer documentation
Build settings
Configure Vercel framework presets, Node versions, root directories, install commands, build commands, and output folders.
Build settings
Vercel can auto-detect many frameworks and choose sensible build defaults. Use advanced settings for monorepos, custom commands, output directories, package manager differences, or specific Node versions.
Framework preset
Auto-detect, Next.js, Vite, Astro, SvelteKit, Nuxt, Remix, Gatsby, Create React App, Vue, Angular, Svelte, Hugo, Eleventy, or Static / other. Vercel uses this to choose framework defaults.
Node version
Choose 22.x, 20.x, 18.x, or leave blank for the Vercel default. Match the version your app supports.
Root directory
Use this when the app lives inside a subfolder such as apps/web, frontend, packages/site, or client.
Install command
Optional command for dependencies, such as npm install, pnpm install, yarn install, or blank for auto-detect.
Build command
Optional build command such as npm run build, pnpm build, yarn build, astro build, or blank for framework defaults.
Output directory
Directory produced by the build, such as dist, build, out, public, or blank for framework defaults.
Dev command
Optional local development command metadata, usually npm run dev. It is not the main production build command.
When to leave fields blank
Leave advanced fields blank when your project has a standard framework layout. Fill them only when the Vercel build needs a specific command, folder, output path, package manager behavior, or Node version.
How Vercel builds the site
- 1The portal creates or reuses the managed Vercel Project for the serverless site.
- 2The portal applies the selected framework preset, root directory, install command, build command, output directory, dev command, and Node version.
- 3Vercel installs dependencies using the package manager and lockfile it detects, unless an install command overrides that behavior.
- 4Vercel runs the build command or the framework default build command.
- 5Vercel serves the framework output, or for static projects, the configured output directory.
- 6The deployment becomes READY when the build output is valid. It becomes ERROR when install, build, or output validation fails.
Build field details
Framework preset
Tells Vercel how to interpret framework defaults. Auto-detect works when package files and folder layout are standard.
Root directory
The app folder. Use this for monorepos or projects where the deployable app is not at the repository root.
Install command
Runs before build to install dependencies. Leave blank for Vercel defaults unless your project needs a specific package manager or command.
Build command
Creates production output. If this command fails locally, it will usually fail in deployment too.
Output directory
For static output, Vercel serves only the contents of this folder after build. Vite commonly uses dist; many frameworks should leave this blank.
Node version
Choose the version supported by your dependencies. If packages require modern Node, use 20.x or 22.x.
Dev command
Useful metadata for local development; it is not a substitute for a production build command.
Common framework examples
Next.js
Framework preset Next.js. Build command usually npm run build. Leave output directory blank unless the project is intentionally exported.
Vite
Framework preset Vite. Build command usually npm run build. Output directory is usually dist.
Astro
Framework preset Astro. Build command usually npm run build. Output directory is usually dist.
Static HTML
Use Static / other. If files are already final HTML/CSS/JS, output directory can often be public or the folder containing index.html.
Monorepo app
Set Root directory to the app folder, for example apps/web, then set install/build commands if auto-detect does not find them.
Package manager
Commit the correct lockfile when possible: package-lock.json for npm, pnpm-lock.yaml for pnpm, or yarn.lock for Yarn.
No build step
Use Static / other and leave build command blank when the uploaded files can be served directly.
Next.js guide
Preset
Next.js.
Install command
Usually blank, npm install, or the package manager used by the project.
Build command
Usually npm run build.
Output directory
Usually blank. Do not set .next as a static output directory.
Environment variables
Add required server-side variables and NEXT_PUBLIC_ variables under Env vars & logs.
Common issue
A build that works only with local .env files will fail until those variables are added in the portal.
Monorepo guide
A monorepo has multiple projects in one repository. The most common fix is setting Root directory to the folder that contains the app you actually want to deploy.
- 1Find the app folder, such as apps/web, apps/site, frontend, client, or packages/site.
- 2Confirm that folder contains the package.json for the app.
- 3Set Root directory to that folder.
- 4Use the build command that works from that folder.
- 5Set output directory only if the framework needs it.
- 6If shared packages are used, keep the monorepo structure in GitHub instead of uploading only one partial folder.
Output directory guide
Leave blank
Use this when the framework preset knows what to serve, such as most Next.js deployments.
dist
Common for Vite, Astro, and many modern static builds.
build
Common for Create React App and some older toolchains.
out
Common for intentionally exported static Next.js sites.
public
Only use when public is actually the final site output, not just source assets.
Wrong output
The Vercel build may succeed but the site can be blank or 404 if the output directory points to the wrong folder.