Netlify Edge Functions

Use this form

// 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

Return values

Endpoint

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

Redirect / rewrite

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)

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

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

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)

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 });
  const allowed = (Netlify.env.get("ADMIN_USER_IDS") ?? "").split(",");
  if (!allowed.includes(user.id)) return new Response("Forbidden", { status: 403 });
  // user.email may be undefined, so use it for display only
};
export const config: Config = { path: "/admin/*" };

Post-response work

export default async (req: Request, context: Context) => {
  context.waitUntil(fetch("https://analytics.example.com/event", { method: "POST" }));
  return new Response("ok");
};

waitUntil does not block the response, but it still counts against the 50 ms CPU limit.

Streaming SSR (.tsx)

import React from "https://esm.sh/react";
import { renderToReadableStream } from "https://esm.sh/react-dom/server";
import type { Config, Context } from "@netlify/edge-functions";

export default async (req: Request, context: Context) => {
  const stream = await renderToReadableStream(
    <html><body><h1>Hello {context.geo.country?.name}</h1></body></html>
  );
  return new Response(stream, { headers: { "Content-Type": "text/html" } });
};
export const config: Config = { path: "/hello" };

Context

Netlify adds no client-info headers to the request. Read client info from context instead.

Netlify.context gives the same object, but only inside the handler. Outside it, it is null.

Netlify.env: get(name), has(name), toObject(), and invocation-scoped set and delete. To change variables persistently, use the env API.

Web APIs:

• console, atob, btoa
• fetch, Request, Response, URL, File, Blob
• TextEncoder/TextDecoder (and their Stream variants), Performance
• Web Crypto: randomUUID, getRandomValues, SubtleCrypto
• WebSocket
• setTimeout, clearTimeout, setInterval
• Streams: ReadableStream, WritableStream, TransformStream
• URLPattern

Modules:

• Node built-ins: use the node: prefix (import { randomBytes } from "node:crypto").
• Deno modules: import by URL, or through an import map.
• npm packages (beta): import by name. Packages with native binaries or runtime dynamic imports may break.

Declarations

Inline config

export const config: Config = {
  path: "/*",
  excludedPath: ["/*.css", "/*.js", "/img/*"],
  header: { "user-agent": "(iPhone|Android)" },
};

The netlify-agent-category request header maps any user-agent to a client category.

netlify.toml

The toml form supports function, path, excludedPath, pattern, excludedPattern, [edge_functions.header], and cache. Set onError inline. Use toml when you need explicit ordering of several functions on one path.

[[edge_functions]]
  path = "/admin"
  function = "auth"

[[edge_functions]]
  path = "/admin"
  function = "injector"
  cache = "manual"

[[edge_functions]]
  pattern = "/products/(.*)"
  excludedPattern = "/products/things/(.*)"
  function = "highlight"

[[edge_functions]]
  path = "/*"
  excludedPath = "/img/*"
  function = "common"
  [edge_functions.header]
  x-required = true
  x-forbidden = false

A request to /admin runs auth, then common, then injector.

Order

Netlify walks the following order twice for the request path. The first pass runs only functions without caching configured. The second pass runs only cached functions.

1. Framework-generated functions declared in a config file.
2. Your netlify.toml declarations, top to bottom.
3. Framework- and integration-generated inline declarations.
4. Your inline declarations, alphabetical by file name.

If the same function is declared both in toml and inline, the configs are merged and treated as step 4; inline wins for duplicate fields.

After the edge functions, redirect rules run, unless a function already returned a Response. A redirect to a new path repeats the whole process for that path.

An edge function declared on the target of a static rewrite does not run for rewritten requests.

Response caching

import type { Config } from "@netlify/edge-functions";

export default async () =>
  new Response("Hello world", { headers: { "cache-control": "public, s-maxage=3600" } });

export const config: Config = { path: "/hello", cache: "manual" };

• Headers must be set in the function code. Supported headers:
  • Cache-Control, CDN-Cache-Control, Netlify-CDN-Cache-Control
  • Expires (overridden by max-age/s-maxage)
  • Vary, Netlify-Vary
• See caching overview.
• A new deploy in the same deploy context invalidates cached responses.
• Cached hits skip invocation, and they do not count toward invocation limits.
• Cache reusable endpoint output, such as SSR.
• Don't cache routing or personalization middleware, such as cookie-based product ordering.
• Local dev has no cache. Cache headers are ignored locally.

Error handling (onError)

Fail closed for critical logic: use the default for internal auth, or a custom path for customer-facing auth. Fail open (bypass) for nice-to-haves such as localization.

Environment variables

• Variables must have the Functions scope.
• Build-scoped variables exist only at build time; embed their values during the build if needed.
• Changing a variable requires a new deploy.
• Deploy info (site, region, deploy id) comes from context, not from env vars.

Local dev / deploy / logs

• Run npm install netlify-cli -g, then netlify dev. Visit http://localhost:8888/<path>.
  • Changes apply on the next request.
  • Debug with --edge-inspect or --edge-inspect-brk.
  • Mock location with --geo=mock (San Francisco), or --geo=mock --country=DE.
  • context.user is undefined locally.
• Manual deploys require CLI ≥ 12.2.8. Deploys are atomic, and Deploy Previews and rollbacks include edge functions.
• Logs: in the Netlify UI, go to Cloud compute > Edge functions (https://app.netlify.com/projects/{site_name}/edge-functions).
  • For older deploys: Deploys → open the deploy → Edge Functions.
  • console.log output is tagged with the function name.
  • Retention is ≥ 24 h (7 days on some plans).
  • Log Drains are available on Enterprise plans.

Limits

• Prerendering does not apply to paths served by an edge function.
• Multiple framework plugins that generate edge functions may collide.

Docs: API · Declarations · Optional configuration · Limits · Examples

Netlify house rules (edge-functions)

These are org conventions and field-learned guardrails, not docs facts — they are merged into the rendered skill by ctx-gen and are never generated. Extracted from the previous hand-written netlify-edge-functions skill; owned by the skills maintainer.

1. Check the framework's adapter/reference first: a custom edge function that duplicates adapter-generated middleware causes conflicts. Only hand-write an edge function when the framework doesn't already generate one for the job.
2. Scope path narrowly. path: "/*" intercepts every request — including static assets — adding latency to each one and billing an edge invocation for it.
3. An edge function without a route (no config export, no netlify.toml declaration) still deploys, but silently never runs: no build error, no warning. When "my edge function does nothing", check the route first.
4. Choose edge vs serverless by workload shape: edge functions for low-latency request/response manipulation, geolocation logic, auth checks/redirects, and A/B personalization; serverless functions for long-running work (up to 15 min), heavy Node.js dependencies, database-heavy operations, background/scheduled tasks, or memory needs above 512 MB.
5. Cache headers on an edge response do nothing without cache: "manual" in config — it's both or neither. Setting Cache-Control on the returned Response has no effect unless the function also opts in.
6. When explaining declaration processing order, state the two-pass loop, not just the ordering: Netlify runs the whole declaration order TWICE — first pass runs only edge functions not configured for caching, second pass runs the ones with caching configured. "Non-cached before cached" without the loop framing is an incomplete answer.
7. On a private project or one with team login protection, context.user is the Netlify user who made the request (id, email, expiresAt). Use it for per-person checks and personalization instead of adding a second login, and never take identity from client-sent headers or cookies: Netlify verifies the login before the edge function runs. Every example must handle context.user being undefined (public projects, basic password protection, netlify dev), and email can be undefined too, so key decisions on id. This is a Netlify account, not a Netlify Identity user.