Netlify — netlify.toml, Functions, Edge Functions, redirects & the CLI

The platform-mechanics layer for Netlify: config, function handlers, routing, env contexts, and the deploy CLI. Not framework code, not generic CI.

What this owns

You own the Netlify adapter/config surface — netlify.toml, netlify/functions/, netlify/edge-functions/, _redirects, _headers, and netlify <cmd>. You do not own the app's routing or data layer (that is ../nextjs/SKILL.md / a React skill), DNS records (../domains-dns/SKILL.md), or another platform's config — Vercel is ../vercel/SKILL.md, Cloudflare is ../cloudflare/SKILL.md. Their config files and function models differ; never cross-apply.

The 5-minute happy path

netlify link                 # link the cwd to a site (or `netlify init` to create one)
# write/edit netlify.toml (see skeleton below)
netlify dev                  # local emulation: build, functions, redirects, env injection
netlify deploy --prod        # build + push straight to production

netlify deploy with no flag creates a draft deploy (preview URL, not live). --prod publishes. Test with netlify dev first — it is the only local runtime that emulates redirects and function routing together.

Where does each piece of config live?

Two rules decide everything below: _redirects/_headers files are processed before the netlify.toml equivalents, and a function's own config export beats dashboard guesses.

Concern	Put it in	Why
Redirects / rewrites / SPA fallback	[[redirects]] in toml or _redirects file	One source. File rules run first; pick one and stay consistent.
Response headers (CSP, caching)	[[headers]] in toml or _headers file	Same precedence; keep security headers in version control, not the UI.
Build command / publish dir / functions dir	[build] in toml	Single declarative source the build picks up; survives UI drift.
A function's URL path	export const config = { path } in the function	Co-located with the handler; deterministic, no dashboard mapping.
Edge function path + ordering	[[edge_functions]] in toml	Declaration order in toml is deterministic (inline config is not).
Secrets / API keys / per-context vars	dashboard or netlify env:set	Never commit secrets — build-time secrets scanning fails the build if it finds one.

netlify.toml skeleton

[build]
  command  = "npm run build"
  publish  = "dist"            # the directory you deploy; relative to base
  functions = "netlify/functions"
  [build.environment]
    NODE_VERSION = "22"

[functions]
  node_bundler = "esbuild"
  # included_files = ["data/**"]   # bundle extra files a function reads at runtime

# SPA fallback — note status 200, NOT 301 (see Redirects)
[[redirects]]
  from   = "/*"
  to     = "/index.html"
  status = 200

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

# per-context override: deploy previews build differently
[context.deploy-preview]
  command = "npm run build:preview"
  [context.deploy-preview.environment]
    SHOW_PREVIEW_BANNER = "true"

Contexts are production, deploy-preview, branch-deploy, and branch."name". Each can override command, publish, environment, etc. The full key-by-key reference (every [build]/[functions]/[[plugins]] option, all header/redirect fields) lives in references/netlify-toml.md — link there instead of inlining it.

Functions (Node runtime)

Default directory is netlify/functions/. TypeScript files are .mts, JS is .mjs (ES modules). Use the modern Web-platform handler — Request in, Response out — and route with a config export, not a dashboard mapping.

// netlify/functions/hello.mts
import type { Config, Context } from "@netlify/functions";

export default async (req: Request, context: Context) => {
  const name = new URL(req.url).searchParams.get("name") ?? "world";
  return Response.json({ hello: name });
};

export const config: Config = { path: "/api/hello" };

Read secrets from the environment; never hardcode them:

const key = Netlify.env.get("RESEND_API_KEY") ?? process.env.RESEND_API_KEY;

Do not revive the legacy AWS-Lambda signature in new functions:

// Bad — legacy handler/event/statusCode shape
exports.handler = async (event) => ({ statusCode: 200, body: "ok" });

// Good — Web-API handler + Config.path
export default async (req: Request) => new Response("ok");
export const config: Config = { path: "/ok" };

Scheduled (config.schedule cron), background (-background suffix), and streaming responses are covered in references/functions.md.

Edge Functions (Deno runtime)

Live in netlify/edge-functions/, run on Deno at the edge. Declare them in toml so ordering is explicit:

[[edge_functions]]
  function = "geo-rewrite"
  path     = "/*"
  # excludedPath = "/assets/*"

When multiple edge functions match one path, they run top-to-bottom in declaration order — declaring in netlify.toml is deterministic; relying on each function's inline config for ordering is not. Pick edge functions for latency-sensitive rewrites, geolocation, and A/B routing. Avoid them for heavy npm dependencies or Node-only APIs — use a regular Function there.

Redirects & rewrites

# _redirects (or the [[redirects]] equivalent)
/api/*   https://api.example.com/:splat   200   # proxy/rewrite: keep the URL, fetch remote
/old/*   /new/:splat                       301   # permanent redirect (default status)
/*       /index.html                        200   # SPA fallback

Three things people get wrong:

• SPA fallback must be status = 200, not 301. 200 serves index.html at the original URL so the client router can read the path; a 301 changes the URL and breaks deep links.
• Proxy/rewrite = status = 200 to a remote URL (add force = true to override an existing file at that path).
• Processing order: Edge Functions run first, then _redirects rules, then netlify.toml redirects; within the set the first matching rule wins (top-to-bottom). Put specific rules above the /* catch-all.

Env vars & deploy contexts

netlify env:set RESEND_API_KEY "xxxx" --context production
netlify env:set SHOW_BANNER "true" --context deploy-preview
netlify env:list --context deploy-preview
netlify env:import .env            # bulk import (do not commit .env)

Variables are scoped to deploy contexts, so a key can differ between production and previews. Build-time secrets scanning inspects build output; if a value you marked secret leaks into the bundle, the build fails — fix the leak, don't disable the scan blindly.

Deploy & local dev

Command	Use it for
netlify dev	Local: build + functions + redirects + env injection. The truth before deploy.
netlify deploy	Draft deploy → preview URL, not live.
netlify deploy --prod	Build + publish to production.
netlify deploy --prod --no-build	Publish an already-built dir; skips the build command.
netlify deploy --skip-functions-cache	Force re-bundle functions when a stale cache bites.

--no-build is the classic foot-gun: if you didn't actually build (or built into the wrong publish dir), you ship a stale or empty site. Only use it when the artifact is fresh.

Anti-patterns

Anti-pattern	Why it breaks	Do instead
SPA fallback as status = 301	URL rewrites; deep-link refresh 404s or loops	status = 200 to /index.html
Hardcoding API keys in a function	Leaks in bundle; secrets scan fails the build	Netlify.env.get(...) / process.env, set via netlify env:set
Legacy exports.handler = (event) => ({statusCode})	Old Lambda shape, mismatched runtime expectations	Web-API export default (req) => Response + config.path
Relying on inline edge config for run order	Ordering is non-deterministic across functions	Declare order in [[edge_functions]] in toml
netlify deploy --prod --no-build without building	Ships stale/empty publish dir	Build first, or drop --no-build
Pasting Vercel/Cloudflare config into Netlify	Different files & function models; nothing wires up	Use netlify.toml + netlify/functions; see ../vercel/SKILL.md for Vercel
functions dir in toml ≠ actual folder on disk	Functions silently not bundled → 404	Make [build].functions match netlify/functions/ exactly
/* redirect above a specific rule	Catch-all wins first; specific rule never matches	Order specific rules before the /* fallback

Verify

Run scripts/verify.sh [target-dir] (default cwd). It confirms a netlify.toml exists, parses, that any SPA fallback is status = 200, and that every [[redirects]] has both from and to. Read-only; exits 0 on a clean or empty target.