/infra-platform-netlify

name: infra-platform-netlify
description: Netlify deployment platform — serverless functions, edge functions, redirects, forms, Blobs, build plugins

Netlify Platform Patterns

> **Quick Guide:** Netlify deploys sites from Git with automatic builds, CDN distribution, and serverless compute. Use `netlify.toml` for all configuration (redirects, headers, build settings, function schedules, plugins). Serverless functions live in `netlify/functions/` and use the standard `(req: Request, context: Context) => Response` signature. Edge functions run on Deno at the network edge for geo-personalization and request transformation. Use `Netlify.env.get()` for environment variables in functions — never `process.env`. Use Netlify Blobs for key-value storage accessible from functions and edge functions.

---

<critical_requirements>

CRITICAL: Before Using This Skill

> **All code must follow project conventions in CLAUDE.md** (kebab-case, named exports, import ordering, `import type`, named constants)

**(You MUST use `Netlify.env.get()` to access environment variables in functions — NOT `process.env` which is unavailable in the modern functions runtime)**

**(You MUST use the `.mts` file extension for serverless functions to get ES module support — `.ts` defaults to CommonJS unless `"type": "module"` is in package.json)**

**(You MUST use `context.waitUntil()` for post-response background work — work not passed to waitUntil may be cancelled when the response is sent)**

**(You MUST keep redirects and headers in `netlify.toml` — they are global and NOT scoped to deploy contexts)**

</critical_requirements>

---

Examples

• [Core Setup & Functions](examples/core.md) — netlify.toml, serverless functions, scheduled functions, background functions, response streaming
• [Edge Functions & Blobs](examples/edge-functions.md) — edge function patterns, geo-personalization, middleware, Netlify Blobs storage
• [Quick Reference](reference.md) — CLI commands, limits tables, redirects/headers syntax, build plugin structure

---

**Auto-detection:** Netlify, netlify.toml, netlify/functions, @netlify/functions, @netlify/edge-functions, @netlify/blobs, Netlify.env, netlify dev, netlify deploy, netlify-cli, edge function, Netlify Blobs, getStore, netlify build, netlify forms, data-netlify, netlify.app, deploy-preview, branch-deploy, Netlify Identity

**When to use:**

• Deploying sites and applications to Netlify's CDN and serverless platform
• Writing serverless functions (API endpoints, webhooks, scheduled tasks)
• Writing edge functions (geo-personalization, A/B testing, auth, request transformation)
• Configuring redirects, rewrites, proxy rules, and custom headers
• Storing data with Netlify Blobs (key-value, file uploads, metadata)
• Setting up build plugins for custom build pipeline logic
• Managing environment variables across deploy contexts (production, deploy-preview, branch-deploy)
• Configuring Netlify Forms for static site form handling

**When NOT to use:**

• Long-running compute exceeding 60 seconds (serverless) or 50ms CPU (edge) — use traditional servers
• Workloads needing persistent database connections — Netlify functions are stateless per invocation
• Applications requiring WebSocket connections (Netlify does not support persistent WebSockets)

**Key patterns covered:**

• `netlify.toml` configuration (build, redirects, headers, deploy contexts, plugins)
• Serverless functions with typed `Context` (geo, cookies, params, waitUntil)
• Scheduled functions with cron expressions
• Background functions for long-running tasks (up to 15 minutes)
• Response streaming for real-time output
• Edge functions on Deno runtime with geo and request transformation
• Netlify Blobs key-value storage (site-level and deploy-scoped)
• Environment variables with scopes and deploy context overrides
• Netlify Forms with honeypot spam filtering
• Build plugins with lifecycle hooks

---

<philosophy>

Philosophy

Netlify is a Git-centric platform: push to a branch, Netlify builds and deploys automatically. Configuration lives in `netlify.toml` alongside your code. The platform provides three compute primitives:

1. **Serverless Functions** — Node.js-based, up to 60 seconds execution, 1 GB memory. For API endpoints, webhooks, form handlers, and scheduled tasks. 2. **Edge Functions** — Deno-based, 50ms CPU limit, run at the nearest edge node. For request/response transformation, geo-personalization, A/B testing, and authentication. 3. **Background Functions** — Same as serverless but async (client gets 202 immediately), up to 15 minutes. For long-running tasks like data processing and batch operations.

**Key architectural decisions:**

• **`netlify.toml` is the source of truth** — build commands, redirects, headers, function config, and plugin setup all live here. Settings in `netlify.toml` override the Netlify UI.
• **Functions use web standard APIs** — `Request`, `Response`, `ReadableStream`, `URL`. No proprietary request/response objects.
• **Edge functions are middleware** — they intercept requests, can modify them, and call `context.next()` to continue the chain. Return `undefined` to skip.
• **Blobs for storage** — Netlify Blobs provides key-value storage accessible from serverless functions, edge functions, and build plugins without external database setup.

**When to use Netlify:**

• Static sites, JAMstack apps, and full-stack applications with serverless backends
• Sites needing CDN distribution with automatic HTTPS
• Projects benefiting from deploy previews on every pull request
• Applications needing geo-based personalization at the edge

**When NOT to use Netlify:**

• CPU-intensive compute exceeding function time limits
• Applications needing persistent server processes or WebSockets
• Workloads requiring more than 1 GB memory per function invocation
• Data-heavy applications needing a collocated database (functions run in a single AWS region)

</philosophy>

---

<patterns>

Core Patterns