netlify-edge-functions

Files (1)

• SKILL.md

SKILL.md (first lines)

# Netlify Edge Functions

## Use this form

```ts
// netlify/edge-functions/hello.ts
import type { Config, Context } from "@netlify/edge-functions";

export default async (request: Request, context: Context) => {
  return new Response(`Hello from ${context.geo.country?.name ?? "somewhere"}`);
};

export const config: Config = { path: "/hello" };
```

- One file = one function: a default-export handler plus a `config` export with the route. Alternatively, declare the route in `netlify.toml`.
- `Request` and `Response` are global. Import `Context` and `Config` types from `@netlify/edge-functions`.
- Read env vars with `Netlify.env.get()`. `process.env` works only for Next.js middleware.

**Avoid these:**
- A file with no `config.path` or `pattern` and no `[[edge_functions]]` entry. It deploys but never runs.
- Import maps in `deno.json`. They are unsupported. Use a separate file with `[functions] deno_import_map`.
- Variables set in `netlify.toml`. They are invisible to edge functions.
- `Netlify.env.set()` or `Netlify.env.delete()` as persistence. They affect only the current invocation.
- `fetch()` to the same site for the current path. Use `context.next()` instead.

## ⚠️ Footguns

- **No route = silent no-op.** Edge functions get no automatic URL.
- **`path: "/*"` runs on every request**, including assets. Narrow it, or add `excludedPath`.
- **Caching needs both parts:** `cache: "manual"` in config AND cache headers on the returned `Response`. With only one, nothing is cached.
- **Cached functions shadow static files.** A cached function on `/*` serves `/cat.png` instead of the file.
- **Returning a `Response` ends the chain.** Redirect rules for that path never run.
- **Same-site `fetch()` and `URL` rewrites start a new request chain.** Matching edge functions run again. Use `context.next()` to reach the static asset or serverless function at the same path.
- **The request body can be read once.** After `await req.json()`, pass `new Request(req, { body })` to `context.next()`.
- **Same-named `foo.ts` and `foo.js`:** the TS file is ignored and the JS file deploys.
- **50 ms CPU per request**, including `waitUntil` work.
- **Not executed** on sites with Split Testing enabled.
- **Custom Headers and basic-auth headers do not apply** to edge functions.
- **Not supported** on HIPAA-compliant hosting.
- **`netlify.app` is on the Public Suffix List.** Cross-subdomain cookies need a custom domain.

## Files

| What | Where |
|---|---|
| Functions | `<base>/netlify/edge-functions/*.{js,ts,jsx,tsx}` |
| Custom dir | `[build] edge_functions = "my-dir"` (relative to base dir; keep it outside the publish dir) |
| Name in toml | file name without extension (`auth.ts` → `function = "auth"`) |
| Import map | any JSON file, referenced by `[functions] deno_import_map = "./import_map.json"` |

## Return values

| Return | Effect |
|---|---|
| `Response` | sent to client; chain ends |
| `URL` | same-site rewrite, 200, address bar unchanged |
| `undefined` / `return;` | skip this function; chain continues |

### Endpoint
```ts
export default async () =>
  new Response("Hello, World!", { headers: { "content-type": "text/html" } });
export const config = { path: "/api/hello" };
```

### Redirect / rewrite
```ts
import type { Context } from "@netlify/edge-functions";

export default async (req: Request, { cookies, geo }: Context) => {
  if (geo.city === "Paris" && cookies.get("promo-code") === "15-for-followers") {
    return Response.redirect(new URL("/subscriber-sale", req.url)); // redirect
    // or: return new URL("/subscriber-sale", req.url);             // rewrite (same-site only)
  }
};
export const config = { path: "/sale" };
```
Rewrites must target the same site. To reach other sites, use `fetch`.

### Middleware (modify origin response)
```ts
import type { Context } from "@netlify/edge-functions";

export default async (request: Request, context: Context) => {
  if (new URL(request.url).searchParams.get("method") !== "transform") return;
  const response = await context.next();
  return new Response((await response.text()).toUpperCase(), response);
};
export const config = { path: "/blog/*" };
```
Call `context.next()` only when you need the response body. If you just return `undefined`, the chain continues on its own.

### Conditional requests
```ts
export default async (req: Request, { next }: Context) => {
  const res = await next({ sendConditionalRequest: true });
  if (res.status === 304) return res;
  return new Response((await res.text()).toUpperCase(), res);
};
```
By default, `next()` strips conditional headers, so it always returns a full response.

### Read body, then continue
```ts
export default async (req: Request, context: Context) => {
  const body = await req.json();
  if (!isValid(body.access_token)) return new Response("forbidden", { status: 403 });
  return context.next(new Request(req, { body: JSON.stringify(body) }));
};
```

### Netlify user gate (private / team-login-protected projects)
```ts
import type { Config, Context } from "@netlify/edge-functions";

export default async (req: Request, context: Context) => {
  const user = context.user; // undefined: public project, password protection, netlify dev
  if (!user) return new Response("Forbidden", { status: 403 });

From netlify/context-and-tools, MIT.

More from netlify/context-and-tools