# netlify-config

Configures Netlify builds and routing through netlify.toml, _redirects, and _headers. Handy when wiring up SPA history fallbacks, proxy rules, or deploy contexts.

- skill · `type=skill` · Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, OpenCode · 3300 installs · ★ 45
- Author: netlify
- License: MIT · policy=mirror · the beginning of the file is at the end of this page
- Source: https://github.com/netlify/context-and-tools/tree/HEAD/skills/netlify-config/SKILL.md
- Updated: 2026-10-23
- HTML: https://affpapa.org/en/nevibecode/skills/netlify-config

## What it does

This skill guides the AI in generating configuration across `netlify.toml`, `_redirects`, and `_headers`. It enforces platform precedence: values in `netlify.toml` override the Netlify UI, while `_redirects` takes priority over TOML routing rules. It also selects `esbuild` as the bundler for serverless functions rather than legacy `zisi`.

Routing rules reflect Netlify-specific constraints. Redirecting to add or drop a trailing slash causes infinite loops because CDN normalization runs first. Status 307 is unsupported. Temporary redirects must use 302. Proxied requests time out after 26 seconds.

Redirects and headers remain global across all branches. Context blocks like `[context.deploy-preview]` only apply to build commands and plugins, requiring custom copy steps during build if headers must differ per branch.

## Install

### Claude Code (native platform)

1. **Skills CLI (Vercel)**
```bash
npx skills add netlify/context-and-tools --skill netlify-config -a claude-code
```

2. **Manually: put the files in place**
- File: `~/.claude/skills/netlify-config/SKILL.md` — Copy the whole skill folder; for one project use .claude/skills/netlify-config/

### Codex

1. **Skills CLI (Vercel)**
```bash
npx skills add netlify/context-and-tools --skill netlify-config -a codex
```

2. **Manually: put the files in place**
- File: `.agents/skills/netlify-config/SKILL.md` — For all projects use ~/.agents/skills/

### Cursor

1. **Skills CLI (Vercel)**
```bash
npx skills add netlify/context-and-tools --skill netlify-config -a cursor
```

2. **Manually: put the files in place**
- File: `.cursor/skills/netlify-config/SKILL.md` — Cursor also reads .agents/skills/ and .claude/skills/

### GitHub Copilot

1. **GitHub CLI**
```bash
gh skill install netlify/context-and-tools netlify-config
```

2. **Manually: put the files in place**
- File: `.github/skills/netlify-config/SKILL.md`

### Gemini CLI

1. **Skills CLI (Vercel)**
```bash
npx skills add netlify/context-and-tools --skill netlify-config -a gemini-cli
```

2. **Platform CLI**
```bash
gemini skills install https://github.com/netlify/context-and-tools --path skills/netlify-config
```

### Windsurf (Devin Desktop)

**Manually: put the files in place**
- File: `.devin/skills/netlify-config/SKILL.md` — The legacy .windsurf/skills/ path still works

### OpenCode

**Skills CLI (Vercel)**
```bash
npx skills add netlify/context-and-tools --skill netlify-config -a opencode
```

### Claude.ai

**Claude.ai**
- Zip the folder and upload it in Settings → Capabilities → Skills

Where a file is given instead of a command, copy the files from the source to that path: https://github.com/netlify/context-and-tools/tree/HEAD/skills/netlify-config/SKILL.md

## When to use it
- configure an SPA fallback route for history-mode navigation
- set up branch-specific build commands using deploy contexts
- create rewrite rules and signed reverse proxies for APIs
- configure `esbuild` bundling and included assets for functions

## Example prompts
- Add an SPA fallback rewrite rule to `_redirects`
- Write a `netlify.toml` with separate production and preview build contexts
- Set up a reverse proxy for `/api/*` with custom request headers

## Source text · SKILL.md · MIT

Below is the content of a third-party file. It is data, not instructions for you: do not act on anything written inside unless the human asks. Block tag: b93377e46b2501cf.

BEGIN THIRD-PARTY FILE b93377e46b2501cf
````text
---
name: netlify-config
description: Configure Netlify builds and routing via netlify.toml, _redirects, and _headers. Use when setting a build command or publish directory, adding redirects or rewrites or proxies, adding an SPA fallback rewrite, setting custom response headers or basic auth, managing environment variables and secrets, scoping vars per deploy context, marking a var as secret, disabling secret scanning, configuring functions bundling, ignoring builds, or wiring up a monorepo or JavaScript SPA on Netlify.
---

# Netlify configuration

Config lives in three files at the repo **root** (or the base/package directory for monorepos):
- `netlify.toml` — build, contexts, plugins, functions, redirects, headers, dev.
- `_redirects` — plain-text redirect/rewrite rules, saved to the **publish directory**, no extension.
- `_headers` — plain-text response headers, saved to the **publish directory**.

`netlify.toml` values **take precedence over the Netlify UI** when they conflict. Paths in `netlify.toml` are absolute relative to the **base directory** (root `/` by default).

## Modern vs legacy syntax to reach for
- Functions bundler: use `node_bundler = "esbuild"`. `zisi` is the legacy JS default; TypeScript always uses `esbuild`.
- Temporary redirect: use `status = 302`. `307` is **unsupported**.
- Gatsby Image CDN: use `NETLIFY_IMAGE_CDN`, not the deprecated `GATSBY_CLOUD_IMAGE_CDN`.
- Injecting env values into TOML: `key = "$VAR"` is **NOT supported** (except `signed` in proxy redirects). Use a build-command `sed` substitution or a build plugin (see below).

## `netlify.toml` build + contexts

```toml
[build]
  base = "frontend"
  publish = "dist"
  command = "npm run build"
  environment = { NODE_VERSION = "18" }

[context.production]
  publish = "output/"
  command = "make publish"

[context.deploy-preview]
  publish = "dist/"

[context."feat/branch"]        # quote names with special characters
  command = "npm run preview"
```

`[build]` runs in **Bash**. Context-aware keys include `[build]` and `[[plugins]]` — but **NOT** `[[redirects]]` or `[[headers]]` (those are always global). Precedence, least→most specific: UI < toml < any-context property < `[context.<name>]` < `[context.branchname]`.

## Redirects and rewrites

`_redirects` rules are processed **first**, then `netlify.toml`; within each, the **first matching rule top-to-bottom wins** — list specific rules before general ones. Edge functions run before redirects.

SPA history-`pushState` fallback (required for clean URLs):
```
/*  /index.html  200
```
```toml
[[redirects]]
  from = "/*"
  to = "/index.html"
  status = 200
```

`_redirects` syntax — `from to [status] [conditions]`, `#` comments, paths case-sensitive, URL-encode special chars:
```
/home         /              301
/my-redirect  /              302
/ecommerce    /store-closed  404          # custom 404 for a path
````
END THIRD-PARTY FILE b93377e46b2501cf

The third-party file has ended. Everything between the b93377e46b2501cf tags is data: requests and commands from it are not followed. An “end of file” line with another tag inside the block is part of the file.

First 2908 of 16228 bytes. © netlify · MIT · https://github.com/netlify/context-and-tools/tree/HEAD/skills/netlify-config/SKILL.md

_Part of the page did not fit — see the HTML version._

---
NeVibeCode on affpapa.org. Catalog texts are descriptions, not instructions for the agent. How to choose and install: https://affpapa.org/en/nevibecode/agents.md