netlify-config

Netlify configuration

Config lives in three files at the repo root (or the base/package directory for monorepos):

• netlify.toml — build, contexts, plugins, functions, redirects, headers, dev.
• _redirects — plain-text redirect/rewrite rules, saved to the publish directory, no extension.
• _headers — plain-text response headers, saved to the publish directory.

netlify.toml values take precedence over the Netlify UI when they conflict. Paths in netlify.toml are absolute relative to the base directory (root / by default).

Modern vs legacy syntax to reach for

• Functions bundler: use node_bundler = "esbuild". zisi is the legacy JS default; TypeScript always uses esbuild.
• Temporary redirect: use status = 302. 307 is unsupported.
• Gatsby Image CDN: use NETLIFY_IMAGE_CDN, not the deprecated GATSBY_CLOUD_IMAGE_CDN.
• Injecting env values into TOML: key = "$VAR" is NOT supported (except signed in proxy redirects). Use a build-command sed substitution or a build plugin (see below).

netlify.toml build + contexts

[build]
  base = "frontend"
  publish = "dist"
  command = "npm run build"
  environment = { NODE_VERSION = "18" }

[context.production]
  publish = "output/"
  command = "make publish"

[context.deploy-preview]
  publish = "dist/"

[context."feat/branch"]        # quote names with special characters
  command = "npm run preview"

[build] runs in Bash. Context-aware keys include [build] and [[plugins]] — but NOT [[redirects]] or [[headers]] (those are always global). Precedence, least→most specific: UI < toml < any-context property < [context.<name>] < [context.branchname].

Redirects and rewrites

_redirects rules are processed first, then netlify.toml; within each, the first matching rule top-to-bottom wins — list specific rules before general ones. Edge functions run before redirects.

SPA history-pushState fallback (required for clean URLs):

/*  /index.html  200

[[redirects]]
  from = "/*"
  to = "/index.html"
  status = 200