Netlify Config

What Is This?

Overview

Netlify Config refers to the netlify.toml file, a configuration file placed at the root of your repository that controls how Netlify builds, deploys, and serves your web application. Written in TOML (Tom's Obvious, Minimal Language) format, this file gives developers precise control over build commands, publish directories, redirects, custom headers, environment variables, and deploy contexts. It serves as the single source of truth for your site's deployment behavior, keeping configuration in version control alongside your code.

The netlify.toml file supports a wide range of directives, from simple build settings to complex redirect rules with splat patterns and conditional logic. It also handles function configurations, edge function settings, and context-specific overrides for environments such as production, staging, and branch deploys. Because the file lives in your repository, every change is tracked, reviewable, and reversible through standard Git workflows.

For teams managing multiple environments or complex routing requirements, netlify.toml eliminates the need to manually configure settings through the Netlify dashboard. This approach reduces human error, enables infrastructure-as-code practices, and makes onboarding new team members significantly faster.

Who Should Use This

• Frontend developers deploying static sites or JAMstack applications to Netlify
• DevOps engineers managing multi-environment deployment pipelines
• Full-stack developers configuring serverless functions alongside their frontend builds
• Teams working in monorepos who need base directory and build context control
• Developers migrating from other hosting platforms who need to replicate routing and redirect logic
• Technical leads establishing consistent deployment standards across multiple projects

Why Use It?

Problems It Solves

• Inconsistent deployment settings caused by manual dashboard configuration that is not tracked in version control
• Complex redirect and rewrite rules that are difficult to manage without a structured configuration file
• Environment-specific build behavior that requires separate configuration for production, staging, and preview deploys
• Missing or incorrect security headers that leave applications vulnerable to common web attacks
• Difficulty reproducing deployment environments when onboarding new developers or debugging production issues

Core Highlights

• Centralized configuration for builds, redirects, headers, and functions in one file
• Support for deploy contexts allowing different settings per environment
• Redirect rules with splat patterns, query parameter conditions, and country-based routing
• Custom HTTP response headers for security and caching control
• Environment variable management scoped to specific deploy contexts
• Serverless function and edge function configuration options
• Full version control integration through standard Git workflows
• Compatible with monorepo setups using the base directory setting

How to Use It?

Basic Usage

Place netlify.toml at the repository root. A minimal configuration looks like this:

[build]
  command = "npm run build"
  publish = "dist"
  functions = "netlify/functions"

Specific Scenarios

Configuring redirects with splat patterns:

[[redirects]]
  from = "/blog/*"
  to = "/posts/:splat"
  status = 301

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

Setting context-specific environment variables:

[context.production]
  command = "npm run build:prod"

[context.deploy-preview]
  command = "npm run build:staging"

[context.production.environment]
  API_URL = "https://api.example.com"

[context.deploy-preview.environment]
  API_URL = "https://staging-api.example.com"

Real-World Examples

A single-page application typically needs a catch-all redirect to serve index.html for all routes, preventing 404 errors on direct URL access. Adding security headers protects users from clickjacking and cross-site scripting attacks:

[[headers]]
  for = "/*"
  [headers.values]
    X-Frame-Options = "DENY"
    X-Content-Type-Options = "nosniff"
    Content-Security-Policy = "default-src 'self'"

When to Use It?

Use Cases

• Deploying a React, Vue, or Svelte SPA that requires client-side routing support
• Setting up API proxy redirects to avoid CORS issues during development and production
• Enforcing HTTPS redirects and canonical domain rules
• Configuring branch-specific deploy previews with isolated environment variables
• Managing serverless function directories and included files
• Applying cache-control headers to static assets for performance optimization
• Implementing geo-based redirects for international sites

Important Notes

Requirements

• The netlify.toml file must be placed at the repository root or at the configured base directory
• TOML syntax must be valid, as parsing errors will cause deploy failures
• Environment variables set in netlify.toml are visible in the repository and should not contain sensitive secrets

Usage Recommendations

Do:

• Keep redirect rules ordered from most specific to least specific
• Use deploy contexts to isolate environment-specific configuration
• Validate your TOML syntax before committing using a linter
• Store sensitive credentials in the Netlify dashboard environment variables, not in the file

Do not:

• Commit API keys or secrets directly into netlify.toml
• Use overly broad redirect rules that may unintentionally catch legitimate routes
• Duplicate settings between the dashboard and the file, as the file takes precedence and conflicts cause confusion