Control build settings

Build settings tell Vercel how to turn your repository into a deployment. The framework preset fills them in for you, and for a plain Next.js app the defaults are right. The trouble starts when someone overrides one of them in the dashboard and forgets.

Keep the contract in the repository

My rule: if a command is part of how the project works, it lives in package.json. The build command is next build because the build script says so. The Node.js version is 22.x because engines says so. Anyone who clones the repository gets the same answers.

Dashboard overrides are for the rare case where the deployment context really differs from local development. When you need one, write down why. A setting nobody remembers is a setting nobody dares to remove.

Read the whole build input

When a build behaves oddly, don’t stare at the build command alone. Check every input:

• root directory
• package manager, decided by the lockfile Vercel finds
• install command
• build command
• output directory
• Node.js version
• environment variables needed at build time

In a monorepo, a perfectly correct npm run build can still run in the wrong folder. The build log tells you which package.json it found. Look for the line that says which framework and version it detected.

And generated output must come from the build itself. If a folder like public/data/ is in .gitignore and only exists on your laptop, the deployed app won’t have it.

Skipping builds you don’t need

Vercel has an Ignored Build Step setting. It runs a command, and if that command exits with 0, the build is skipped. Handy in a monorepo where a docs change shouldn’t rebuild the app:

git diff HEAD^ HEAD --quiet -- apps/web

Be careful with it. A wrong check silently skips a build you wanted.

Change one thing, compare, then ship

Repository files and dashboard settings have separate histories, so they drift. Whenever you change a dashboard setting, push a trivial commit to a branch, open the Preview build log, and compare it with the previous one. Same install output, same route table, same output size. Only then touch Production.

Try this on your own project: open the project’s build settings and compare every field with package.json and your version files. Remove any override that repeats what the repository already says, or write one line explaining why it exists.