Intermediate
How to configure build settings on Netlify
Quick Answer
Link your Git repo in Netlify UI, navigate to Build settings, configure base directory (e.g., /frontend), build command (e.g.,
npm run build), and publish directory (e.g., dist); save to trigger deploy. Use netlify.toml in repo root for overrides like context-specific commands. Test locally with netlify build --debug 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>
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.
Tip
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.Tip
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.Tip
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.Tip
Check your framework docs (e.g., Vite outputs to
dist) 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.
Tip
Pin Node version via environment variable like
NODE_VERSION=20 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.
Tip
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"Tip
Use contexts like
[context.deploy-preview] 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).Tip
Set env vars locally via
netlify env:set KEY value for accurate testing.Troubleshooting
"Failed during stage 'building site': Build script returned non-zero exit code" or "npm run build failed"
Verify build command is correct (e.g.,
npm run build, not npm install). Check logs in Deploys tab, test locally with netlify build --debug, ensure dependencies match.Build skips or uses wrong paths in monorepos
Confirm base directory and package directory point to correct subfolders (e.g.,
/frontend). Use netlify.toml with explicit base and publish.Node/Ruby version mismatch causing failures
Set
NODE_VERSION (e.g., "20") as environment variable in UI or netlify.toml under [context.production.environment]. Select specific build image if needed.Static site deploys blank or 404s
Set publish directory to
. or public, leave build command blank. Ensure index.html is in root or specified folder.Environment variables not available during build
Add vars in UI under Project configuration > Build & deploy > Environment. Test with
netlify build after netlify env:set.Ready to get started with Netlify?
Put this tutorial into practice. Visit Netlify and follow the steps above.
Visit Netlify →