netlify

---
name: netlify
description: Use to deploy sites/apps with continuous deployment, configure builds via netlify.toml, add functions, redirects, headers, and deploy contexts.
license: MIT
---

# Netlify — Skillship

> Git-driven hosting for web apps and static sites with a global CDN, serverless functions, and
> per-branch deploy previews. Most config lives in a single `netlify.toml`.

## 🧭 When to use this skill
- Use when: deploying static sites or Jamstack/SSR apps with CI/CD from Git.
- Use when: you want redirects, custom headers, and preview deploys defined in-repo.
- Don't use for: always-on servers or heavy background jobs.

## ⚡ Quickstart

### 1. Install CLI (optional but handy)
```bash
npm i -g netlify-cli
netlify login
netlify init          # link repo + set build settings
netlify deploy         # draft deploy
netlify deploy --prod  # production deploy
```

### 2. Minimal `netlify.toml` (repo root)
```toml
[build]
  base = "."             # base directory (where package.json lives)
  command = "npm run build"
  publish = "dist"       # the deploy-ready output directory

[functions]
  directory = "netlify/functions"
```

## 🧩 Common recipes

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

### Recipe: Proxy /api to a backend
```toml
[[redirects]]
  from = "/api/*"
  to = "https://api.example.com/:splat"
  status = 200
  force = true
```

### Recipe: Security headers
```toml
[[headers]]
  for = "/*"
  [headers.values]
    X-Frame-Options = "DENY"
    Content-Security-Policy = "frame-ancestors 'none'"
```

### Recipe: Per-context build (production vs preview vs branch)
```toml
[context.production]
  command = "npm run build"
[context.deploy-preview]
  command = "npm run build:preview"
[context.branch-deploy.environment]
  NODE_ENV = "development"
```

### Recipe: A serverless function
```ts
// netlify/functions/hello.ts
export default async (req: Request) => {
  return new Response(JSON.stringify({ ok: true }), {
    headers: { "content-type": "application/json" },
  });
};
```

## 🚀 Ship to production
- [ ] Secrets set as **environment variables in the Netlify UI** (scoped, audited) — not in `netlify.toml`.
- [ ] `publish` points to the real build output; `command` builds successfully in CI.
- [ ] SPA fallback / redirects verified so deep links don't 404.
- [ ] Security headers configured for `/*`.
- [ ] Custom domain + HTTPS configured; deploy previews reviewed before merge.
- [ ] Remember: `netlify.toml` settings **override** UI settings when both exist.

## 🔐 Security & secrets
- Don't store secrets in `netlify.toml` (it's committed). Use UI/CLI/API env vars, and include the **Builds** scope if you need them at build time.
- Env var interpolation like `key = "$VAR"` is NOT supported in `netlify.toml` (except signed proxy redirects).
- `redirects`/`headers` in `netlify.toml` are global; use `_headers`/`_redirects` files for per-deploy rules.

## 🐛 Common errors & fixes
| Symptom | Likely cause | Fix |
|---|---|---|
| Deep links 404 on a SPA | No fallback redirect | Add `/* -> /index.html 200` |
| Site shows old build | Wrong `publish` dir | Point `publish` at the actual output folder |
| Secret missing at build | Var lacks Builds scope | Set the env var with Builds scope in the UI |
| UI setting ignored | `netlify.toml` overrides it | Change the value in `netlify.toml` |
| Function not found | Wrong functions `directory` | Match `[functions] directory` to your folder |

## 📚 Sources
- https://docs.netlify.com/configure-builds/file-based-configuration/