Skip to content
Tutorials Center
My learning

Topics

Lesson 10 of 37 ยท Build Settings and Environments

Build Settings: Commands, Output and Root

Master the build settings that every project has: install command, build command, output directory, base directory and ignore rules, with where each lives and who wins when they conflict.

Every deploy answers four questions: where is the project, how do I install it, how do I build it, and which folder do I publish? The answers are your build settings. They can be set in three places, and knowing which one wins saves hours of confusion.

This lesson lists the settings on both platforms, shows where they live and gives you a model of the precedence rules.

The core settings

Question Vercel setting Netlify setting
Where is the project? Root Directory Base directory
How do I install? Install Command (automatic from lockfile; runs before the build command)
How do I build? Build Command Build command
What do I publish? Output Directory Publish directory
Where are functions? api/ or framework route files Functions directory (netlify/functions by default)
Should I skip? Ignored Build Step ignore command

If you leave a field empty, the platform uses the preset for the detected framework (see Static Sites and Frameworks). Type a value and it overrides the preset.

Where settings live

  1. The dashboard (UI). Convenient, but invisible in code review.
  2. A config file in the repository (vercel.json, netlify.toml). Versioned and reviewable.
  3. The framework itself. For example, Vite's build.outDir decides where files go. The platform setting must match.

When the dashboard and the file disagree, the file generally wins for the keys it defines. On Netlify, values in netlify.toml override the UI. On Vercel, a setting in vercel.json overrides the project setting (the dashboard may show a notice that it is overridden). Treat this as a rule of thumb and confirm in the build log, which prints the commands it actually ran.

The build command is just a shell command

Anything you can run in a terminal works, including chains:

Terminal
npm run lint && npm run test -- --run && npm run build

If any step fails (non-zero exit code), the whole deploy fails. That makes the build command a convenient quality gate: lint and tests run on every deploy and a broken change never goes live. Keep it fast, though; builds have time limits.

The simplest and most portable approach is to put the real work in package.json scripts and keep the platform command short:

JSON
{
  "scripts": {
    "build": "vite build",
    "build:ci": "npm run lint && vite build"
  }
}

Then set the platform's build command to npm run build:ci.

Output directory pitfalls

  • The directory must be relative to the root/base directory, with no leading slash.
  • It must contain index.html (for sites) at its top level.
  • Frameworks with their own deploy integration (such as Next.js) are special: you leave the output directory empty and the platform uses the framework's own build output.
  • A single-page app with client-side routing needs fallback rules; see the redirects chapter.

Resolving settings: a model

This stand-in layers settings the way you should picture them: preset defaults, then dashboard values, then the config file. It illustrates the idea; the real platforms have more cases.

Node.js Settings precedence (stand-in)

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

Validate settings before you push

Because a mistake costs a full build, a small checker is worth writing. This one inspects a package.json and a settings object, and reports typical problems.

Node.js Settings linter (stand-in)

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

Root directory and what the build can see

If you set a root or base directory, the build can usually only see files inside it unless you enable an option to include files outside (Vercel) or use the repository root as the install location (Netlify). That is why a project in apps/web that imports ../../packages/ui fails by default. See Monorepos.

A reasonable default setup

  1. Commit a lockfile so installs are reproducible.
  2. Put real build steps in package.json scripts.
  3. Put the platform command and output folder in vercel.json / netlify.toml.
  4. Pin the Node version (next lessons).
  5. Read the first part of the build log once after each change to confirm what ran.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. What makes a deploy fail from inside the build command?

    A non-zero exit code stops the build, so lint or test failures can block a deploy.
  2. 2. Where do you set the folder that gets published?

    The output or publish directory names the folder uploaded to the CDN.
  3. 3. If the dashboard says build and the file says another command, which usually wins?

    File settings override the dashboard for the keys they define.
  4. 4. Why is a setup with settings only in the dashboard risky?

    Config files in Git are reviewable and travel with the code.

Summary

  • Build settings answer: where, how to install, how to build and what to publish.
  • Empty fields use the framework preset; typed values override it.
  • A config file in the repository generally beats the dashboard, and the build log shows what really ran.
  • Put the real work in package.json scripts and keep the platform command short.
  • Output directories are relative and must contain index.html for sites.

Next: Environment Variables