Netlify configuration

netlify.toml lives at the repo root (or set base/package directory for monorepos). Settings in netlify.toml override the Netlify UI on conflict. _headers and _redirects are extensionless plain-text files in the publish directory, processed before netlify.toml rules.

Footguns (read first)

• Env vars in netlify.toml are NOT available to functions or edge functions at runtime — reading them there returns undefined. Vars declared in netlify.toml only get the Builds and Post processing scopes. Set runtime vars in the UI or with netlify env:set.
• Never put secrets in client-prefixed vars (VITE_, NEXT_PUBLIC_, PUBLIC_, …) — they are inlined into the client bundle. --secret does not protect them.
• .env is not read by the Netlify build system — import variables into Netlify first (netlify env:import). The CLI reads .env only for local builds.
• Direct env injection into netlify.toml (key = "$VAR") is unsupported — except signed proxy redirects. Use a build plugin or sed in the build command.
• [[redirects]] and [[headers]] are global — NOT context-aware, cannot be scoped to branches/contexts. Workaround: per-context build command copies a custom file into the publish directory.
• Proxy rewrites time out at 26 seconds. HTTP 307 is unsupported — use 302.

netlify.toml — core structure