Agent skill · practicalswan
netlify-config
Configure Netlify projects via netlify.toml and the _headers/_redirects files — covering build settings and deploy contexts alongside environment variables/scopes and the Secrets Controller plus redirect/rewrite/proxy and custom-header rules. Use when setting a build command or publish directory, adding redirect or rewrite or proxy rules, configuring custom headers or basic auth, setting or scoping environment variables and secrets, wiring up a monorepo or SPA fallback, or skipping unnecessary builds. Reach for this whenever you touch netlify.toml or ask \"why is my env var undefined in a function\" or \"how do I redirect this path\".
What it needs
About 10k tokens when loaded.
What this skill does
Netlify configuration netlify.toml lives at the repo root (or set base/package directory for monorepos). Settings in netlify.toml override the Netlify UI on conflict. headers and redirects are extensionless plain-text files in the publish directory, processed before netlify.toml rules. Footguns (read first) Env vars in netlify.toml are NOT available to functions or edge functions at runtime — reading them there returns undefined. Vars declared in netlify.toml only get the Builds and Post processing scopes. Set runtime vars in the UI or with netlify env:set. Never put secrets in client-prefixed vars (VITE, NEXTPUBLIC, PUBLIC, …) — they are inlined into the client bundle. --secret does not protect them. .env is not read by the Netlify build system — import variables into Netlify first (netlify env:import). The CLI reads .env only for local builds. Direct env injection into netlify.toml (key = "$VAR") is unsupported — except signed proxy redirects. Use a build plugin or sed in the build command. [[redirects]] and [[headers]] are global — NOT context-aware, cannot be scoped to branches/contexts. Workaround: per-context build command copies a custom file into the publish directory. Proxy rewrites time out at 26 seconds. HTTP 307 is unsupported — use 302. netlify.toml — core structure Context precedence (least → most specific): UI settings < base context-aware key < [context.production deploy-preview branch-deploy dev] < [context.branchname]. Only [build] and [[plugins]] are context-aware. All paths are absolute relative to the base directory (root / default). Config file search order: package directory → base directory → root. Functions config esbuild = smaller/faster artifacts; TypeScript functions always use esbuild. externalnodemodules applies only with esbuild. includedfiles: wildcard, ! excludes; paths absolute to base. Environment variables Set runtime/scoped vars via CLI/UI/API (not netlify.toml): Keep any .env snapshot gitignored — never commit it. …
How to use it
Reference it in AdaL, Claude Code, Cursor or any coding agent — nothing to install:
@skills practicalswan/netlify-config