@netlify/agent-runner-cli 1.69.3 → 1.71.0

package/dist/skills/netlify-edge-functions/SKILL.md

@@ -0,0 +1,478 @@
+---
+name: netlify-edge-functions
+description: Create and deploy Netlify Edge Functions that run on Deno at the network edge. Use when implementing low-latency middleware, request/response transformations, A/B testing, geolocation routing, or authentication checks at the edge.
+---
+
+# Netlify Edge Functions
+
+Netlify Edge Functions run on Deno at the network edge, providing low-latency middleware and request/response
+transformations. They share the same handler signature pattern as serverless functions (Web API Request/Response) but
+use the Deno runtime with Web APIs built in. Edge functions are configured with a path pattern and only paths matching
+those patterns will run the edge function.
+
+## Quick Start
+
+Create an edge function file in the `netlify/edge-functions/` directory:
+
+```typescript
+// netlify/edge-functions/hello.ts
+import type { Context, Config } from '@netlify/edge-functions'
+
+export default async (req: Request, context: Context) => {
+  const name = new URL(req.url).searchParams.get('name') || 'world'
+  return new Response(`Hello, ${name}!`)
+}
+
+export const config: Config = {
+  path: '/hello',
+}
+```
+
+```javascript
+// netlify/edge-functions/hello.js
+export default async (req, context) => {
+  const name = new URL(req.url).searchParams.get('name') || 'world'
+  return new Response(`Hello, ${name}!`)
+}
+
+export const config = {
+  path: '/hello',
+}
+```
+
+Deploy and invoke at the configured `path`.
+
+ALWAYS use TypeScript (`.ts`) if other functions in the project are TypeScript or if there are no existing edge functions.
+ONLY use vanilla JavaScript if there are other `.js` files in the edge functions directory. DO NOT put global logic outside
+of the exported function unless it is wrapped in a function definition. ALWAYS use the latest format of an edge
+function structure.
+
+If using TypeScript, ensure types are installed from `npm install @netlify/edge-functions`.
+
+## Function Structure & Placement
+
+**Default directory:** `netlify/edge-functions/` (relative to site base directory)
+
+**Naming conventions:**
+- Use `.ts` (TypeScript, recommended) or `.js` (JavaScript) extensions (not `.mts`/`.mjs` — Deno natively supports ESM)
+- Filename becomes the function name
+- One default export per file
+
+**Valid function paths:**
+- `netlify/edge-functions/hello.ts`
+- `netlify/edge-functions/hello/index.ts`
+- `netlify/edge-functions/hello/hello.ts`
+
+**Custom directory** via `netlify.toml`:
+
+```toml
+[build]
+edge_functions = "my_edge_functions"
+```
+
+## Handler Signature
+
+```typescript
+export default async (req: Request, context: Context) => Response | void
+```
+
+The first argument is a standard Web API Request object. The second argument is a Netlify-specific `Context` object.
+Return a standard Web API Response, or return nothing to pass through to the next handler in the chain.
+
+```typescript
+import type { Context } from '@netlify/edge-functions'
+
+export default async (req: Request, context: Context) => {
+  const body = await req.json()
+  return Response.json({ received: body })
+}
+```
+
+## Deno Runtime & Module Support
+
+Edge functions use Deno as runtime and should attempt to use built-in methods where possible.
+
+### Node.js Built-in Modules
+
+Use the `node:` prefix to import Node.js built-in modules:
+
+```typescript
+import { Buffer } from 'node:buffer'
+import { randomBytes } from 'node:crypto'
+import process from 'node:process'
+```
+
+### npm Packages (beta)
+
+Install via `npm install` and import by package name:
+
+```typescript
+import lodash from 'lodash'
+```
+
+Some npm packages with native binaries (e.g., Prisma) or dynamic imports (e.g., cowsay) may not work.
+
+### Deno URL Imports
+
+Import modules directly by URL:
+
+```typescript
+import React from 'https://esm.sh/react'
+```
+
+### Import Maps
+
+Use an import map to alias third-party modules with shorthand names. Define mappings in a separate JSON file (not in
+`deno.json`):
+
+```json
+{
+  "imports": {
+    "html-rewriter": "https://ghuc.cc/worker-tools/html-rewriter/index.ts"
+  }
+}
+```
+
+Enable import maps in `netlify.toml`:
+
+```toml
+[functions]
+deno_import_map = "./path/to/your/import_map.json"
+```
+
+Then import by name:
+
+```typescript
+import { HTMLRewriter } from 'html-rewriter'
+```
+
+### Available Web APIs
+
+Edge functions have access to standard Web APIs:
+
+- **Fetch API:** `fetch`, `Request`, `Response`, `URL`, `File`, `Blob`
+- **Encoding:** `TextEncoder`, `TextDecoder`, `TextEncoderStream`, `TextDecoderStream`, `atob`, `btoa`
+- **Crypto:** `crypto.randomUUID()`, `crypto.getRandomValues()`, `crypto.subtle` (SubtleCrypto)
+- **Streams:** `ReadableStream`, `WritableStream`, `TransformStream`
+- **Timers:** `setTimeout`, `clearTimeout`, `setInterval`
+- **Other:** `console.*`, `Performance`, `WebSocket`, `URLPattern`
+
+## In-Code Config & Routing
+
+Prefer to use in-code configuration via exporting a `config` object. Prefer to provide a friendly path using the
+config object. `path` and `excludedPath` support substring patterns or the URLPattern syntax from the web platform.
+Unless explicitly asked to modify other properties, only set `path`, `pattern`, `excludedPath` when creating functions.
+
+```typescript
+import type { Config } from '@netlify/edge-functions'
+
+export default async (req: Request, context: Context) => {
+  return new Response('Hello from the edge')
+}
+
+export const config: Config = {
+  path: '/api/edge/*',
+}
+```
+
+**Config properties:**
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `path` | `string \| string[]` | URLPattern expression for paths. Must start with `/` |
+| `excludedPath` | `string \| string[]` | Paths to exclude from execution. Must start with `/` |
+| `pattern` | `RegExp \| RegExp[]` | Regex for path matching (alternative to `path`) |
+| `excludedPattern` | `RegExp \| RegExp[]` | Regex patterns to exclude |
+| `method` | `string \| string[]` | HTTP method(s) to match (`GET`, `POST`, etc.) |
+| `onError` | `'bypass' \| 'fail'` | Error behavior (`'bypass'` serves static/origin) |
+| `cache` | `'manual'` | Enables CDN response caching |
+
+**Route parameters:**
+
+```typescript
+// :param - named parameter
+export const config: Config = { path: '/api/users/:id' }
+// context.params.id = '123' for /api/users/123
+
+// * - wildcard
+export const config: Config = { path: '/api/*' }
+// Matches /api/anything/here
+```
+
+**Multiple paths:**
+
+```typescript
+export const config: Config = {
+  path: ['/api/edge/:name', '/edge/:name'],
+}
+```
+
+## Context Object
+
+The `context` parameter provides Netlify-specific metadata. All standard context properties are available:
+
+### Standard Properties
+
+```typescript
+context.ip            // string - client IP address
+context.geo.city      // string - city name
+context.geo.country   // { code: string, name: string } - ISO 3166
+context.geo.latitude  // number
+context.geo.longitude // number
+context.geo.subdivision // { code: string, name: string } - ISO 3166
+context.geo.timezone  // string - IANA timezone
+context.geo.postalCode // string
+context.site.id       // string - unique site ID
+context.site.name     // string - site subdomain name
+context.site.url      // string - primary site URL
+context.deploy.context   // string - e.g., 'production', 'deploy-preview'
+context.deploy.id        // string - unique deploy ID
+context.deploy.published // boolean - is this the published deploy?
+context.account.id    // string - team/account ID
+context.requestId     // string - unique request identifier
+context.params        // route parameters from config.path
+context.server.region // string - e.g., 'us-east-1'
+```
+
+### `context.cookies`
+
+Simplified cookie interface:
+
+```typescript
+const session = context.cookies.get('session')
+context.cookies.set({ name: 'session', value: 'abc123', path: '/', httpOnly: true })
+context.cookies.delete('session')
+```
+
+### `context.waitUntil(promise)`
+
+Extends execution after the response is sent:
+
+```typescript
+export default async (req: Request, context: Context) => {
+  context.waitUntil(
+    fetch('https://analytics.example.com/track', {
+      method: 'POST',
+      body: JSON.stringify({ path: new URL(req.url).pathname }),
+    }),
+  )
+  return new Response('OK')
+}
+```
+
+### Edge-Only: `context.next()`
+
+Passes the request to the next edge function in the chain or to the origin.
+
+**IMPORTANT:** When the goal is to skip edge function execution and let the request proceed normally, prefer an empty
+`return` (or `return undefined`) over `return context.next()`. An empty return is the most performant way to terminate
+execution — calling `context.next()` when you don't need the response is unnecessary and slows down overall execution.
+
+ONLY use `context.next()` when you need to read or modify the upstream response (e.g., adding headers, transforming
+the body). Note that empty returns don't set cache-control headers, so the function will always execute on every
+request. To cache responses, you must use `context.next()`, set appropriate cache headers, and return it explicitly.
+
+```typescript
+// GOOD: Skip execution and let the request proceed (most performant)
+export default async (req: Request, context: Context) => {
+  if (!shouldProcess(req)) {
+    return  // terminates execution, request proceeds normally
+  }
+  // ... process request
+}
+
+// GOOD: Modify the upstream response (valid use of context.next())
+export default async (req: Request, context: Context) => {
+  const response = await context.next()
+  response.headers.set('x-custom-header', 'value')
+  return response
+}
+```
+
+Optionally use conditional requests:
+
+```typescript
+const response = await context.next({ sendConditionalRequest: true })
+```
+
+### Edge-Only: `context.nextRequest()`
+
+Passes a modified request to the next handler:
+
+```typescript
+export default async (req: Request, context: Context) => {
+  const modifiedReq = new Request(req.url, {
+    headers: { ...Object.fromEntries(req.headers), 'x-added': 'true' },
+  })
+  return context.nextRequest(modifiedReq)
+}
+```
+
+## Global `Netlify` Object
+
+Available in all edge function contexts:
+
+### `Netlify.env`
+
+Access environment variables:
+
+```typescript
+const apiKey = Netlify.env.get('API_KEY')     // string | undefined
+const exists = Netlify.env.has('API_KEY')      // boolean
+const all = Netlify.env.toObject()             // Record<string, string>
+
+// Scoped to current invocation only
+Netlify.env.set('TEMP_VAR', 'value')
+Netlify.env.delete('TEMP_VAR')
+```
+
+ONLY use `Netlify.env.*` for interacting with environment variables in code. Do not use `process.env` or `Deno.env`.
+
+### `Netlify.context`
+
+Same as the `context` parameter in the handler. Available from outside the handler scope (e.g., imported modules).
+Returns `null` outside a function invocation.
+
+## netlify.toml Configuration
+
+ONLY use `netlify.toml` `[[edge_functions]]` blocks for precise function execution order control. DO NOT use
+`netlify.toml` if there are no edge function ordering requirements. When controlling order, include all edge functions.
+
+```toml
+[[edge_functions]]
+function = "auth"
+path = "/admin"
+
+[[edge_functions]]
+function = "injector"
+path = "/admin"
+cache = "manual"
+
+[[edge_functions]]
+function = "auth"
+path = "/blog/*"
+
+[[edge_functions]]
+function = "rewriter"
+path = "/blog/*"
+
+[[edge_functions]]
+function = "highlight"
+pattern = "/products/(.*)"
+excludedPattern = "/products/things/(.*)"
+
+[[edge_functions]]
+function = "common"
+path = "/*"
+excludedPath = "/img/*"
+```
+
+**Edge function properties in `netlify.toml`:**
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `function` | `string` | Name of the edge function |
+| `path` | `string` | URL pattern to trigger the function (must start with `/`) |
+| `excludedPath` | `string \| string[]` | Routes to exclude from `path` |
+| `pattern` | `string` | Regex-based path matching |
+| `excludedPattern` | `string \| string[]` | Regex patterns to exclude |
+| `cache` | `string` | Set to `'manual'` to enable response caching |
+
+## Execution Order
+
+When multiple edge functions match the same path, they execute in this order:
+
+1. Configuration-based edge functions (`netlify.toml`) run first
+2. Framework-generated edge functions execute before user-defined functions
+3. Non-cached edge functions execute before cached (`cache: 'manual'`) functions
+4. Inline-declared `config` exports override duplicate `netlify.toml` declarations for the same function
+5. Multiple inline edge functions sort alphabetically by filename
+
+## Caveats
+
+- If an edge function returns a response, redirects for that path DO NOT occur
+- Edge functions DO NOT execute for rewritten static routing targets
+- `fetch()` or `new URL()` with the same site origin triggers a new request chain, re-running matching functions.
+  Use `context.next()` to continue processing instead of re-triggering functions
+- Can only rewrite requests to same-site URLs (use `fetch()` for external content)
+- Cached edge function responses override existing static files at the same path
+- Function failure behavior depends on the `onError` configuration
+
+## Limits
+
+| Resource | Limit |
+|----------|-------|
+| Code size (compressed) | 20 MB |
+| Memory per deployment | 512 MB |
+| CPU time per request | 50 ms (excludes waiting time) |
+| Response header timeout | 40 seconds |
+
+**Incompatibilities:**
+- Netlify's split testing feature
+- Custom headers from `_headers` or `netlify.toml` config (use response headers in code instead)
+- Netlify prerendering on paths served by edge functions
+- Not included in Netlify's HIPAA-compliant hosting offering
+
+**Restrictions:**
+- Can only rewrite requests to same-site URLs
+- Cached edge functions override existing static files
+- No local caching in development (HTTP cache headers are ignored locally)
+- Multiple framework adapters may generate conflicting edge functions
+
+## Common Errors & Solutions
+
+### "Edge function not found"
+
+**Cause:** Function file not in the correct directory or missing `config.path`.
+
+**Fix:**
+
+1. Place function in `netlify/edge-functions/` (or configured directory)
+2. Use `.ts` or `.js` extension
+3. Ensure the file has a default export
+4. Ensure the function exports a `config` with a `path` or `pattern`
+
+### "CPU time exceeded" (50ms limit)
+
+**Cause:** Function CPU-intensive work exceeds the 50ms CPU time limit.
+
+**Fix:**
+
+1. Optimize hot paths — the 50ms limit is CPU time only, not wall-clock time
+2. Waiting on `fetch()`, `context.next()`, or other I/O does not count against the CPU limit
+3. For heavy computation, offload to a serverless function instead
+
+### Module import failures
+
+**Cause:** Incompatible npm package or incorrect import syntax.
+
+**Fix:**
+
+1. Use `node:` prefix for Node.js built-in modules (`node:crypto`, not `crypto`)
+2. Check that npm packages do not rely on native binaries or unsupported dynamic imports
+3. For Deno URL imports, ensure the URL is accessible and returns valid ESM
+
+### "CORS errors" in browser
+
+**Cause:** Missing CORS headers on function response. NEVER add CORS headers unless explicitly requested by the user.
+
+**Fix** (only when user asks for CORS support):
+
+```typescript
+return new Response(JSON.stringify(data), {
+  headers: {
+    'Content-Type': 'application/json',
+    'Access-Control-Allow-Origin': '*',
+  },
+})
+```
+
+### Environment variable is undefined
+
+**Cause:** Variable not available in the function context.
+
+**Fix:**
+
+1. Use `Netlify.env.get('VAR_NAME')` — do not use `process.env` or `Deno.env`
+2. Ensure the variable is set in Netlify UI with correct scopes (Runtime)
+3. Deploy to Netlify for env var injection