davila7--claude-code-templates/cli-tool/components/skills/development/netlify-deploy/references/netlify-toml.md

netlify.toml Configuration Reference

Configuration file for Netlify builds and deployments.

Basic Structure

[build]
  command = "npm run build"
  publish = "dist"

Build Settings

Common Configuration

[build]
  # Command to build your site
  command = "npm run build"

  # Directory to publish (relative to repo root)
  publish = "dist"

  # Functions directory
  functions = "netlify/functions"

  # Base directory (if not repo root)
  base = "packages/frontend"

  # Ignore builds for specific conditions
  ignore = "git diff --quiet HEAD^ HEAD package.json"

Environment Variables

[build.environment]
  NODE_VERSION = "18"
  NPM_FLAGS = "--prefix=/dev/null"

[context.production.environment]
  NODE_ENV = "production"

Framework Detection

Netlify auto-detects frameworks, but you can override:

Next.js

[build]
  command = "npm run build"
  publish = ".next"

React (Vite)

[build]
  command = "npm run build"
  publish = "dist"

Vue

[build]
  command = "npm run build"
  publish = "dist"

Astro

[build]
  command = "npm run build"
  publish = "dist"

SvelteKit

[build]
  command = "npm run build"
  publish = "build"

Redirects and Rewrites

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

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

# SPA fallback (for client-side routing)
[[redirects]]
  from = "/*"
  to = "/index.html"
  status = 200

Headers

[[headers]]
  for = "/*"
  [headers.values]
    X-Frame-Options = "DENY"
    X-XSS-Protection = "1; mode=block"
    Content-Security-Policy = "default-src 'self'"

[[headers]]
  for = "/assets/*"
  [headers.values]
    Cache-Control = "public, max-age=31536000, immutable"

Context-Specific Configuration

Deploy different settings per context:

# Production
[context.production]
  command = "npm run build:prod"
  [context.production.environment]
    NODE_ENV = "production"

# Deploy previews
[context.deploy-preview]
  command = "npm run build:preview"

# Branch deploys
[context.branch-deploy]
  command = "npm run build:staging"

# Specific branch
[context.staging]
  command = "npm run build:staging"

Functions Configuration

[functions]
  directory = "netlify/functions"
  node_bundler = "esbuild"

[[functions]]
  path = "/api/*"
  function = "api"

Build Plugins

[[plugins]]
  package = "@netlify/plugin-lighthouse"

  [plugins.inputs]
    output_path = "reports/lighthouse.html"

[[plugins]]
  package = "netlify-plugin-submit-sitemap"

  [plugins.inputs]
    baseUrl = "https://example.com"
    sitemapPath = "/sitemap.xml"

Edge Functions

[[edge_functions]]
  function = "geolocation"
  path = "/api/location"

Processing

[build.processing]
  skip_processing = false

[build.processing.css]
  bundle = true
  minify = true

[build.processing.js]
  bundle = true
  minify = true

[build.processing.html]
  pretty_urls = true

[build.processing.images]
  compress = true

Common Patterns

Single Page Application (SPA)

[build]
  command = "npm run build"
  publish = "dist"

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

Monorepo with Base Directory

[build]
  base = "packages/web"
  command = "npm run build"
  publish = "dist"

Multiple Redirects with Country-Based Routing

[[redirects]]
  from = "/"
  to = "/uk"
  status = 302
  conditions = {Country = ["GB"]}

[[redirects]]
  from = "/"
  to = "/us"
  status = 302
  conditions = {Country = ["US"]}

Validation

Validate your netlify.toml:

npx netlify build --dry

Resources

• Full configuration reference: https://docs.netlify.com/configure-builds/file-based-configuration/
• Framework-specific guides: https://docs.netlify.com/frameworks/