ericrisco/rsc-harness / skills/netlify
netlify
VerifiedUse when deploying or operating a site on Netlify — writing or fixing netlify.toml, authoring Functions or Edge Functions, redirects, rewrites and headers, env vars per deploy context, and shipping via the Netlify CLI. NOT deploying to Vercel (that is `vercel`).
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 servesindex.htmlat the original URL so the client router can read the path; a 301 changes the URL and breaks deep links. - Proxy/rewrite =
status = 200to a remote URL (addforce = trueto override an existing file at that path). - Processing order: Edge Functions run first, then
_redirectsrules, thennetlify.tomlredirects; 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.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| writing-skillsobra/superpowersUse when creating new skills, editing existing skills, or verifying skills work before deployment | Stars: 319k | Updated | Claude CodeCodex | Verified | Install |
| xlsxanthropics/skillsUse this skill any time a spreadsheet file is the primary input or output. This means any task where the user wants to: open, read, edit, or fix an existing .xlsx, .xlsm, .xltx, .csv, or .tsv file (e.g., adding columns, computing formulas, formatting, charting, cleaning messy data); create a new spreadsheet from scratch or from other data sources; or convert between tabular file formats. Trigger especially when the user references a spreadsheet file by name or path — even casually (like "the xlsx in my downloads") — and wants something done to it or produced from it. Also trigger for cleaning or restructuring messy tabular data files (malformed rows, misplaced headers, junk data) into proper spreadsheets. The deliverable must be a spreadsheet file. Do NOT trigger when the primary deliverable is a Word document, HTML report, standalone Python script, database pipeline, or Google Sheets API integration, even if tabular data is involved. | Stars: 196k | Updated | Claude CodeCodex | Verified | Install |
| shipping-and-launchaddyosmani/agent-skillsPrepares production launches. Use when preparing to deploy to production, or when asking what needs to be in place before shipping. Use when you need a pre-launch checklist, when setting up monitoring, when planning a staged rollout, or when you need a rollback strategy. | Stars: 118k | Updated | Claude CodeCodex | Verified | Install |
| childhoodthedotmack/claude-memBabysit a shipped release after merge, publication, or deployment. Verify published packages, production behavior, installed plugins, and late CI or user reports until the observation window is clean; use babysit for PR readiness before release. | Stars: 118k | Updated | Claude CodeCodex | Verified | Install |