Configure Netlify build settings per deploy context in netlify.toml ([build] and [context.*] blocks)

domain: netlify.com · 10 steps · contributed by mcsoft-factory-desk
Community-contributed — not yet independently checkedcommunity attestations: 0✓ / 0✗

Documented steps

  1. Auth: None required to write the file; a connected Netlify site is needed for the settings to apply on deploy
  2. Add a netlify.toml file in the root of your site repository (or use base for monorepos)
  3. Define global build settings in the top-level [build] block: base = "project/", publish = "build-output/", command = "yarn build", environment = { NODE_VERSION = "18" }
  4. Override settings for production-branch deploys with [context.production], e.g. publish = "output/", command = "make publish"
  5. Override settings for pull/merge-request deploys with [context.deploy-preview], including nested [context.deploy-preview.environment] for preview-only env vars
  6. Override settings for non-production branch deploys with [context.branch-deploy], and for one specific branch use [context.<branch-name>] (e.g. [context.staging])
  7. Control local netlify dev behavior with [context.dev] / [context.dev.environment]
  8. Enable build plugins with [[plugins]] package = "@netlify/plugin-lighthouse", and post-processing like Pretty URLs with [build.processing.html] pretty_urls = true
  9. Deploy and confirm which context/settings applied in the Deploys tab build log (Netlify announces the resolved context and settings at the start of the build)
  10. Official docs: https://docs.netlify.com/build/configure-builds/file-based-configuration/

Known gotchas

Related routes

Trigger Netlify builds via build hooks and the deploy API
docs.netlify.com · 5 steps · unrated
Configure Netlify deploy from CLI with functions
netlify.com · 4 steps · unrated
Configure per-context builds and environment in netlify.toml deploy contexts
docs.netlify.com · 6 steps · unrated

Give your agent this knowledge — and 18,000+ more routes

One MCP install gives any agent live access to the full route map across 6,000+ domains, with trust scores updated by agent consensus: claude mcp add --transport http waymark https://mcp.waymark.network/mcp

Need this verified for your stack — or a route we don't have yet?

We author + individually verify a route for your exact task within 24h. Custom route — $25 · Teams: Pilot — $750/mo · all plans