netlify.toml Builder

A correct netlify.toml without TOML guesswork

netlify.toml configures how Netlify builds and serves your site: the build command, the publish folder, redirects, headers, and functions. TOML tables and array-of-tables syntax are easy to mistype, and a malformed file silently reverts to defaults. This builder produces valid TOML from plain inputs you type, not raw TOML you have to write yourself.

What netlify.toml covers

The file has four main sections, each using different TOML syntax:

• [build] — the command Netlify runs (e.g. npm run build) and the directory it deploys (e.g. dist or _site). The [build.environment] sub-table sets environment variables available at build time.
• [[redirects]] — an array-of-tables where each entry has from, to, and status. Order matters: Netlify applies the first rule that matches a request path.
• [[headers]] — another array-of-tables, with a for path pattern and a [headers.values] sub-table of header names and values.
• [functions] — sets the directory where your serverless function files live.

The double-bracket [[...]] syntax is TOML’s way of defining arrays of objects. A single mistake here — such as writing [redirects] instead of [[redirects]] — silently invalidates all your redirects.

How it works

The builder takes your inputs (build command, publish directory, redirect rules, header values), assembles them into the correct TOML structure, and escapes strings where needed. You do not write a single line of TOML manually. The output is ready to save as netlify.toml at your repository root.

Common patterns and examples

Single-page app (React, Vue, Svelte): set publish to dist, add one redirect rule from = "/*", to = "/index.html", status = 200. This serves every unknown path through the app’s index without changing the URL in the browser.

Security headers for all pages:

[[headers]]
  for = "/*"
  [headers.values]
    X-Frame-Options = "DENY"
    X-Content-Type-Options = "nosniff"
    Referrer-Policy = "strict-origin-when-cross-origin"

API proxy rewrite (keep the URL but fetch from a backend):

[[redirects]]
  from = "/api/*"
  to   = "https://your-api.example.com/:splat"
  status = 200
  force = true

Permanent URL redirect (301 for SEO):

[[redirects]]
  from   = "/old-page"
  to     = "/new-page"
  status = 301

Tips

• Put specific redirect rules before the SPA catch-all, or they will never match.
• Build-time environment variables in [build.environment] are not automatically available in the browser — your bundler must inject them explicitly.
• Commit the file to the repository root and push; Netlify picks it up automatically on the next build.
• The dashboard-based settings and netlify.toml can conflict; file-based config wins for most settings.

Debugging a netlify.toml that is not working

The most common failure modes:

• Redirects not firing. Check that you used [[redirects]] (double bracket) not [redirects] (single bracket). Single bracket silently replaces the whole section with the last entry, and TOML parsers may accept it without error.
• SPA fallback catching everything. If you placed the /* catch-all rule before specific redirect rules, it matches first and those specific rules never run. Order matters in TOML redirects.
• Build command not running. The command in [build] runs in the shell during the Netlify build. If it depends on a dev-only binary, ensure it is listed in devDependencies in your package.json so Netlify installs it.
• Environment variables not available at runtime. Variables under [build.environment] are available only at build time, not to serverless functions at runtime. For runtime variables, use Netlify’s environment variable UI or the Netlify CLI env:set command.