netlify-edge-functions

Write, route, cache, and debug Netlify Edge Functions, the Deno-based TypeScript or JavaScript handlers in netlify/edge-functions that run at the network edge in front of static files and serverless functions. Activate this skill whenever someone wants to add auth middleware or a login gate, redirect or rewrite visitors by country or cookie, localize or personalize a page with geolocation, run A/B testing, transform or inject HTML into a response, stream server-side rendering at the edge, or cache an edge response. Also use it when an edge function silently does nothing, runs in the wrong order, ignores its Cache-Control headers, or cannot read an environment variable.

3,089
installs: 0 up / 0 down, score 0.00
votes: 41
repo stars
Updated: less than a month ago
In the catalog since: 1 Oct 2026
From: netlify/context-and-tools

Get it through your agent npx skills add netlify/context-and-tools@netlify-edge-functions

Skill instructions

Rendered from the published SKILL.md, 355 lines.

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

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

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(",");

Show the whole skill (235 more lines)

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
```ts
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`

Property	Notes
`cookies.get(name)` / `.set(options)` / `.delete(name \| options)`	`set` and `delete` use `CookieStore` option format; they act on the outgoing response
`geo`	`city`, `country.{code,name}`, `subdivision.{code,name}`, `latitude`, `longitude`, `timezone`, `postalCode` (format varies)
`ip`	client IP
`next(options?)` / `next(request, options?)`	`Promise<Response>` from the next item in the chain
`params`	URLPattern named groups from `path` (`/pets/:name` → `{ name }`). For the query string, use `request.url`
`user`	`{ id, email?, expiresAt }` or `undefined`. It is a Netlify account, not Netlify Identity; for Identity, use `getUser()` from `@netlify/identity`
`waitUntil(promise)`	runs after the response is sent
`requestId`, `account.id`, `server.region`	—
`site`	`{ id, name, url }`
`deploy`	`{ context, id, published, skewProtectionToken }`

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`

Key	Value
`path`	URLPattern string or array; must start with `/`
`excludedPath`	URLPattern string or array; must start with `/`
`pattern` / `excludedPattern`	regex alternatives to `path` / `excludedPath`
`method`	HTTP method string or array
`header`	`{ name: true \| false \| "regex" }`; case-insensitive names; multi-value headers match the comma-joined list
`onError`	`"fail"` (default), `"/custom-path"`, or `"bypass"`
`cache`	`"manual"`

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.

Framework-generated functions declared in a config file.
Your netlify.toml declarations, top to bottom.
Framework- and integration-generated inline declarations.
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`)

Value	Effect
`"fail"` (default)	chain stops; generic error page is shown
`"/unavailable"`	rewrite to that same-site path; edge functions on it are not invoked
`"bypass"`	skip the failing function; chain continues

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

Limit	Value
Bundle size	20 MB compressed
Memory (per set of deployed functions)	512 MB
CPU time per request	50 ms (excludes I/O wait)
Response header timeout	40 s

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.

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.
Scope path narrowly. path: "/*" intercepts every request — including static assets — adding latency to each one and billing an edge invocation for it.
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.
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.
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.
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.
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.

Get it through your agent

Call the Graph-of-Skills MCP server's retrieve_skill_bundle tool and it returns this skill's text inside your budget.

{
  "tool": "retrieve_skill_bundle",
  "arguments": {
    "query": "netlify-edge-functions"
  }
}

New to this? Set up Graph-of-Skills or get a free key. The text on this page comes from its authors: how skills are sourced and what we check. If none fits your task, your agent can write a skill for your own library. To keep a skill from your own library on a machine, see how to install one of your skills.

Share on X Share on LinkedIn Share on Bluesky Share on Hacker News

Share on Reddit

Source

Source repository netlify/context-and-tools
Listing on skills.sh

From netlify/context-and-tools via skills.sh

Related skills

