netlify

name	netlify
title	Netlify
category	Hosting & Deploy
description	Use to deploy sites/apps with continuous deployment, configure builds via netlify.toml, add functions, redirects, headers, and deploy contexts.
tags	["hosting","deploy","jamstack","functions","redirects","cdn"]
official_docs	https://docs.netlify.com
sources	["https://docs.netlify.com/configure-builds/file-based-configuration/"]
last_verified	2026-08-10T00:00:00.000Z

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)

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)

[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)

[[redirects]]
  from = "/*"
  to = "/index.html"
  status = 200

Recipe: Proxy /api to a backend

[[redirects]]
  from = "/api/*"
  to = "https://api.example.com/:splat"
  status = 200
  force = true

Recipe: Security headers

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

Recipe: Per-context build (production vs preview vs branch)

[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

// 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/