netlify/context-and-tools/netlify-edge-functions

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 named config export with the route. Alternatively, declare the route in netlify.toml.
• The default export can also be a Fetchable module: an object with a fetch method. Netlify calls fetch with the same (request, context) arguments and uses its return value the same way; inside fetch, this is the exported object. Use it to share one handler with other platforms that accept Fetchable modules.

``ts export default { async fetch(request: Request, context: Context) { return new Response("Hello"); }, }; export const config: Config = { path: "/hello" }; // still a named export ``

• 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" } });