netlify-functions
Write, configure, and deploy Netlify serverless functions in TypeScript, JavaScript, or Go. Use this when adding an API endpoint or backend route, adding a contact form handler, wiring auth or Identity signup/login hooks, identifying which Netlify user is calling a private or team-login-protected app, building streaming or AI-proxy responses, scheduling cron jobs, running long background jobs (batch processing/scraping), reacting to deploy or form events, setting up rate limiting or region/memory config, or reading environment variables and secrets inside a function. Covers file locations, the Request/Context/Response handler shape, path routing, config options, and local testing with netlify dev.
3,226 installs
netlify-config
Configure Netlify builds and routing via netlify.toml, _redirects, and _headers. Use when setting a build command or publish directory, adding redirects or rewrites or proxies, adding an SPA fallback rewrite, setting custom response headers or basic auth, managing environment variables and secrets, scoping vars per deploy context, marking a var as secret, disabling secret scanning, configuring functions bundling, ignoring builds, or wiring up a monorepo or JavaScript SPA on Netlify.
3,279 installs
supabase-server
Use when planning or writing server-side code that uses `@supabase/server` — Edge Functions, Hono apps, webhook handlers, or any backend that creates Supabase clients or validates inbound auth. Trigger **before** writing or modifying any file that imports from `@supabase/server` (or sub-paths like `@supabase/server/core`); calls `withSupabase`, `createSupabaseContext`, `createAdminClient`, `createContextClient`, `verifyAuth`, `verifyCredentials`, or `extractCredentials`; configures an `auth:` mode (`'none'` | `'publishable'` | `'secret'` | `'user'`, or keyed variants like `'secret:*'`); or lives under `supabase/functions/` and authenticates an inbound request. Also trigger during planning — if a plan mentions any of the above, load the skill before drafting code; do not extrapolate `auth:` values or auth modes from neighboring functions. Also trigger when you see legacy patterns to migrate to this package — `Deno.serve`, `createClient(Deno.env.get('SUPABASE_URL'))`, imports from `esm.sh/@supabase` or `deno.land/std`, usage of `SUPABASE_ANON_KEY` / `SUPABASE_SERVICE_ROLE_KEY`, or the deprecated `allow:` config option / removed `'always'` / `'public'` mode values / removed `authType` field.
9,655 installs
node
Provides domain-specific best practices for Node.js development with TypeScript, covering type stripping, async patterns, error handling, streams, modules, testing, performance, caching, logging, and more. Use when setting up Node.js projects with native TypeScript support, configuring type stripping (--experimental-strip-types), writing Node 22+ TypeScript without a build step, or when the user mentions 'native TypeScript in Node', 'strip types', 'Node 22 TypeScript', '.ts files without compilation', 'ts-node alternative', or needs guidance on error handling, graceful shutdown, flaky tests, profiling, or environment configuration in Node.js. Helps configure tsconfig.json for type stripping, set up package.json scripts, handle module resolution and import extensions, and apply robust patterns across the full Node.js stack.
5,855 installs
convex-functions
Writes Convex queries, mutations, actions, and internal functions in the object form with args and returns validators, correct ctx usage, runtime boundaries, and error handling. Use when adding or changing anything in convex/*.ts that exports a function, or when deciding between query, mutation, and action.
3,206 installs

More from netlify/context-and-tools

netlify-deploy
Create, configure, and manage Netlify deploys from code — reach for this when setting up Git continuous deployment, running netlify deploy or netlify deploy --prod from the CLI, writing netlify.toml deploy contexts, adding a Deploy to Netlify button, wiring build hooks, configuring Deploy Previews or branch deploys, locking or skipping deploys, fixing a failed or secrets-scanning deploy, or when someone asks to "deploy my site", "set up preview deploys", "add per-branch build config", "keep staging out of Google", or "add a deploy button to my README".
3,351 installs
netlify-config
Configure Netlify builds and routing via netlify.toml, _redirects, and _headers. Use when setting a build command or publish directory, adding redirects or rewrites or proxies, adding an SPA fallback rewrite, setting custom response headers or basic auth, managing environment variables and secrets, scoping vars per deploy context, marking a var as secret, disabling secret scanning, configuring functions bundling, ignoring builds, or wiring up a monorepo or JavaScript SPA on Netlify.
3,279 installs
netlify-functions
Write, configure, and deploy Netlify serverless functions in TypeScript, JavaScript, or Go. Use this when adding an API endpoint or backend route, adding a contact form handler, wiring auth or Identity signup/login hooks, identifying which Netlify user is calling a private or team-login-protected app, building streaming or AI-proxy responses, scheduling cron jobs, running long background jobs (batch processing/scraping), reacting to deploy or form events, setting up rate limiting or region/memory config, or reading environment variables and secrets inside a function. Covers file locations, the Request/Context/Response handler shape, path routing, config options, and local testing with netlify dev.
3,226 installs
netlify-frameworks
Deploy and configure web frameworks on Netlify — build settings and SSR/edge adapters plus local platform emulation and env vars. Use when setting up or fixing a framework deploy (Next.js / Astro / Nuxt / SvelteKit / Remix / React Router / TanStack Start / SolidStart / Gatsby / Angular / Vite / Express / Hydrogen / Hugo / Eleventy / Vue / React), adding SSR or edge functions or middleware wired to Netlify context, fixing SPA redirect and catch-all rules, setting a build command or publish directory, or debugging "why isn't my env var updating" and framework build failures.
3,163 installs
netlify-forms
Serverless form handling on Netlify-hosted sites — detects HTML forms at deploy time, stores submissions, filters spam, and sends notifications. Use when adding a contact form, lead-capture form, file-upload form, or newsletter signup to a Netlify site; wiring AJAX form submission; setting up a custom thank-you page; adding a honeypot or reCAPTCHA to a form; getting forms working in Next.js, Nuxt, SvelteKit, Astro, or Gatsby; reading form submissions via the Netlify API; setting up submission notifications or ChatGPT automations on form submission events; or debugging missing submissions and forms that silently fail to register.
3,085 installs

Content is provided as published by its creators; you are responsible for how you use it.

To request removal, use the contact form.