Skip to content
Tutorials Center
My learning

Topics

Lesson 13 of 37 ยท Build Settings and Environments

vercel.json and netlify.toml Configuration Files

Put your deployment settings in code: the structure of vercel.json and netlify.toml, per-context overrides, headers, redirects and functions, with side-by-side examples.

A configuration file turns clicks in a dashboard into reviewable text. Both platforms read one from the repository root: vercel.json on Vercel and netlify.toml on Netlify. Because the file travels with the code, a pull request can change deployment behavior and a teammate can review it.

This lesson shows what each file can express, side by side, and how to merge settings across contexts. Redirect and header rules get their own chapter; here you get the overall shape.

Same job, two syntaxes

Build settings:

JSON
{
  "$schema": "https://openapi.vercel.sh/vercel.json",
  "framework": "vite",
  "installCommand": "npm ci",
  "buildCommand": "npm run build",
  "outputDirectory": "dist"
}
TOML
[build]
  command = "npm run build"
  publish = "dist"
  functions = "netlify/functions"

[build.environment]
  NODE_VERSION = "22"

Netlify has no installCommand: dependency installation happens automatically before your build command. Vercel's $schema line gives your editor autocomplete for the keys.

What each file can contain

Feature vercel.json key netlify.toml section
Build commands buildCommand, installCommand, outputDirectory [build]
Redirects redirects [[redirects]]
Rewrites (proxy-like) rewrites [[redirects]] with status = 200
Response headers headers [[headers]]
Function options functions (memory, duration, region) [functions] (bundler, included files)
Scheduled jobs crons function-level config.schedule
Ignore builds ignoreCommand ignore in [build]
Clean URLs cleanUrls, trailingSlash [build.processing] and pretty_urls options
Per-context overrides not in file (use environments/branches) [context.NAME]

Notice one difference: Netlify expresses redirects and rewrites with one rule type (the HTTP status code decides), while Vercel has separate arrays.

A fuller example of each

JSON
{
  "buildCommand": "npm run build",
  "outputDirectory": "dist",
  "redirects": [
    { "source": "/old-blog/:slug", "destination": "/blog/:slug", "permanent": true }
  ],
  "headers": [
    {
      "source": "/assets/(.*)",
      "headers": [
        { "key": "Cache-Control", "value": "public, max-age=31536000, immutable" }
      ]
    }
  ],
  "functions": {
    "api/report.js": { "maxDuration": 30 }
  }
}
TOML
[build]
  command = "npm run build"
  publish = "dist"

[[redirects]]
  from = "/old-blog/:slug"
  to = "/blog/:slug"
  status = 301

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

[functions]
  node_bundler = "esbuild"

In TOML, double brackets [[redirects]] mean "one more item in a list". Each [[redirects]] block is a separate rule, and rule order matters.

Context overrides on Netlify

netlify.toml can change settings for one kind of deploy:

TOML
[build]
  command = "npm run build"

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

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

[context.branch-deploy.environment]
  FEATURE_BETA = "on"

[context.staging]            # a specific branch name
  command = "npm run build:staging"

Contexts are production, deploy-preview, branch-deploy, dev (for the CLI), or a branch name. Specific beats general: a branch context overrides a deploy-type context, which overrides [build]. On Vercel you get the same effect with environment variables per environment and, if needed, a different buildCommand that reads VERCEL_ENV.

Node.js Merging context settings (stand-in)

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

Validate before pushing

Typos in config files either silently do nothing or fail the deploy. Two habits help:

  1. Keep JSON valid (no trailing commas, no comments in vercel.json) and TOML valid (strings quoted).
  2. Run the platform dev server (vercel dev, netlify dev) so redirects, headers and functions behave as in production.
Node.js vercel.json sanity check (stand-in)

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

Single source of truth

Decide once whether the file or the dashboard owns a setting. A good rule: structural settings (commands, output, headers, redirects, functions) in the file; secrets and per-environment values in the dashboard's environment variables; Node version in engines or the file so it is versioned.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. What does [[redirects]] (double brackets) mean in netlify.toml?

    Double brackets define an array of tables, so each block is a separate rule.
  2. 2. Which Netlify section changes settings only for pull request previews?

    deploy-preview is the context for pull request previews.
  3. 3. What is true about comments in vercel.json?

    vercel.json is JSON, which has no comment syntax.
  4. 4. Where should secret values live?

    Config files are committed to Git, so secrets belong in protected environment variables.

Summary

  • vercel.json and netlify.toml capture build commands, redirects, headers, function options and more in code.
  • Netlify's [context.*] blocks override settings per deploy type or branch; Vercel relies on per-environment variables.
  • Netlify uses one rule type for redirects and rewrites; Vercel has separate arrays.
  • Validate with the local dev server and keep secrets out of config files.

Next: Build Caching and Plugins