N Netlify

How to configure build settings on Netlify

intermediate 8 min read Updated 2026-03-13
Quick Answer

Link your Git repo in Netlify UI, navigate to Build settings, configure base directory (e.g., /frontend), build command (e.g., <code>npm run build</code>), and publish directory (e.g., dist); save to trigger deploy. Use <code>netlify.toml</code> in repo root for overrides like context-specific commands. Test locally with <code>netlify build --debug</code> to mimic production.

Prerequisites

  • Netlify account (free tier sufficient)
  • Git repository (GitHub, GitLab, or Bitbucket) with site code
  • Knowledge of your project's build tool (e.g., npm, or none for static HTML)
  • Optional: Netlify CLI installed via <code>npm install -g netlify-cli</code>

Step-by-Step Instructions

1

Log in and select your site

Log in to your Netlify account at app.netlify.com and select your site from the dashboard. Ensure your Git repository (GitHub, GitLab, or Bitbucket) is linked via continuous deployment if not already set up.
Use the search bar in the dashboard for quick site access if you have multiple projects.
2

Navigate to Build settings

Go to Project configuration > Build & deploy > Continuous deployment > Build settings in the left sidebar. If no settings are configured, click Configure; otherwise, click Edit settings to open the build configuration form.
3

Set the base directory

Enter the Base directory (optional): subdirectory path from repo root where your site's code lives (e.g., /frontend for monorepos). Leave blank for repo root. Netlify uses this to check for package.json or .nvmrc and perform caching.
For monorepos, this ensures dependencies install from the correct subfolder.
4

Configure the build command

Set the Build command (optional): exact command to build your site (e.g., npm run build, nuxt build for Nuxt 3, or leave blank for static sites). Defaults to none, assuming static files in publish directory.
Test your command locally before saving to avoid deploy failures.
5

Specify the publish directory

Set the Publish directory (required for most sites): output folder after build (e.g., dist, build, public). For simple static sites with just index.html, use . or public. This must be specified.
Check your framework docs (e.g., Vite outputs to <code>dist</code>) for the exact path.
6

Set package directory (monorepos)

Set the Package directory (optional, for monorepos): subfolder containing site files if different from base (e.g., /packages/website). If unset, Netlify searches base/root for netlify.toml. Defaults to auto-detected.
7

Adjust advanced settings

Toggle Deploy log visibility: Public logs (default, anyone with URL) or Private logs (team only). Select Build image (advanced): choose specific OS/software versions; defaults to newest and pins Node/etc. on first build.
Pin Node version via environment variable like <code>NODE_VERSION=20</code> for consistency.
8

Save and verify deploy

Click Save to apply changes. Builds trigger on next Git push; check the Deploys tab for status and logs.
Watch the first deploy closely for errors.
9

Use netlify.toml for overrides

Place netlify.toml in repo root (or base directory) to override UI. Example: 
[build]
  command = "npm run build"
  base = "/frontend"
  publish = "dist"

[context.production.environment]
  NODE_VERSION = "20"
Commit and push; file takes precedence.
Use contexts like <code>[context.deploy-preview]</code> for branch-specific settings.
10

Test locally with Netlify CLI

Install CLI: npm install netlify-cli -g. Run netlify init or netlify linked to link site. Test with netlify build --debug (mimics Netlify environment, uses set env vars).
Set env vars locally via <code>netlify env:set KEY value</code> for accurate testing.

Common Issues & Troubleshooting

"Failed during stage 'building site': Build script returned non-zero exit code" or "npm run build failed"

Verify <strong>build command</strong> is correct (e.g., <code>npm run build</code>, not <code>npm install</code>). Check logs in <strong>Deploys</strong> tab, test locally with <code>netlify build --debug</code>, ensure dependencies match.

Build skips or uses wrong paths in monorepos

Confirm <strong>base directory</strong> and <strong>package directory</strong> point to correct subfolders (e.g., <code>/frontend</code>). Use <code>netlify.toml</code> with explicit <code>base</code> and <code>publish</code>.

Node/Ruby version mismatch causing failures

Set <code>NODE_VERSION</code> (e.g., "20") as environment variable in UI or <code>netlify.toml</code> under <code>[context.production.environment]</code>. Select specific <strong>build image</strong> if needed.

Static site deploys blank or 404s

Set <strong>publish directory</strong> to <code>.</code> or <code>public</code>, leave <strong>build command</strong> blank. Ensure <code>index.html</code> is in root or specified folder.

Environment variables not available during build

Add vars in UI under <strong>Project configuration > Build & deploy > Environment</strong>. Test with <code>netlify build</code> after <code>netlify env:set</code>.

Visit Netlify View Netlify Pricing