/netlify-config

name: netlify-config
description: Configure Netlify builds and routing via netlify.toml, _redirects, and _headers. Use when setting a build command or publish directory, validating netlify.toml against its JSON schema, adding redirects/rewrites/proxies or an SPA fallback rewrite, or setting custom response headers or basic auth. Also use when managing environment variables and secrets, scoping vars per deploy context, marking a var as secret or disabling secret scanning, configuring functions bundling, ignoring builds, or wiring up a monorepo or JavaScript SPA on Netlify.

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

• Schema: start `netlify.toml` with `"$schema" = "https://open-api.netlify.com/netlify.schema.json"` (key is quoted). Editors and agents with TOML JSON-schema support suggest and validate properties. In VS Code, use the Even Better TOML extension. Netlify ignores the key at build/deploy. **A schema-valid file can still fail to build**, because checks like whether a directory exists happen only during the build.
• 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

"$schema" = "https://open-api.netlify.com/netlify.schema.json"

[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]]`. They do **NOT** include `[[redirects]]` or `[[headers]]`, which 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**, so 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

`_redirects` syntax is `from to [status] [conditions]`. Lines starting with `#` are comments, paths are case-sensitive, and special chars must be URL-encoded:

/home         /              301
/my-redirect  /              302
/ecommerce    /store-closed  404          # custom 404 for a path
/pass-through /index.html    200          # rewrite
/best-pets/dogs /best-pets/cats.html 200! # force/shadow (! or force=true)
/news/*  /blog/:splat                     # splat
/news/:month/:date/:year/:slug  /blog/:year/:month/:date/:slug   # placeholders
/store id=:id  /blog/:id  301             # query params
/  /anz  302  Country=au,nz               # no spaces in value list
/israel/*  /israel/he/:splat  302  Language=he
/* /legacy/:splat 200 Cookie=is_legacy,my_other_cookie

`[[redirects]]` keywords:

• `from`, `to`
• `status` (default `301`)
• `force` (default `false`; same as `!`/shadow)
• `query` (`query = {path = ":path"}`)
• `conditions` (`{Language, Country, Role, Cookie}`)
• `headers` (proxy request headers)
• `signed` (env var name for signed proxies)

**Gotchas:**

• You **cannot** add or remove a trailing slash with a redirect. The CDN normalizes URLs first, so a `/x/ → /x 301!` rule loops infinitely. Rely on Pretty URLs (default on).
• Splat asterisks work only at the **end** of a segment (`/jobs/*`), not mid-path (`/jobs/*.html` is invalid). Placeholders (`:x`) work only at the start of a segment. You can't mix a wildcard and a placeholder in one segment.
• You can't exclude a path from a splat. Put a more specific rule first instead.
• `Country` takes ISO 3166-1 alpha-2 codes. Language redirects match only the **first** `Accept-Language` entry.
• Role-based redirects with external auth providers are **Enterprise-only**.
• For 10,000+ redirects, use wildcards/placeholders or Edge Functions. Oversized serialized output fails the deploy.

Proxies

/api/*           https://api.example.com/:splat        200
/netlify-site/*  https://my-other-site.netlify.app/:splat  200   # use .netlify.app, not custom domain

[[redirects]]                     # custom request headers + force
  from = "/search"
  to = "https://api.mysearch.com"
  status = 200
  force = true
  headers = {X-From = "Netlify"}

Signed proxy rules:

• `signed` names an env var scoped to **Runtime**.
• The rule must live in `netlify.toml`.
• JWS signing works for external targets only, not Netlify→Netlify.

[[redirects]]
  from = "/search"
  to = "https://api.mysearch.com"
  status = 200
  force = true
  signed = "API_SIGNATURE_TOKEN_PLACEHOLDER"

**Gotchas:**

• Cross-team rewrites are disallowed.
• Rewrites within the same password-protected site are OK, but not across separate protected sites.
• Proxy timeout is **26 s**.
• Only one hop by default.
• Assets with rel