Update to Netlify
Snapshot Nov 19, 2026 · 00:11 UTC · version 1.9.0
Collection source: downloaded plugin package.
Instructions updated for netlify-config
Full description — Now says: validating netlify.toml against its JSON schema, adding redirects/rewrites/proxies or an SPA fallback rewrite, or setting custom response headers or basic...
Observed in instructions or declared skills. Runtime behavior has not been tested.
Up to 3 plugins free · no card required.
All fields and original values.
Full description
Oct 7, 2026 · 00:02 UTC
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,
Nov 19, 2026 · 00:11 UTC
validating netlify.toml against its JSON schema, adding redirects/rewrites/proxies or an SPA fallback rewrite, or setting custom response headers or basic auth. Also use when managing environment variables and secrets, scoping vars per d...
Skill instructions
Oct 7, 2026 · 00:02 UTC
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 secre...
Nov 19, 2026 · 00:11 UTC
validating netlify.toml against its JSON schema, adding redirects/rewrites/proxies or an SPA fallback rewrite, or setting custom response headers or basic auth. Also use when managing environment variables and secrets, scoping vars per d...
Compare saved observations
Download comparison JSONSKILL.md text changes
− removed · + added
--- before +++ after @@ -1,19 +1,20 @@ --- 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. +description: Configure Netlify builds and routing via netlify.toml, _redirects, and _headers. Use when setting a build command or publish directory, validating netlify.toml against its JSON schema, adding redirects/rewrites/proxies or an SPA fallback rewrite, or setting custom response headers or basic auth. Also use when managing environment variables and secrets, scoping vars per deploy context, marking a var as secret or 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`: 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`. +- Schema: start `netlify.toml` with `"$schema" = "https://open-api.netlify.com/netlify.schema.json"` (key is quoted). Editors and agents with TOML JSON-schema support suggest and validate properties. In VS Code, use the Even Better TOML extension. Netlify ignores the key at build/deploy. **A schema-valid file can still fail to build**, because checks like whether a directory exists happen only during the build. +- 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). @@ -21,6 +22,8 @@ ## `netlify.toml` build + contexts ```toml +"$schema" = "https://open-api.netlify.com/netlify.schema.json" + [build] base = "frontend" publish = "dist" @@ -38,11 +41,11 @@ 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]`. +`[build]` runs in **Bash**. Context-aware keys include `[build]` and `[[plugins]]`. They do **NOT** include `[[redirects]]` or `[[headers]]`, which 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. +`_redirects` rules are processed **first**, then `netlify.toml`. Within each, the **first matching rule top-to-bottom wins**, so list specific rules before general ones. Edge functions run before redirects. SPA history-`pushState` fallback (required for clean URLs): ``` @@ -55,7 +58,7 @@ status = 200 ``` -`_redirects` syntax — `from to [status] [conditions]`, `#` comments, paths case-sensitive, URL-encode special chars: +`_redirects` syntax is `from to [status] [conditions]`. Lines starting with `#` are comments, paths are case-sensitive, and special chars must be URL-encoded: ``` /home / 301 /my-redirect / 302 @@ -70,15 +73,22 @@ /* /legacy/:splat 200 Cookie=is_legacy,my_other_cookie ``` -`[[redirects]]` keywords: `from`, `to`, `status` (default `301`), `force` (default `false`; `!`/shadow), `query` (`query = {path = ":path"}`), `conditions` (`{Language, Country, Role, Cookie}`), `headers` (proxy request headers), `signed` (env var name for signed proxies). +`[[redirects]]` keywords: +- `from`, `to` +- `status` (default `301`) +- `force` (default `false`; same as `!`/shadow) +- `query` (`query = {path = ":path"}`) +- `conditions` (`{Language, Country, Role, Cookie}`) +- `headers` (proxy request headers) +- `signed` (env var name for signed proxies) **Gotchas:** -- You **cannot** add/remove a trailing slash with a redirect — CDN normalizes URLs first; a `/x/ → /x 301!` rule loops infinitely. Rely on Pretty URLs (default on). -- Splat asterisks work only at the **end** of a segment (`/jobs/*`), not mid-path (`/jobs/*.html` invalid). Placeholders (`:x`) only at the start of a segment; can't mix wildcard+placeholder in one segment. -- You can't exclude a path from a splat; put a more specific rule first. -- `Country` = ISO 3166-1 alpha-2; language redirects match only the **first** `Accept-Language` entry. +- You **cannot** add or remove a trailing slash with a redirect. The CDN normalizes URLs first, so a `/x/ → /x 301!` rule loops infinitely. Rely on Pretty URLs (default on). +- Splat asterisks work only at the **end** of a segment (`/jobs/*`), not mid-path (`/jobs/*.html` is invalid). Placeholders (`:x`) work only at the start of a segment. You can't mix a wildcard and a placeholder in one segment. +- You can't exclude a path from a splat. Put a more specific rule first instead. +- `Country` takes ISO 3166-1 alpha-2 codes. Language redirects match only the **first** `Accept-Language` entry. - Role-based redirects with external auth providers are **Enterprise-only**. -- 10,000+ redirects: use wildcards/placeholders or Edge Functions — oversized serialized output fails the deploy. +- For 10,000+ redirects, use wildcards/placeholders or Edge Functions. Oversized serialized output fails the deploy. ## Proxies @@ -94,7 +104,11 @@ force = true headers = {X-From = "Netlify"} ``` -Signed proxy (`signed` names an env var scoped to **Runtime**; must live in `netlify.toml`; JWS is external-only, not Netlify→Netlify): +Signed proxy rules: +- `signed` names an env var scoped to **Runtime**. +- The rule must live in `netlify.toml`. +- JWS signing works for external targets only, not Netlify→Netlify. + ```toml [[redirects]] from = "/search" @@ -104,7 +118,13 @@ signed = "API_SIGNATURE_TOKEN_PLACEHOLDER" ``` -**Gotchas:** cross-team rewrites disallowed; same-password-site rewrites OK but not across separate protected sites; proxy timeout **26 s**; one hop by default; relative-path assets break (use absolute or `<base>`); loops silently ignored. +**Gotchas:** +- Cross-team rewrites are disallowed. +- Rewrites within the same password-protected site are OK, but not across separate protected sites. +- Proxy timeout is **26 s**. +- Only one hop by default. +- Assets with relative paths break; use absolute paths or `<base>`. +- Looping rules are silently ignored. ## Custom headers @@ -114,7 +134,7 @@ /templates/index2.html X-Frame-Options: SAMEORIGIN ``` -Multi-value — repeat the key (`_headers`) or a multiline TOML string: +For multi-value headers, repeat the key (`_headers`) or use a multiline TOML string: ```toml [[headers]] for = "/*" @@ -127,14 +147,15 @@ ``` **Gotchas:** -- Headers in `_headers`/`netlify.toml` are **global** — NOT scoped to branch/context. Workaround: strip global headers, keep header files in a custom dir, and `cp` them into the publish dir from a per-context build command: +- Headers in `_headers`/`netlify.toml` are **global**, NOT scoped to branch/context. Workaround: remove global headers, keep header files in a custom dir, and `cp` them into the publish dir from a per-context build command: ```toml [context.staging] command = "npm run build && cp ./custom-headers/_stagingHeaders ./dist/_headers" ``` -- Headers apply only to files from Netlify's store — **NOT** to proxied content or function/edge (SSR) responses; those must set their own headers. -- Ignored (server-set) names include `Content-Length`, `Content-Encoding`, `Location` (use redirects), `Set-Cookie`, `Server`, etc. -- Basic auth headers: **Pro/Enterprise only**. Cross-subdomain cookies need a custom domain (`netlify.app` is on the Public Suffix List). +- Headers apply only to files from Netlify's store. They do **NOT** apply to proxied content or function/edge (SSR) responses, which must set their own headers. +- Server-set names are ignored, including `Content-Length`, `Content-Encoding`, `Location` (use redirects), `Set-Cookie`, and `Server`. +- Basic auth headers are **Pro/Enterprise only**. +- Cross-subdomain cookies need a custom domain, because `netlify.app` is on the Public Suffix List. ## Functions @@ -153,8 +174,14 @@ ## Environment variables Two storage methods: -- **UI / CLI / API** — stored on Netlify (not the repo). Supports site + shared vars, per-context values, scopes; reaches builds, functions/edge/ODB, snippet injection, forms, signed proxies. **Recommended for anything sensitive.** -- **`netlify.toml`** — stored in the repo. Site vars only, per-context values, **no scope selection** (everything gets **Builds** + **Post processing**), reaches builds + snippet injection only. +- **UI / CLI / API**: stored on Netlify, not in the repo. + - Supports site + shared vars, per-context values, and scopes. + - Reaches builds, functions/edge/ODB, snippet injection, forms, and signed proxies. + - **Recommended for anything sensitive.** +- **`netlify.toml`**: stored in the repo. + - Site vars only, with per-context values. + - **No scope selection**: everything gets **Builds** + **Post processing**. + - Reaches builds and snippet injection only. `netlify.toml` env vars **override** same-key UI/CLI/API vars. @@ -180,53 +207,68 @@ **Access syntax:** Bash `$VAR` in `build.command`/`ignore.command`; `process.env.VAR` in Node scripts and plugins. -**Scopes** (Pro/Enterprise; default all): Builds (site builds) · Functions (Functions/Edge/ODB) · Runtime (forms, signed proxies) · Post processing (snippet injection). Shared vars are Pro/Enterprise and **Team-Owner-only** to read/edit. Precedence for a site+shared key collision resolves **per scope** — a site var only wins within the scopes it actually carries. +**Scopes** (Pro/Enterprise; default is all scopes): +- Builds: site builds. +- Functions: Functions, Edge Functions, ODB. +- Runtime: forms, signed proxies. +- Post processing: snippet injection. -**Naming/limits:** keys alphanumeric + underscore, must start with a letter (`1KEY`, `_KEY1` invalid); keys ≤255 chars, values ≤5,000 chars. Read-only variable names are reserved. Changes need a build + deploy. +Shared vars are Pro/Enterprise and **Team-Owner-only** to read/edit. When a site var and a shared var use the same key, precedence resolves **per scope**: the site var only wins within the scopes it actually carries. -**Set the build language via reserved config vars** — `NODE_VERSION`, `NPM_FLAGS`, `YARN_VERSION`, `BUN_VERSION`, `RUBY_VERSION`, `PHP_VERSION`, `PYTHON_VERSION`, `GO_VERSION`, `HUGO_VERSION`, `PNPM_FLAGS`, `NPM_TOKEN` (Yarn: `YARN_NPM_AUTH_TOKEN`), etc. +**Naming/limits:** +- Keys use only alphanumerics and underscores, and must start with a letter (`1KEY` and `_KEY1` are invalid). +- Keys ≤255 chars, values ≤5,000 chars. +- Read-only variable names are reserved. +- Changes need a build + deploy. -**Must be set in UI/CLI/API, NOT `netlify.toml`** (read after the repo is cloned or a runtime-only var): `AWS_LAMBDA_JS_RUNTIME`, `GIT_LFS_ENABLED`, `GIT_LFS_FETCH_INCLUDE`, `NETLIFY_BUILD_DEBUG`. +**Set the build language via reserved config vars**: `NODE_VERSION`, `NPM_FLAGS`, `YARN_VERSION`, `BUN_VERSION`, `RUBY_VERSION`, `PHP_VERSION`, `PYTHON_VERSION`, `GO_VERSION`, `HUGO_VERSION`, `PNPM_FLAGS`, `NPM_TOKEN` (Yarn: `YARN_NPM_AUTH_TOKEN`), etc. -**`CI` gotcha:** defaults to `true`; if it breaks a build, prepend `CI='' ` to the build command. +**Must be set in UI/CLI/API, NOT `netlify.toml`**, because they are read before `netlify.toml` (after the repo is cloned) or are runtime-only: `AWS_LAMBDA_JS_RUNTIME`, `GIT_LFS_ENABLED`, `GIT_LFS_FETCH_INCLUDE`, `NETLIFY_BUILD_DEBUG`. + +**`CI` gotcha:** `CI` defaults to `true`. If it breaks a build, prepend `CI='' ` to the build command. ### Injecting env values into headers/redirects -`key = "$VAR"` is unsupported. Only path (scope must include **Builds**): +`key = "$VAR"` is unsupported. For headers and redirects, substitute values from the build command (the var's scope must include **Builds**): ```toml [build] command = "sed -i \"s|HEADER_PLACEHOLDER|${PROD_API_LOCATION}|g\" netlify.toml && yarn build" ``` -`sed` substitution works **only** for `[[headers]]`/`[[redirects]]` (read after the build) and is **not** visible to build plugins (they run before the build command). For plugin-visible changes, use a local build plugin editing `netlifyConfig`. +`sed` substitution works **only** for `[[headers]]`/`[[redirects]]`, which are read after the build. It is **not** visible to build plugins, which run before the build command. For changes plugins must see, use a local build plugin that edits `netlifyConfig`. ### Useful read-only build vars `CONTEXT` (`production`/`deploy-preview`/`branch-deploy`/`dev`), `BRANCH`, `COMMIT_REF`, `CACHED_COMMIT_REF`, `PULL_REQUEST`, `REVIEW_ID`, `URL`, `DEPLOY_URL`, `DEPLOY_PRIME_URL`, `SITE_ID`, `SITE_NAME`. ## Secrets Controller -Flag a var as secret: `Contains secret values` (UI) / `--secret` (CLI) / `is_secret: true` (API). Enforced, non-customizable policy: -- Secret values are **write-only** — no readable version after set; the flag can't be removed to reveal it. -- Secrets need explicit contexts + scopes; **cannot** carry the `post processing` scope. -- Only code on Netlify (edge/serverless/build) reads unmasked values; off-Netlify sees masked. The `dev`-context value is exempt (unmasked from UI/CLI/API); `netlify build` never emits raw values. - -**Secret scanning** runs automatically once any var is secret (and via smart detection). Fails the build on detection and logs the location. Configure via env vars set per context: -- `SECRETS_SCAN_ENABLED=false` — disables **all** scanning (loses all secret protection). -- `SECRETS_SCAN_SMART_DETECTION_ENABLED=false` — disables smart detection only. -- `SECRETS_SCAN_OMIT_KEYS`, `SECRETS_SCAN_OMIT_PATHS` (comma lists; paths from repo root, globs OK). -- `SECRETS_SCAN_SMART_DETECTION_OMIT_VALUES` — safelist false positives (**prefer** this over disabling). Smart detection is Personal/Pro/Enterprise. +Flag a var as secret with `Contains secret values` (UI), `--secret` (CLI), or `is_secret: true` (API). The policy is enforced and can't be customized: +- Secret values are **write-only**: there is no readable version after setting, and the flag can't be removed to reveal the value. +- Secrets need explicit contexts + scopes and **cannot** carry the `post processing` scope. +- Only code on Netlify (edge/serverless/build) reads unmasked values. Code off Netlify sees masked values. +- The `dev`-context value is exempt and stays unmasked from UI/CLI/API. `netlify build` never emits raw values. + +**Secret scanning** runs automatically once any var is secret, and also through smart detection. It fails the build on detection and logs the location. Configure it with env vars set per context: +- `SECRETS_SCAN_ENABLED=false` disables **all** scanning, which removes all secret protection. +- `SECRETS_SCAN_SMART_DETECTION_ENABLED=false` disables smart detection only. +- `SECRETS_SCAN_OMIT_KEYS` and `SECRETS_SCAN_OMIT_PATHS` take comma lists. Paths are relative to the repo root; globs are OK. +- `SECRETS_SCAN_SMART_DETECTION_OMIT_VALUES` safelists false positives. **Prefer** this over disabling. +- Smart detection is available on Personal/Pro/Enterprise. -Scanning covers all build files, values >4 chars and non-boolean, searching plaintext + base64 + URI-encoded permutations. +Scanning covers all build files. It checks secret values longer than 4 chars that aren't booleans, searching plaintext, base64, and URI-encoded permutations. ### Sensitive variable policy (public repos only) -Governs whether **untrusted** deploys (unrecognized authors) get sensitive vars. Site members' Git deploys are always trusted, even from forks. Set at Project configuration > Environment variables > Site policies: -- **Require approval** (default) — untrusted deploys wait for a member's approval. -- **Deploy without sensitive variables** — builds run, sensitive vars withheld. -- **Deploy without restrictions** — all vars present. +This policy governs whether **untrusted** deploys (from unrecognized authors) get sensitive vars. Site members' Git deploys are always trusted, even from forks. Set it at Project configuration > Environment variables > Site policies: +- **Require approval** (default): untrusted deploys wait for a member's approval. +- **Deploy without sensitive variables**: builds run, but sensitive vars are withheld. +- **Deploy without restrictions**: all vars are present. -NOT available for GitHub Enterprise Server / GitLab self-managed repos (treated as private). +The policy is NOT available for GitHub Enterprise Server or GitLab self-managed repos, which are treated as private. ## Ignore builds -`ignore` under `[build]` decides whether to rebuild — runs from the base directory in Bash (or Node.js 18, fixed; site `package.json` deps **not** available). **Exit `1` = changed → build continues; exit `0` = no change → build stops.** A build hook always builds regardless of exit code. +`ignore` under `[build]` decides whether to rebuild. It runs from the base directory in Bash, or in Node.js 18 (fixed version; site `package.json` deps are **not** available). +- **Exit `1` = changed → build continues.** +- **Exit `0` = no change → build stops.** +- A build hook always builds, regardless of exit code. ```toml [build] ignore = "git diff --quiet $CACHED_COMMIT_REF $COMMIT_REF packages/blog-1 packages/common" @@ -242,15 +284,25 @@ ## Monorepos -Set the site subdirectory as the **package directory** (keep its `netlify.toml` there), leave base at root `/`, declare deps at the subdirectory level. Package directory is **UI-only — cannot be set in `netlify.toml`** (Project configuration > Developer settings > Continuous deployment > Build settings). Config file discovery order: package dir → base dir → root. Paths in `netlify.toml` stay absolute relative to the base directory. `netlify <cmd> --filter <site>` selects a site. +Recommended setup: +1. Set the site subdirectory as the **package directory** and keep its `netlify.toml` there. +2. Leave the base directory at root `/`. +3. Declare deps at the subdirectory level. + +The package directory is **UI-only and cannot be set in `netlify.toml`**. Set it at Project configuration > Developer settings > Continuous deployment > Build settings. + +Config files are discovered in this order: package dir → base dir → root. Paths in `netlify.toml` stay absolute relative to the base directory. Use `netlify <cmd> --filter <site>` to select a site. ## JavaScript SPAs -Build command `npm run <script>` / `yarn <script>`; publish dir often `dist` (framework-dependent). Add the `/* /index.html 200` fallback (above) for `pushState` routing. Code splitting + hashed filenames with atomic deploys can throw `Uncaught SyntaxError: Unexpected token` on stale references — disable hashed filenames, use permalinks, or a service worker. +- Build command: `npm run <script>` or `yarn <script>`. +- Publish dir: often `dist`, depending on the framework. +- Add the `/* /index.html 200` fallback (above) for `pushState` routing. +- Code splitting + hashed filenames with atomic deploys can throw `Uncaught SyntaxError: Unexpected token` on stale references. Fix by disabling hashed filenames, using permalinks, or using a service worker. ## Netlify Dev `[dev]` -Does **NOT** run in Bash (no Bash syntax in `command`). There is **no `environment` key** — set local env vars under `[context.dev.environment]`. +`[dev]` does **NOT** run in Bash, so don't use Bash syntax in `command`. There is **no `environment` key**; set local env vars under `[context.dev.environment]`. ```toml [dev] command = "yarn start" @@ -276,7 +328,15 @@ output_path = "reports/performance-reports.html" ``` -Full reference pages: build environment variables at https://docs.netlify.com/build/configure-builds/environment-variables.md, env-var overview at https://docs.netlify.com/build/environment-variables/overview.md, Secrets Controller at https://docs.netlify.com/build/environment-variables/secrets-controller.md, redirects at https://docs.netlify.com/manage/routing/redirects/overview.md, redirect options at https://docs.netlify.com/manage/routing/redirects/redirect-options.md, rewrites/proxies at https://docs.netlify.com/manage/routing/redirects/rewrites-proxies.md, custom headers at https://docs.netlify.com/manage/routing/headers.md, and file-based config at https://docs.netlify.com/build/configure-builds/file-based-configuration.md. +## Reference pages +- Build environment variables: https://docs.netlify.com/build/configure-builds/environment-variables.md +- Env-var overview: https://docs.netlify.com/build/environment-variables/overview.md +- Secrets Controller: https://docs.netlify.com/build/environment-variables/secrets-controller.md +- Redirects: https://docs.netlify.com/manage/routing/redirects/overview.md +- Redirect options: https://docs.netlify.com/manage/routing/redirects/redirect-options.md +- Rewrites/proxies: https://docs.netlify.com/manage/routing/redirects/rewrites-proxies.md +- Custom headers: https://docs.netlify.com/manage/routing/headers.md +- File-based config: https://docs.netlify.com/build/configure-builds/file-based-configuration.md <!-- Plan gating for the sensitive variable policy itself is unspecified in the sources; only its public-repo requirement and the smart-detection plan list are documented. --> @@ -298,3 +358,9 @@ Builds does not shadow the shared variable for other scopes — precedence resolves independently per scope (site beats shared only within the scopes the site variable actually carries). +5. When creating or editing `netlify.toml`, add + `"$schema" = "https://open-api.netlify.com/netlify.schema.json"` as its + first line if it's missing, and check property names and value types + against that schema instead of guessing. The schema doesn't describe the + contents of `[dev]`, `[template]`, `[[integrations]]` or + `[build.processing]`; use the docs for those.
Full technical diff · 2 changed fields
changed /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."
"Configure Netlify builds and routing via netlify.toml, _redirects, and _headers. Use when setting a build command or publish directory, validating netlify.toml against its JSON schema, adding redirects/rewrites/proxies or an SPA fallback rewrite, or setting custom response headers or basic auth. Also use when managing environment variables and secrets, scoping vars per deploy context, marking a var as secret or disabling secret scanning, configuring functions bundling, ignoring builds, or wiring up a monorepo or JavaScript SPA on Netlify."
changed /skill_md_contents
"---\nname: netlify-config\ndescription: 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.\n---\n\n# Netlify configuration\n\nConfig lives in three files at the repo **root** (or the base/package directory for monorepos):\n- `netlify.toml` — build, contexts, plugins, functions, redirects, headers, dev.\n- `_redirects` — plain-text redirect/rewrite rules, saved to the **publish directory**, no extension.\n- `_headers` — plain-text response headers, saved to the **publish directory**.\n\n`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).\n\n## Modern vs legacy syntax to reach for\n- Functions bundler: use `node_bundler = \"esbuild\"`. `zisi` is the legacy JS default; TypeScript always uses `esbuild`.\n- Temporary redirect: use `status = 302`. `307` is **unsupported**.\n- Gatsby Image CDN: use `NETLIFY_IMAGE_CDN`, not the deprecated `GATSBY_CLOUD_IMAGE_CDN`.\n- 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).\n\n## `netlify.toml` build + contexts\n\n```toml\n[build]\n base = \"frontend\"\n publish = \"dist\"\n command = \"npm run build\"\n environment = { NODE_VERSION = \"18\" }\n\n[context.production]\n publish = \"output/\"\n command = \"make publish\"\n\n[context.deploy-preview]\n publish = \"dist/\"\n\n[context.\"feat/branch\"] # quote names with special characters\n command = \"npm run preview\"\n```\n\n`[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]`.\n\n## Redirects and rewrites\n\n`_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.\n\nSPA history-`pushState` fallback (required for clean URLs):\n```\n/* /index.html 200\n```\n```toml\n[[redirects]]\n from = \"/*\"\n to = \"/index.html\"\n status = 200\n```\n\n`_redirects` syntax — `from to [status] [conditions]`, `#` comments, paths case-sensitive, URL-encode special chars:\n```\n/home / 301\n/my-redirect / 302\n/ecommerce /store-closed 404 # custom 404 for a path\n/pass-through /index.html 200 # rewrite\n/best-pets/dogs /best-pets/cats.html 200! # force/shadow (! or force=true)\n/news/* /blog/:splat # splat\n/news/:month/:date/:year/:slug /blog/:year/:month/:date/:slug # placeholders\n/store id=:id /blog/:id 301 # query params\n/ /anz 302 Country=au,nz # no spaces in value list\n/israel/* /israel/he/:splat 302 Language=he\n/* /legacy/:splat 200 Cookie=is_legacy,my_other_cookie\n```\n\n`[[redirects]]` keywords: `from`, `to`, `status` (default `301`), `force` (default `false`; `!`/shadow), `query` (`query = {path = \":path\"}`), `conditions` (`{Language, Country, Role, Cookie}`), `headers` (proxy request headers), `signed` (env var name for signed proxies).\n\n**Gotchas:**\n- You **cannot** add/remove a trailing slash with a redirect — CDN normalizes URLs first; a `/x/ → /x 301!` rule loops infinitely. Rely on Pretty URLs (default on).\n- Splat asterisks work only at the **end** of a segment (`/jobs/*`), not mid-path (`/jobs/*.html` invalid). Placeholders (`:x`) only at the start of a segment; can't mix wildcard+placeholder in one segment.\n- You can't exclude a path from a splat; put a more specific rule first.\n- `Country` = ISO 3166-1 alpha-2; language redirects match only the **first** `Accept-Language` entry.\n- Role-based redirects with external auth providers are **Enterprise-only**.\n- 10,000+ redirects: use wildcards/placeholders or Edge Functions — oversized serialized output fails the deploy.\n\n## Proxies\n\n```\n/api/* https://api.example.com/:splat 200\n/netlify-site/* https://my-other-site.netlify.app/:splat 200 # use .netlify.app, not custom domain\n```\n```toml\n[[redirects]] # custom request headers + force\n from = \"/search\"\n to = \"https://api.mysearch.com\"\n status = 200\n force = true\n headers = {X-From = \"Netlify\"}\n```\nSigned proxy (`signed` names an env var scoped to **Runtime**; must live in `netlify.toml`; JWS is external-only, not Netlify→Netlify):\n```toml\n[[redirects]]\n from = \"/search\"\n to = \"https://api.mysearch.com\"\n status = 200\n force = true\n signed = \"API_SIGNATURE_TOKEN_PLACEHOLDER\"\n```\n\n**Gotchas:** cross-team rewrites disallowed; same-password-site rewrites OK but not across separate protected sites; proxy timeout **26 s**; one hop by default; relative-path assets break (use absolute or `<base>`); loops silently ignored.\n\n## Custom headers\n\n```\n/*\n X-Frame-Options: DENY\n/templates/index2.html\n X-Frame-Options: SAMEORIGIN\n```\nMulti-value — repeat the key (`_headers`) or a multiline TOML string:\n```toml\n[[headers]]\n for = \"/*\"\n [headers.values]\n cache-control = '''\n max-age=0,\n no-cache,\n no-store,\n must-revalidate'''\n```\n\n**Gotchas:**\n- Headers in `_headers`/`netlify.toml` are **global** — NOT scoped to branch/context. Workaround: strip global headers, keep header files in a custom dir, and `cp` them into the publish dir from a per-context build command:\n ```toml\n [context.staging]\n command = \"npm run build && cp ./custom-headers/_stagingHeaders ./dist/_headers\"\n ```\n- Headers apply only to files from Netlify's store — **NOT** to proxied content or function/edge (SSR) responses; those must set their own headers.\n- Ignored (server-set) names include `Content-Length`, `Content-Encoding`, `Location` (use redirects), `Set-Cookie`, `Server`, etc.\n- Basic auth headers: **Pro/Enterprise only**. Cross-subdomain cookies need a custom domain (`netlify.app` is on the Public Suffix List).\n\n## Functions\n\n```toml\n[functions]\n directory = \"myfunctions/\" # default: <base>/netlify/functions\n node_bundler = \"esbuild\"\n external_node_modules = [\"package-1\"] # esbuild only; native add-ons etc.\n included_files = [\"files/*.md\"] # ! prefix excludes\n\n[functions.\"api_*\"] # glob/named blocks concatenate with top-level\n external_node_modules = [\"package-2\"]\n included_files = [\"!files/post-1.md\"]\n```\n\n## Environment variables\n\nTwo storage methods:\n- **UI / CLI / API** — stored on Netlify (not the repo). Supports site + shared vars, per-context values, scopes; reaches builds, functions/edge/ODB, snippet injection, forms, signed proxies. **Recommended for anything sensitive.**\n- **`netlify.toml`** — stored in the repo. Site vars only, per-context values, **no scope selection** (everything gets **Builds** + **Post processing**), reaches builds + snippet injection only.\n\n`netlify.toml` env vars **override** same-key UI/CLI/API vars.\n\nPer-context values in TOML:\n```toml\n[context.production]\n environment = { NODE_VERSION = \"14.15.3\" }\n[context.deploy-preview.environment]\n NOT_PRIVATE_ITEM = \"not so secret\"\n[context.branch-deploy.environment]\n NODE_ENV = \"development\"\n```\n\nCLI:\n```bash\nnetlify env:set KEY value # --secret marks it a secret\nnetlify env:import .env # site vars; --replace-existing wipes others first\nnetlify env:unset KEY\nnetlify env:list --plain --context production > .env\nnetlify build # local build with Netlify's env vars\n```\nAPI: `createEnvVars` / `updateEnvVar` (`is_secret: true`) / `setEnvVarValue` / `deleteEnvVar` / `deleteEnvVarValue`.\n\n**Access syntax:** Bash `$VAR` in `build.command`/`ignore.command`; `process.env.VAR` in Node scripts and plugins.\n\n**Scopes** (Pro/Enterprise; default all): Builds (site builds) · Functions (Functions/Edge/ODB) · Runtime (forms, signed proxies) · Post processing (snippet injection). Shared vars are Pro/Enterprise and **Team-Owner-only** to read/edit. Precedence for a site+shared key collision resolves **per scope** — a site var only wins within the scopes it actually carries.\n\n**Naming/limits:** keys alphanumeric + underscore, must start with a letter (`1KEY`, `_KEY1` invalid); keys ≤255 chars, values ≤5,000 chars. Read-only variable names are reserved. Changes need a build + deploy.\n\n**Set the build language via reserved config vars** — `NODE_VERSION`, `NPM_FLAGS`, `YARN_VERSION`, `BUN_VERSION`, `RUBY_VERSION`, `PHP_VERSION`, `PYTHON_VERSION`, `GO_VERSION`, `HUGO_VERSION`, `PNPM_FLAGS`, `NPM_TOKEN` (Yarn: `YARN_NPM_AUTH_TOKEN`), etc.\n\n**Must be set in UI/CLI/API, NOT `netlify.toml`** (read after the repo is cloned or a runtime-only var): `AWS_LAMBDA_JS_RUNTIME`, `GIT_LFS_ENABLED`, `GIT_LFS_FETCH_INCLUDE`, `NETLIFY_BUILD_DEBUG`.\n\n**`CI` gotcha:** defaults to `true`; if it breaks a build, prepend `CI='' ` to the build command.\n\n### Injecting env values into headers/redirects\n`key = \"$VAR\"` is unsupported. Only path (scope must include **Builds**):\n```toml\n[build]\n command = \"sed -i \\\"s|HEADER_PLACEHOLDER|${PROD_API_LOCATION}|g\\\" netlify.toml && yarn build\"\n```\n`sed` substitution works **only** for `[[headers]]`/`[[redirects]]` (read after the build) and is **not** visible to build plugins (they run before the build command). For plugin-visible changes, use a local build plugin editing `netlifyConfig`.\n\n### Useful read-only build vars\n`CONTEXT` (`production`/`deploy-preview`/`branch-deploy`/`dev`), `BRANCH`, `COMMIT_REF`, `CACHED_COMMIT_REF`, `PULL_REQUEST`, `REVIEW_ID`, `URL`, `DEPLOY_URL`, `DEPLOY_PRIME_URL`, `SITE_ID`, `SITE_NAME`.\n\n## Secrets Controller\n\nFlag a var as secret: `Contains secret values` (UI) / `--secret` (CLI) / `is_secret: true` (API). Enforced, non-customizable policy:\n- Secret values are **write-only** — no readable version after set; the flag can't be removed to reveal it.\n- Secrets need explicit contexts + scopes; **cannot** carry the `post processing` scope.\n- Only code on Netlify (edge/serverless/build) reads unmasked values; off-Netlify sees masked. The `dev`-context value is exempt (unmasked from UI/CLI/API); `netlify build` never emits raw values.\n\n**Secret scanning** runs automatically once any var is secret (and via smart detection). Fails the build on detection and logs the location. Configure via env vars set per context:\n- `SECRETS_SCAN_ENABLED=false` — disables **all** scanning (loses all secret protection).\n- `SECRETS_SCAN_SMART_DETECTION_ENABLED=false` — disables smart detection only.\n- `SECRETS_SCAN_OMIT_KEYS`, `SECRETS_SCAN_OMIT_PATHS` (comma lists; paths from repo root, globs OK).\n- `SECRETS_SCAN_SMART_DETECTION_OMIT_VALUES` — safelist false positives (**prefer** this over disabling). Smart detection is Personal/Pro/Enterprise.\n\nScanning covers all build files, values >4 chars and non-boolean, searching plaintext + base64 + URI-encoded permutations.\n\n### Sensitive variable policy (public repos only)\nGoverns whether **untrusted** deploys (unrecognized authors) get sensitive vars. Site members' Git deploys are always trusted, even from forks. Set at Project configuration > Environment variables > Site policies:\n- **Require approval** (default) — untrusted deploys wait for a member's approval.\n- **Deploy without sensitive variables** — builds run, sensitive vars withheld.\n- **Deploy without restrictions** — all vars present.\n\nNOT available for GitHub Enterprise Server / GitLab self-managed repos (treated as private).\n\n## Ignore builds\n\n`ignore` under `[build]` decides whether to rebuild — runs from the base directory in Bash (or Node.js 18, fixed; site `package.json` deps **not** available). **Exit `1` = changed → build continues; exit `0` = no change → build stops.** A build hook always builds regardless of exit code.\n```toml\n[build]\n ignore = \"git diff --quiet $CACHED_COMMIT_REF $COMMIT_REF packages/blog-1 packages/common\"\n```\n```toml\n[build]\n ignore = \"node ignore_build.js\" # separate file paths must start with ./\n```\n```js\n// ignore_build.js\nprocess.exitCode = process.env.BRANCH.includes(\"debug\") ? 0 : 1\n```\n\n## Monorepos\n\nSet the site subdirectory as the **package directory** (keep its `netlify.toml` there), leave base at root `/`, declare deps at the subdirectory level. Package directory is **UI-only — cannot be set in `netlify.toml`** (Project configuration > Developer settings > Continuous deployment > Build settings). Config file discovery order: package dir → base dir → root. Paths in `netlify.toml` stay absolute relative to the base directory. `netlify <cmd> --filter <site>` selects a site.\n\n## JavaScript SPAs\n\nBuild command `npm run <script>` / `yarn <script>`; publish dir often `dist` (framework-dependent). Add the `/* /index.html 200` fallback (above) for `pushState` routing. Code splitting + hashed filenames with atomic deploys can throw `Uncaught SyntaxError: Unexpected token` on stale references — disable hashed filenames, use permalinks, or a service worker.\n\n## Netlify Dev `[dev]`\n\nDoes **NOT** run in Bash (no Bash syntax in `command`). There is **no `environment` key** — set local env vars under `[context.dev.environment]`.\n```toml\n[dev]\n command = \"yarn start\"\n targetPort = 3000 # if both command + targetPort set, framework must be \"#custom\"\n port = 8888\n framework = \"#custom\"\n [dev.https]\n certFile = \"cert.pem\"\n keyFile = \"key.pem\"\n```\n\n## Plugins & extensions\n\n```toml\n[[plugins]]\npackage = \"netlify-plugin-check-output-for-puppy-references\"\n [plugins.inputs]\n breeds = [\"pomeranian\", \"chihuahua\"]\n\n[[integrations]] # build-time extension; install on team first\n name = \"abc-performance-extension\"\n [integrations.config]\n output_path = \"reports/performance-reports.html\"\n```\n\nFull reference pages: build environment variables at https://docs.netlify.com/build/configure-builds/environment-variables.md, env-var overview at https://docs.netlify.com/build/environment-variables/overview.md, Secrets Controller at https://docs.netlify.com/build/environment-variables/secrets-controller.md, redirects at https://docs.netlify.com/manage/routing/redirects/overview.md, redirect options at https://docs.netlify.com/manage/routing/redirects/redirect-options.md, rewrites/proxies at https://docs.netlify.com/manage/routing/redirects/rewrites-proxies.md, custom headers at https://docs.netlify.com/manage/routing/headers.md, and file-based config at https://docs.netlify.com/build/configure-builds/file-based-configuration.md.\n\n<!-- Plan gating for the sensitive variable policy itself is unspecified in the sources; only its public-repo requirement and the smart-detection plan list are documented. -->\n\n<!-- system: agent-context/config/system.md — human-owned, merged by ctx-gen; edit system.md, not this section -->\n# Netlify house rules (config)\n\nThese are org conventions, not docs facts — merged into the rendered skill by\nctx-gen and never generated. Owned by the skills maintainer.\n\n1. Env vars set in `netlify.toml` are NOT available to functions or edge\n functions at runtime — reading them there returns `undefined`. Set\n runtime vars in the UI or with `netlify env:set`, not `netlify.toml`.\n2. Never put secrets in client-prefixed env vars (`VITE_`, `NEXT_PUBLIC_`,\n `PUBLIC_`, ...) — they are inlined into the client bundle; `--secret`\n does not protect them.\n3. When snapshotting env vars locally (`netlify env:list --plain > .env`),\n keep `.env` gitignored — never commit it.\n4. State env-var scope interaction explicitly: a site variable scoped to\n Builds does not shadow the shared variable for other scopes — precedence\n resolves independently per scope (site beats shared only within the\n scopes the site variable actually carries).\n""---\nname: netlify-config\ndescription: Configure Netlify builds and routing via netlify.toml, _redirects, and _headers. Use when setting a build command or publish directory, validating netlify.toml against its JSON schema, adding redirects/rewrites/proxies or an SPA fallback rewrite, or setting custom response headers or basic auth. Also use when managing environment variables and secrets, scoping vars per deploy context, marking a var as secret or disabling secret scanning, configuring functions bundling, ignoring builds, or wiring up a monorepo or JavaScript SPA on Netlify.\n---\n\n# Netlify configuration\n\nConfig lives in three files at the repo **root** (or the base/package directory for monorepos):\n- `netlify.toml`: build, contexts, plugins, functions, redirects, headers, dev.\n- `_redirects`: plain-text redirect/rewrite rules, saved to the **publish directory**, no extension.\n- `_headers`: plain-text response headers, saved to the **publish directory**.\n\n`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).\n\n## Modern vs legacy syntax to reach for\n- Schema: start `netlify.toml` with `\"$schema\" = \"https://open-api.netlify.com/netlify.schema.json\"` (key is quoted). Editors and agents with TOML JSON-schema support suggest and validate properties. In VS Code, use the Even Better TOML extension. Netlify ignores the key at build/deploy. **A schema-valid file can still fail to build**, because checks like whether a directory exists happen only during the build.\n- Functions bundler: use `node_bundler = \"esbuild\"`. `zisi` is the legacy JS default. TypeScript always uses `esbuild`.\n- Temporary redirect: use `status = 302`. `307` is **unsupported**.\n- Gatsby Image CDN: use `NETLIFY_IMAGE_CDN`, not the deprecated `GATSBY_CLOUD_IMAGE_CDN`.\n- 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).\n\n## `netlify.toml` build + contexts\n\n```toml\n\"$schema\" = \"https://open-api.netlify.com/netlify.schema.json\"\n\n[build]\n base = \"frontend\"\n publish = \"dist\"\n command = \"npm run build\"\n environment = { NODE_VERSION = \"18\" }\n\n[context.production]\n publish = \"output/\"\n command = \"make publish\"\n\n[context.deploy-preview]\n publish = \"dist/\"\n\n[context.\"feat/branch\"] # quote names with special characters\n command = \"npm run preview\"\n```\n\n`[build]` runs in **Bash**. Context-aware keys include `[build]` and `[[plugins]]`. They do **NOT** include `[[redirects]]` or `[[headers]]`, which are always global. Precedence, least→most specific: UI < toml < any-context property < `[context.<name>]` < `[context.branchname]`.\n\n## Redirects and rewrites\n\n`_redirects` rules are processed **first**, then `netlify.toml`. Within each, the **first matching rule top-to-bottom wins**, so list specific rules before general ones. Edge functions run before redirects.\n\nSPA history-`pushState` fallback (required for clean URLs):\n```\n/* /index.html 200\n```\n```toml\n[[redirects]]\n from = \"/*\"\n to = \"/index.html\"\n status = 200\n```\n\n`_redirects` syntax is `from to [status] [conditions]`. Lines starting with `#` are comments, paths are case-sensitive, and special chars must be URL-encoded:\n```\n/home / 301\n/my-redirect / 302\n/ecommerce /store-closed 404 # custom 404 for a path\n/pass-through /index.html 200 # rewrite\n/best-pets/dogs /best-pets/cats.html 200! # force/shadow (! or force=true)\n/news/* /blog/:splat # splat\n/news/:month/:date/:year/:slug /blog/:year/:month/:date/:slug # placeholders\n/store id=:id /blog/:id 301 # query params\n/ /anz 302 Country=au,nz # no spaces in value list\n/israel/* /israel/he/:splat 302 Language=he\n/* /legacy/:splat 200 Cookie=is_legacy,my_other_cookie\n```\n\n`[[redirects]]` keywords:\n- `from`, `to`\n- `status` (default `301`)\n- `force` (default `false`; same as `!`/shadow)\n- `query` (`query = {path = \":path\"}`)\n- `conditions` (`{Language, Country, Role, Cookie}`)\n- `headers` (proxy request headers)\n- `signed` (env var name for signed proxies)\n\n**Gotchas:**\n- You **cannot** add or remove a trailing slash with a redirect. The CDN normalizes URLs first, so a `/x/ → /x 301!` rule loops infinitely. Rely on Pretty URLs (default on).\n- Splat asterisks work only at the **end** of a segment (`/jobs/*`), not mid-path (`/jobs/*.html` is invalid). Placeholders (`:x`) work only at the start of a segment. You can't mix a wildcard and a placeholder in one segment.\n- You can't exclude a path from a splat. Put a more specific rule first instead.\n- `Country` takes ISO 3166-1 alpha-2 codes. Language redirects match only the **first** `Accept-Language` entry.\n- Role-based redirects with external auth providers are **Enterprise-only**.\n- For 10,000+ redirects, use wildcards/placeholders or Edge Functions. Oversized serialized output fails the deploy.\n\n## Proxies\n\n```\n/api/* https://api.example.com/:splat 200\n/netlify-site/* https://my-other-site.netlify.app/:splat 200 # use .netlify.app, not custom domain\n```\n```toml\n[[redirects]] # custom request headers + force\n from = \"/search\"\n to = \"https://api.mysearch.com\"\n status = 200\n force = true\n headers = {X-From = \"Netlify\"}\n```\nSigned proxy rules:\n- `signed` names an env var scoped to **Runtime**.\n- The rule must live in `netlify.toml`.\n- JWS signing works for external targets only, not Netlify→Netlify.\n\n```toml\n[[redirects]]\n from = \"/search\"\n to = \"https://api.mysearch.com\"\n status = 200\n force = true\n signed = \"API_SIGNATURE_TOKEN_PLACEHOLDER\"\n```\n\n**Gotchas:**\n- Cross-team rewrites are disallowed.\n- Rewrites within the same password-protected site are OK, but not across separate protected sites.\n- Proxy timeout is **26 s**.\n- Only one hop by default.\n- Assets with relative paths break; use absolute paths or `<base>`.\n- Looping rules are silently ignored.\n\n## Custom headers\n\n```\n/*\n X-Frame-Options: DENY\n/templates/index2.html\n X-Frame-Options: SAMEORIGIN\n```\nFor multi-value headers, repeat the key (`_headers`) or use a multiline TOML string:\n```toml\n[[headers]]\n for = \"/*\"\n [headers.values]\n cache-control = '''\n max-age=0,\n no-cache,\n no-store,\n must-revalidate'''\n```\n\n**Gotchas:**\n- Headers in `_headers`/`netlify.toml` are **global**, NOT scoped to branch/context. Workaround: remove global headers, keep header files in a custom dir, and `cp` them into the publish dir from a per-context build command:\n ```toml\n [context.staging]\n command = \"npm run build && cp ./custom-headers/_stagingHeaders ./dist/_headers\"\n ```\n- Headers apply only to files from Netlify's store. They do **NOT** apply to proxied content or function/edge (SSR) responses, which must set their own headers.\n- Server-set names are ignored, including `Content-Length`, `Content-Encoding`, `Location` (use redirects), `Set-Cookie`, and `Server`.\n- Basic auth headers are **Pro/Enterprise only**.\n- Cross-subdomain cookies need a custom domain, because `netlify.app` is on the Public Suffix List.\n\n## Functions\n\n```toml\n[functions]\n directory = \"myfunctions/\" # default: <base>/netlify/functions\n node_bundler = \"esbuild\"\n external_node_modules = [\"package-1\"] # esbuild only; native add-ons etc.\n included_files = [\"files/*.md\"] # ! prefix excludes\n\n[functions.\"api_*\"] # glob/named blocks concatenate with top-level\n external_node_modules = [\"package-2\"]\n included_files = [\"!files/post-1.md\"]\n```\n\n## Environment variables\n\nTwo storage methods:\n- **UI / CLI / API**: stored on Netlify, not in the repo.\n - Supports site + shared vars, per-context values, and scopes.\n - Reaches builds, functions/edge/ODB, snippet injection, forms, and signed proxies.\n - **Recommended for anything sensitive.**\n- **`netlify.toml`**: stored in the repo.\n - Site vars only, with per-context values.\n - **No scope selection**: everything gets **Builds** + **Post processing**.\n - Reaches builds and snippet injection only.\n\n`netlify.toml` env vars **override** same-key UI/CLI/API vars.\n\nPer-context values in TOML:\n```toml\n[context.production]\n environment = { NODE_VERSION = \"14.15.3\" }\n[context.deploy-preview.environment]\n NOT_PRIVATE_ITEM = \"not so secret\"\n[context.branch-deploy.environment]\n NODE_ENV = \"development\"\n```\n\nCLI:\n```bash\nnetlify env:set KEY value # --secret marks it a secret\nnetlify env:import .env # site vars; --replace-existing wipes others first\nnetlify env:unset KEY\nnetlify env:list --plain --context production > .env\nnetlify build # local build with Netlify's env vars\n```\nAPI: `createEnvVars` / `updateEnvVar` (`is_secret: true`) / `setEnvVarValue` / `deleteEnvVar` / `deleteEnvVarValue`.\n\n**Access syntax:** Bash `$VAR` in `build.command`/`ignore.command`; `process.env.VAR` in Node scripts and plugins.\n\n**Scopes** (Pro/Enterprise; default is all scopes):\n- Builds: site builds.\n- Functions: Functions, Edge Functions, ODB.\n- Runtime: forms, signed proxies.\n- Post processing: snippet injection.\n\nShared vars are Pro/Enterprise and **Team-Owner-only** to read/edit. When a site var and a shared var use the same key, precedence resolves **per scope**: the site var only wins within the scopes it actually carries.\n\n**Naming/limits:**\n- Keys use only alphanumerics and underscores, and must start with a letter (`1KEY` and `_KEY1` are invalid).\n- Keys ≤255 chars, values ≤5,000 chars.\n- Read-only variable names are reserved.\n- Changes need a build + deploy.\n\n**Set the build language via reserved config vars**: `NODE_VERSION`, `NPM_FLAGS`, `YARN_VERSION`, `BUN_VERSION`, `RUBY_VERSION`, `PHP_VERSION`, `PYTHON_VERSION`, `GO_VERSION`, `HUGO_VERSION`, `PNPM_FLAGS`, `NPM_TOKEN` (Yarn: `YARN_NPM_AUTH_TOKEN`), etc.\n\n**Must be set in UI/CLI/API, NOT `netlify.toml`**, because they are read before `netlify.toml` (after the repo is cloned) or are runtime-only: `AWS_LAMBDA_JS_RUNTIME`, `GIT_LFS_ENABLED`, `GIT_LFS_FETCH_INCLUDE`, `NETLIFY_BUILD_DEBUG`.\n\n**`CI` gotcha:** `CI` defaults to `true`. If it breaks a build, prepend `CI='' ` to the build command.\n\n### Injecting env values into headers/redirects\n`key = \"$VAR\"` is unsupported. For headers and redirects, substitute values from the build command (the var's scope must include **Builds**):\n```toml\n[build]\n command = \"sed -i \\\"s|HEADER_PLACEHOLDER|${PROD_API_LOCATION}|g\\\" netlify.toml && yarn build\"\n```\n`sed` substitution works **only** for `[[headers]]`/`[[redirects]]`, which are read after the build. It is **not** visible to build plugins, which run before the build command. For changes plugins must see, use a local build plugin that edits `netlifyConfig`.\n\n### Useful read-only build vars\n`CONTEXT` (`production`/`deploy-preview`/`branch-deploy`/`dev`), `BRANCH`, `COMMIT_REF`, `CACHED_COMMIT_REF`, `PULL_REQUEST`, `REVIEW_ID`, `URL`, `DEPLOY_URL`, `DEPLOY_PRIME_URL`, `SITE_ID`, `SITE_NAME`.\n\n## Secrets Controller\n\nFlag a var as secret with `Contains secret values` (UI), `--secret` (CLI), or `is_secret: true` (API). The policy is enforced and can't be customized:\n- Secret values are **write-only**: there is no readable version after setting, and the flag can't be removed to reveal the value.\n- Secrets need explicit contexts + scopes and **cannot** carry the `post processing` scope.\n- Only code on Netlify (edge/serverless/build) reads unmasked values. Code off Netlify sees masked values.\n- The `dev`-context value is exempt and stays unmasked from UI/CLI/API. `netlify build` never emits raw values.\n\n**Secret scanning** runs automatically once any var is secret, and also through smart detection. It fails the build on detection and logs the location. Configure it with env vars set per context:\n- `SECRETS_SCAN_ENABLED=false` disables **all** scanning, which removes all secret protection.\n- `SECRETS_SCAN_SMART_DETECTION_ENABLED=false` disables smart detection only.\n- `SECRETS_SCAN_OMIT_KEYS` and `SECRETS_SCAN_OMIT_PATHS` take comma lists. Paths are relative to the repo root; globs are OK.\n- `SECRETS_SCAN_SMART_DETECTION_OMIT_VALUES` safelists false positives. **Prefer** this over disabling.\n- Smart detection is available on Personal/Pro/Enterprise.\n\nScanning covers all build files. It checks secret values longer than 4 chars that aren't booleans, searching plaintext, base64, and URI-encoded permutations.\n\n### Sensitive variable policy (public repos only)\nThis policy governs whether **untrusted** deploys (from unrecognized authors) get sensitive vars. Site members' Git deploys are always trusted, even from forks. Set it at Project configuration > Environment variables > Site policies:\n- **Require approval** (default): untrusted deploys wait for a member's approval.\n- **Deploy without sensitive variables**: builds run, but sensitive vars are withheld.\n- **Deploy without restrictions**: all vars are present.\n\nThe policy is NOT available for GitHub Enterprise Server or GitLab self-managed repos, which are treated as private.\n\n## Ignore builds\n\n`ignore` under `[build]` decides whether to rebuild. It runs from the base directory in Bash, or in Node.js 18 (fixed version; site `package.json` deps are **not** available).\n- **Exit `1` = changed → build continues.**\n- **Exit `0` = no change → build stops.**\n- A build hook always builds, regardless of exit code.\n```toml\n[build]\n ignore = \"git diff --quiet $CACHED_COMMIT_REF $COMMIT_REF packages/blog-1 packages/common\"\n```\n```toml\n[build]\n ignore = \"node ignore_build.js\" # separate file paths must start with ./\n```\n```js\n// ignore_build.js\nprocess.exitCode = process.env.BRANCH.includes(\"debug\") ? 0 : 1\n```\n\n## Monorepos\n\nRecommended setup:\n1. Set the site subdirectory as the **package directory** and keep its `netlify.toml` there.\n2. Leave the base directory at root `/`.\n3. Declare deps at the subdirectory level.\n\nThe package directory is **UI-only and cannot be set in `netlify.toml`**. Set it at Project configuration > Developer settings > Continuous deployment > Build settings.\n\nConfig files are discovered in this order: package dir → base dir → root. Paths in `netlify.toml` stay absolute relative to the base directory. Use `netlify <cmd> --filter <site>` to select a site.\n\n## JavaScript SPAs\n\n- Build command: `npm run <script>` or `yarn <script>`.\n- Publish dir: often `dist`, depending on the framework.\n- Add the `/* /index.html 200` fallback (above) for `pushState` routing.\n- Code splitting + hashed filenames with atomic deploys can throw `Uncaught SyntaxError: Unexpected token` on stale references. Fix by disabling hashed filenames, using permalinks, or using a service worker.\n\n## Netlify Dev `[dev]`\n\n`[dev]` does **NOT** run in Bash, so don't use Bash syntax in `command`. There is **no `environment` key**; set local env vars under `[context.dev.environment]`.\n```toml\n[dev]\n command = \"yarn start\"\n targetPort = 3000 # if both command + targetPort set, framework must be \"#custom\"\n port = 8888\n framework = \"#custom\"\n [dev.https]\n certFile = \"cert.pem\"\n keyFile = \"key.pem\"\n```\n\n## Plugins & extensions\n\n```toml\n[[plugins]]\npackage = \"netlify-plugin-check-output-for-puppy-references\"\n [plugins.inputs]\n breeds = [\"pomeranian\", \"chihuahua\"]\n\n[[integrations]] # build-time extension; install on team first\n name = \"abc-performance-extension\"\n [integrations.config]\n output_path = \"reports/performance-reports.html\"\n```\n\n## Reference pages\n- Build environment variables: https://docs.netlify.com/build/configure-builds/environment-variables.md\n- Env-var overview: https://docs.netlify.com/build/environment-variables/overview.md\n- Secrets Controller: https://docs.netlify.com/build/environment-variables/secrets-controller.md\n- Redirects: https://docs.netlify.com/manage/routing/redirects/overview.md\n- Redirect options: https://docs.netlify.com/manage/routing/redirects/redirect-options.md\n- Rewrites/proxies: https://docs.netlify.com/manage/routing/redirects/rewrites-proxies.md\n- Custom headers: https://docs.netlify.com/manage/routing/headers.md\n- File-based config: https://docs.netlify.com/build/configure-builds/file-based-configuration.md\n\n<!-- Plan gating for the sensitive variable policy itself is unspecified in the sources; only its public-repo requirement and the smart-detection plan list are documented. -->\n\n<!-- system: agent-context/config/system.md — human-owned, merged by ctx-gen; edit system.md, not this section -->\n# Netlify house rules (config)\n\nThese are org conventions, not docs facts — merged into the rendered skill by\nctx-gen and never generated. Owned by the skills maintainer.\n\n1. Env vars set in `netlify.toml` are NOT available to functions or edge\n functions at runtime — reading them there returns `undefined`. Set\n runtime vars in the UI or with `netlify env:set`, not `netlify.toml`.\n2. Never put secrets in client-prefixed env vars (`VITE_`, `NEXT_PUBLIC_`,\n `PUBLIC_`, ...) — they are inlined into the client bundle; `--secret`\n does not protect them.\n3. When snapshotting env vars locally (`netlify env:list --plain > .env`),\n keep `.env` gitignored — never commit it.\n4. State env-var scope interaction explicitly: a site variable scoped to\n Builds does not shadow the shared variable for other scopes — precedence\n resolves independently per scope (site beats shared only within the\n scopes the site variable actually carries).\n5. When creating or editing `netlify.toml`, add\n `\"$schema\" = \"https://open-api.netlify.com/netlify.schema.json\"` as its\n first line if it's missing, and check property names and value types\n against that schema instead of guessing. The schema doesn't describe the\n contents of `[dev]`, `[template]`, `[[integrations]]` or\n `[build.processing]`; use the docs for those.\n"Full snapshot data
{
"description": "Configure Netlify builds and routing via netlify.toml, _redirects, and _headers. Use when setting a build command or publish directory, validating netlify.toml against its JSON schema, adding redirects/rewrites/proxies or an SPA fallback rewrite, or setting custom response headers or basic auth. Also use when managing environment variables and secrets, scoping vars per deploy context, marking a var as secret or disabling secret scanning, configuring functions bundling, ignoring builds, or wiring up a monorepo or JavaScript SPA on Netlify.",
"included_files": [],
"name": "netlify-config",
"skill_md_contents": "---\nname: netlify-config\ndescription: Configure Netlify builds and routing via netlify.toml, _redirects, and _headers. Use when setting a build command or publish directory, validating netlify.toml against its JSON schema, adding redirects/rewrites/proxies or an SPA fallback rewrite, or setting custom response headers or basic auth. Also use when managing environment variables and secrets, scoping vars per deploy context, marking a var as secret or disabling secret scanning, configuring functions bundling, ignoring builds, or wiring up a monorepo or JavaScript SPA on Netlify.\n---\n\n# Netlify configuration\n\nConfig lives in three files at the repo **root** (or the base/package directory for monorepos):\n- `netlify.toml`: build, contexts, plugins, functions, redirects, headers, dev.\n- `_redirects`: plain-text redirect/rewrite rules, saved to the **publish directory**, no extension.\n- `_headers`: plain-text response headers, saved to the **publish directory**.\n\n`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).\n\n## Modern vs legacy syntax to reach for\n- Schema: start `netlify.toml` with `\"$schema\" = \"https://open-api.netlify.com/netlify.schema.json\"` (key is quoted). Editors and agents with TOML JSON-schema support suggest and validate properties. In VS Code, use the Even Better TOML extension. Netlify ignores the key at build/deploy. **A schema-valid file can still fail to build**, because checks like whether a directory exists happen only during the build.\n- Functions bundler: use `node_bundler = \"esbuild\"`. `zisi` is the legacy JS default. TypeScript always uses `esbuild`.\n- Temporary redirect: use `status = 302`. `307` is **unsupported**.\n- Gatsby Image CDN: use `NETLIFY_IMAGE_CDN`, not the deprecated `GATSBY_CLOUD_IMAGE_CDN`.\n- 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).\n\n## `netlify.toml` build + contexts\n\n```toml\n\"$schema\" = \"https://open-api.netlify.com/netlify.schema.json\"\n\n[build]\n base = \"frontend\"\n publish = \"dist\"\n command = \"npm run build\"\n environment = { NODE_VERSION = \"18\" }\n\n[context.production]\n publish = \"output/\"\n command = \"make publish\"\n\n[context.deploy-preview]\n publish = \"dist/\"\n\n[context.\"feat/branch\"] # quote names with special characters\n command = \"npm run preview\"\n```\n\n`[build]` runs in **Bash**. Context-aware keys include `[build]` and `[[plugins]]`. They do **NOT** include `[[redirects]]` or `[[headers]]`, which are always global. Precedence, least→most specific: UI < toml < any-context property < `[context.<name>]` < `[context.branchname]`.\n\n## Redirects and rewrites\n\n`_redirects` rules are processed **first**, then `netlify.toml`. Within each, the **first matching rule top-to-bottom wins**, so list specific rules before general ones. Edge functions run before redirects.\n\nSPA history-`pushState` fallback (required for clean URLs):\n```\n/* /index.html 200\n```\n```toml\n[[redirects]]\n from = \"/*\"\n to = \"/index.html\"\n status = 200\n```\n\n`_redirects` syntax is `from to [status] [conditions]`. Lines starting with `#` are comments, paths are case-sensitive, and special chars must be URL-encoded:\n```\n/home / 301\n/my-redirect / 302\n/ecommerce /store-closed 404 # custom 404 for a path\n/pass-through /index.html 200 # rewrite\n/best-pets/dogs /best-pets/cats.html 200! # force/shadow (! or force=true)\n/news/* /blog/:splat # splat\n/news/:month/:date/:year/:slug /blog/:year/:month/:date/:slug # placeholders\n/store id=:id /blog/:id 301 # query params\n/ /anz 302 Country=au,nz # no spaces in value list\n/israel/* /israel/he/:splat 302 Language=he\n/* /legacy/:splat 200 Cookie=is_legacy,my_other_cookie\n```\n\n`[[redirects]]` keywords:\n- `from`, `to`\n- `status` (default `301`)\n- `force` (default `false`; same as `!`/shadow)\n- `query` (`query = {path = \":path\"}`)\n- `conditions` (`{Language, Country, Role, Cookie}`)\n- `headers` (proxy request headers)\n- `signed` (env var name for signed proxies)\n\n**Gotchas:**\n- You **cannot** add or remove a trailing slash with a redirect. The CDN normalizes URLs first, so a `/x/ → /x 301!` rule loops infinitely. Rely on Pretty URLs (default on).\n- Splat asterisks work only at the **end** of a segment (`/jobs/*`), not mid-path (`/jobs/*.html` is invalid). Placeholders (`:x`) work only at the start of a segment. You can't mix a wildcard and a placeholder in one segment.\n- You can't exclude a path from a splat. Put a more specific rule first instead.\n- `Country` takes ISO 3166-1 alpha-2 codes. Language redirects match only the **first** `Accept-Language` entry.\n- Role-based redirects with external auth providers are **Enterprise-only**.\n- For 10,000+ redirects, use wildcards/placeholders or Edge Functions. Oversized serialized output fails the deploy.\n\n## Proxies\n\n```\n/api/* https://api.example.com/:splat 200\n/netlify-site/* https://my-other-site.netlify.app/:splat 200 # use .netlify.app, not custom domain\n```\n```toml\n[[redirects]] # custom request headers + force\n from = \"/search\"\n to = \"https://api.mysearch.com\"\n status = 200\n force = true\n headers = {X-From = \"Netlify\"}\n```\nSigned proxy rules:\n- `signed` names an env var scoped to **Runtime**.\n- The rule must live in `netlify.toml`.\n- JWS signing works for external targets only, not Netlify→Netlify.\n\n```toml\n[[redirects]]\n from = \"/search\"\n to = \"https://api.mysearch.com\"\n status = 200\n force = true\n signed = \"API_SIGNATURE_TOKEN_PLACEHOLDER\"\n```\n\n**Gotchas:**\n- Cross-team rewrites are disallowed.\n- Rewrites within the same password-protected site are OK, but not across separate protected sites.\n- Proxy timeout is **26 s**.\n- Only one hop by default.\n- Assets with relative paths break; use absolute paths or `<base>`.\n- Looping rules are silently ignored.\n\n## Custom headers\n\n```\n/*\n X-Frame-Options: DENY\n/templates/index2.html\n X-Frame-Options: SAMEORIGIN\n```\nFor multi-value headers, repeat the key (`_headers`) or use a multiline TOML string:\n```toml\n[[headers]]\n for = \"/*\"\n [headers.values]\n cache-control = '''\n max-age=0,\n no-cache,\n no-store,\n must-revalidate'''\n```\n\n**Gotchas:**\n- Headers in `_headers`/`netlify.toml` are **global**, NOT scoped to branch/context. Workaround: remove global headers, keep header files in a custom dir, and `cp` them into the publish dir from a per-context build command:\n ```toml\n [context.staging]\n command = \"npm run build && cp ./custom-headers/_stagingHeaders ./dist/_headers\"\n ```\n- Headers apply only to files from Netlify's store. They do **NOT** apply to proxied content or function/edge (SSR) responses, which must set their own headers.\n- Server-set names are ignored, including `Content-Length`, `Content-Encoding`, `Location` (use redirects), `Set-Cookie`, and `Server`.\n- Basic auth headers are **Pro/Enterprise only**.\n- Cross-subdomain cookies need a custom domain, because `netlify.app` is on the Public Suffix List.\n\n## Functions\n\n```toml\n[functions]\n directory = \"myfunctions/\" # default: <base>/netlify/functions\n node_bundler = \"esbuild\"\n external_node_modules = [\"package-1\"] # esbuild only; native add-ons etc.\n included_files = [\"files/*.md\"] # ! prefix excludes\n\n[functions.\"api_*\"] # glob/named blocks concatenate with top-level\n external_node_modules = [\"package-2\"]\n included_files = [\"!files/post-1.md\"]\n```\n\n## Environment variables\n\nTwo storage methods:\n- **UI / CLI / API**: stored on Netlify, not in the repo.\n - Supports site + shared vars, per-context values, and scopes.\n - Reaches builds, functions/edge/ODB, snippet injection, forms, and signed proxies.\n - **Recommended for anything sensitive.**\n- **`netlify.toml`**: stored in the repo.\n - Site vars only, with per-context values.\n - **No scope selection**: everything gets **Builds** + **Post processing**.\n - Reaches builds and snippet injection only.\n\n`netlify.toml` env vars **override** same-key UI/CLI/API vars.\n\nPer-context values in TOML:\n```toml\n[context.production]\n environment = { NODE_VERSION = \"14.15.3\" }\n[context.deploy-preview.environment]\n NOT_PRIVATE_ITEM = \"not so secret\"\n[context.branch-deploy.environment]\n NODE_ENV = \"development\"\n```\n\nCLI:\n```bash\nnetlify env:set KEY value # --secret marks it a secret\nnetlify env:import .env # site vars; --replace-existing wipes others first\nnetlify env:unset KEY\nnetlify env:list --plain --context production > .env\nnetlify build # local build with Netlify's env vars\n```\nAPI: `createEnvVars` / `updateEnvVar` (`is_secret: true`) / `setEnvVarValue` / `deleteEnvVar` / `deleteEnvVarValue`.\n\n**Access syntax:** Bash `$VAR` in `build.command`/`ignore.command`; `process.env.VAR` in Node scripts and plugins.\n\n**Scopes** (Pro/Enterprise; default is all scopes):\n- Builds: site builds.\n- Functions: Functions, Edge Functions, ODB.\n- Runtime: forms, signed proxies.\n- Post processing: snippet injection.\n\nShared vars are Pro/Enterprise and **Team-Owner-only** to read/edit. When a site var and a shared var use the same key, precedence resolves **per scope**: the site var only wins within the scopes it actually carries.\n\n**Naming/limits:**\n- Keys use only alphanumerics and underscores, and must start with a letter (`1KEY` and `_KEY1` are invalid).\n- Keys ≤255 chars, values ≤5,000 chars.\n- Read-only variable names are reserved.\n- Changes need a build + deploy.\n\n**Set the build language via reserved config vars**: `NODE_VERSION`, `NPM_FLAGS`, `YARN_VERSION`, `BUN_VERSION`, `RUBY_VERSION`, `PHP_VERSION`, `PYTHON_VERSION`, `GO_VERSION`, `HUGO_VERSION`, `PNPM_FLAGS`, `NPM_TOKEN` (Yarn: `YARN_NPM_AUTH_TOKEN`), etc.\n\n**Must be set in UI/CLI/API, NOT `netlify.toml`**, because they are read before `netlify.toml` (after the repo is cloned) or are runtime-only: `AWS_LAMBDA_JS_RUNTIME`, `GIT_LFS_ENABLED`, `GIT_LFS_FETCH_INCLUDE`, `NETLIFY_BUILD_DEBUG`.\n\n**`CI` gotcha:** `CI` defaults to `true`. If it breaks a build, prepend `CI='' ` to the build command.\n\n### Injecting env values into headers/redirects\n`key = \"$VAR\"` is unsupported. For headers and redirects, substitute values from the build command (the var's scope must include **Builds**):\n```toml\n[build]\n command = \"sed -i \\\"s|HEADER_PLACEHOLDER|${PROD_API_LOCATION}|g\\\" netlify.toml && yarn build\"\n```\n`sed` substitution works **only** for `[[headers]]`/`[[redirects]]`, which are read after the build. It is **not** visible to build plugins, which run before the build command. For changes plugins must see, use a local build plugin that edits `netlifyConfig`.\n\n### Useful read-only build vars\n`CONTEXT` (`production`/`deploy-preview`/`branch-deploy`/`dev`), `BRANCH`, `COMMIT_REF`, `CACHED_COMMIT_REF`, `PULL_REQUEST`, `REVIEW_ID`, `URL`, `DEPLOY_URL`, `DEPLOY_PRIME_URL`, `SITE_ID`, `SITE_NAME`.\n\n## Secrets Controller\n\nFlag a var as secret with `Contains secret values` (UI), `--secret` (CLI), or `is_secret: true` (API). The policy is enforced and can't be customized:\n- Secret values are **write-only**: there is no readable version after setting, and the flag can't be removed to reveal the value.\n- Secrets need explicit contexts + scopes and **cannot** carry the `post processing` scope.\n- Only code on Netlify (edge/serverless/build) reads unmasked values. Code off Netlify sees masked values.\n- The `dev`-context value is exempt and stays unmasked from UI/CLI/API. `netlify build` never emits raw values.\n\n**Secret scanning** runs automatically once any var is secret, and also through smart detection. It fails the build on detection and logs the location. Configure it with env vars set per context:\n- `SECRETS_SCAN_ENABLED=false` disables **all** scanning, which removes all secret protection.\n- `SECRETS_SCAN_SMART_DETECTION_ENABLED=false` disables smart detection only.\n- `SECRETS_SCAN_OMIT_KEYS` and `SECRETS_SCAN_OMIT_PATHS` take comma lists. Paths are relative to the repo root; globs are OK.\n- `SECRETS_SCAN_SMART_DETECTION_OMIT_VALUES` safelists false positives. **Prefer** this over disabling.\n- Smart detection is available on Personal/Pro/Enterprise.\n\nScanning covers all build files. It checks secret values longer than 4 chars that aren't booleans, searching plaintext, base64, and URI-encoded permutations.\n\n### Sensitive variable policy (public repos only)\nThis policy governs whether **untrusted** deploys (from unrecognized authors) get sensitive vars. Site members' Git deploys are always trusted, even from forks. Set it at Project configuration > Environment variables > Site policies:\n- **Require approval** (default): untrusted deploys wait for a member's approval.\n- **Deploy without sensitive variables**: builds run, but sensitive vars are withheld.\n- **Deploy without restrictions**: all vars are present.\n\nThe policy is NOT available for GitHub Enterprise Server or GitLab self-managed repos, which are treated as private.\n\n## Ignore builds\n\n`ignore` under `[build]` decides whether to rebuild. It runs from the base directory in Bash, or in Node.js 18 (fixed version; site `package.json` deps are **not** available).\n- **Exit `1` = changed → build continues.**\n- **Exit `0` = no change → build stops.**\n- A build hook always builds, regardless of exit code.\n```toml\n[build]\n ignore = \"git diff --quiet $CACHED_COMMIT_REF $COMMIT_REF packages/blog-1 packages/common\"\n```\n```toml\n[build]\n ignore = \"node ignore_build.js\" # separate file paths must start with ./\n```\n```js\n// ignore_build.js\nprocess.exitCode = process.env.BRANCH.includes(\"debug\") ? 0 : 1\n```\n\n## Monorepos\n\nRecommended setup:\n1. Set the site subdirectory as the **package directory** and keep its `netlify.toml` there.\n2. Leave the base directory at root `/`.\n3. Declare deps at the subdirectory level.\n\nThe package directory is **UI-only and cannot be set in `netlify.toml`**. Set it at Project configuration > Developer settings > Continuous deployment > Build settings.\n\nConfig files are discovered in this order: package dir → base dir → root. Paths in `netlify.toml` stay absolute relative to the base directory. Use `netlify <cmd> --filter <site>` to select a site.\n\n## JavaScript SPAs\n\n- Build command: `npm run <script>` or `yarn <script>`.\n- Publish dir: often `dist`, depending on the framework.\n- Add the `/* /index.html 200` fallback (above) for `pushState` routing.\n- Code splitting + hashed filenames with atomic deploys can throw `Uncaught SyntaxError: Unexpected token` on stale references. Fix by disabling hashed filenames, using permalinks, or using a service worker.\n\n## Netlify Dev `[dev]`\n\n`[dev]` does **NOT** run in Bash, so don't use Bash syntax in `command`. There is **no `environment` key**; set local env vars under `[context.dev.environment]`.\n```toml\n[dev]\n command = \"yarn start\"\n targetPort = 3000 # if both command + targetPort set, framework must be \"#custom\"\n port = 8888\n framework = \"#custom\"\n [dev.https]\n certFile = \"cert.pem\"\n keyFile = \"key.pem\"\n```\n\n## Plugins & extensions\n\n```toml\n[[plugins]]\npackage = \"netlify-plugin-check-output-for-puppy-references\"\n [plugins.inputs]\n breeds = [\"pomeranian\", \"chihuahua\"]\n\n[[integrations]] # build-time extension; install on team first\n name = \"abc-performance-extension\"\n [integrations.config]\n output_path = \"reports/performance-reports.html\"\n```\n\n## Reference pages\n- Build environment variables: https://docs.netlify.com/build/configure-builds/environment-variables.md\n- Env-var overview: https://docs.netlify.com/build/environment-variables/overview.md\n- Secrets Controller: https://docs.netlify.com/build/environment-variables/secrets-controller.md\n- Redirects: https://docs.netlify.com/manage/routing/redirects/overview.md\n- Redirect options: https://docs.netlify.com/manage/routing/redirects/redirect-options.md\n- Rewrites/proxies: https://docs.netlify.com/manage/routing/redirects/rewrites-proxies.md\n- Custom headers: https://docs.netlify.com/manage/routing/headers.md\n- File-based config: https://docs.netlify.com/build/configure-builds/file-based-configuration.md\n\n<!-- Plan gating for the sensitive variable policy itself is unspecified in the sources; only its public-repo requirement and the smart-detection plan list are documented. -->\n\n<!-- system: agent-context/config/system.md — human-owned, merged by ctx-gen; edit system.md, not this section -->\n# Netlify house rules (config)\n\nThese are org conventions, not docs facts — merged into the rendered skill by\nctx-gen and never generated. Owned by the skills maintainer.\n\n1. Env vars set in `netlify.toml` are NOT available to functions or edge\n functions at runtime — reading them there returns `undefined`. Set\n runtime vars in the UI or with `netlify env:set`, not `netlify.toml`.\n2. Never put secrets in client-prefixed env vars (`VITE_`, `NEXT_PUBLIC_`,\n `PUBLIC_`, ...) — they are inlined into the client bundle; `--secret`\n does not protect them.\n3. When snapshotting env vars locally (`netlify env:list --plain > .env`),\n keep `.env` gitignored — never commit it.\n4. State env-var scope interaction explicitly: a site variable scoped to\n Builds does not shadow the shared variable for other scopes — precedence\n resolves independently per scope (site beats shared only within the\n scopes the site variable actually carries).\n5. When creating or editing `netlify.toml`, add\n `\"$schema\" = \"https://open-api.netlify.com/netlify.schema.json\"` as its\n first line if it's missing, and check property names and value types\n against that schema instead of guessing. The schema doesn't describe the\n contents of `[dev]`, `[template]`, `[[integrations]]` or\n `[build.processing]`; use the docs for those.\n"
}SHA-256 of public snapshot: 1a3b7cab0075115e34f6c4058e9bed17dc0dbca474d0a50ea2e9726059dcb713