Edge Functions skill for Codex

Edge code earns its place when it answers from data that is already at the edge (cache, KV, the request itself) or decides quickly where a request should go. It loses when it makes several round trips to a database in one region. A good edge function is small, uses only Web-standard APIs, finishes in a few milliseconds of CPU, and has a tested fallback when a binding or upstream is unavailable.

Inspect first

1. Read AGENTS.md, the framework and hosting config (wrangler.jsonc, vercel.json, netlify.toml, next.config, supabase/functions/), and which routes already run at the edge (export const runtime = "edge", middleware or proxy files, edge function directories).
2. List the data each candidate route touches and where that data lives (region of the database, KV, cache, third-party API).
3. Check the dependencies the route imports. Anything using fs, net, child_process, native addons or large SDKs will not run or will blow the bundle limit.

Should this run at the edge?

Route does	Edge?
Redirects, rewrites, header changes, bot or geo blocking	Yes
Auth gate that verifies a JWT signature locally (no DB call)	Yes
A/B bucketing, feature flags from an edge store	Yes
Personalizing cached HTML with small fragments (HTMLRewriter, streaming)	Yes
Read from an edge KV or cache, fall back to origin	Yes
One query to a regional database	Maybe: only with an HTTP driver or pooler, and placement near the DB
Several sequential database queries, ORM-heavy pages	No: run regionally next to the database
CPU-heavy work (image processing, PDF, large JSON transforms)	No
Long-running jobs, websockets with server state	No, or use Durable Objects / a dedicated service

If the answer is “maybe”, measure: time to first byte from three regions, edge versus regional, with the real database.

Runtime constraints that bite

• No filesystem, no child_process, no raw TCP in most runtimes. Cloudflare offers connect() for TCP and a nodejs_compat flag for many Node built-ins; others vary.
• CPU time per request is capped (milliseconds on free tiers). Await-time on fetch usually does not count against CPU, but wall-clock limits still apply.
• Bundle size caps are a few MB compressed. Tree-shake and avoid SDKs that pull in Node polyfills; use the provider REST API with fetch instead.
• Global variables persist only for the lifetime of an isolate. They are a cache, never a store, and different requests may share or not share them.
• eval and new Function are blocked in several runtimes; some template engines and schema validators that compile code at runtime will fail.

For per-provider limits, placement controls and entry-point signatures, read references/provider-runtimes.md when targeting a specific platform or comparing two.

Portable handler shape

Write the core as a pure (Request) => Promise<Response> and adapt per provider:

// src/edge/handler.ts
import { jwtVerify, createRemoteJWKSet } from "jose";

const JWKS = createRemoteJWKSet(new URL("https://auth.example.com/.well-known/jwks.json"));
const CHECKOUT_BLOCKED = new Set<string>(["XX"]); // ISO codes from legal or compliance, not guesses

export async function handle(req: Request, country: string | undefined): Promise<Response | null> {
  const url = new URL(req.url);

  if (country && CHECKOUT_BLOCKED.has(country) && url.pathname.startsWith("/checkout")) {
    return new Response("Not available in your region", { status: 451 });
  }

  if (url.pathname.startsWith("/app")) {
    const token = req.headers.get("cookie")?.match(/(?:^|;\s*)session=([^;]+)/)?.[1];
    if (!token) return Response.redirect(new URL("/login", url), 302);
    try {
      await jwtVerify(token, JWKS, { issuer: "https://auth.example.com", audience: "web" });
    } catch {
      return Response.redirect(new URL("/login", url), 302);
    }
  }
  return null; // continue to origin
}

// Cloudflare Worker adapter
export default {
  async fetch(req: Request, env: Env, ctx: ExecutionContext) {
    return (await handle(req, req.cf?.country as string | undefined)) ?? fetch(req);
  },
};

jose works in every Web-standard runtime because it uses crypto.subtle. Prefer libraries that state edge or Workers support.

Sticky A/B bucketing

function bucket(req: Request): { variant: "a" | "b"; setCookie?: string } {
  const existing = req.headers.get("cookie")?.match(/(?:^|;\s*)ab_home=(a|b)/)?.[1] as "a" | "b" | undefined;
  if (existing) return { variant: existing };
  const variant = crypto.getRandomValues(new Uint8Array(1))[0] < 128 ? "a" : "b";
  return { variant, setCookie: `ab_home=${variant}; Path=/; Max-Age=2592000; SameSite=Lax; Secure` };
}

Rewrite to /home-a or /home-b so each variant stays cacheable on its own URL; never vary the cache on the cookie itself.

Data access from the edge

Option	Use when
Edge KV / Edge Config / cache API	Read-mostly config, flags, rendered fragments
HTTP database drivers (Neon serverless, PlanetScale, Turso/libSQL, Supabase REST)	One or two queries per request
Connection pooler close to the DB (Cloudflare Hyperdrive, PgBouncer, Prisma Accelerate)	Existing Postgres with TCP drivers
Run the function near the DB (Cloudflare Smart Placement, Vercel function region)	Many queries; you keep edge routing but compute moves to the data

Never open a fresh TCP connection to a regional Postgres from hundreds of edge locations per request; connection storms take the database down.

Background work

Use the runtime’s waitUntil for logging, analytics and cache writes after the response: ctx.waitUntil(...) on Workers, context.waitUntil on Netlify, waitUntil from @vercel/functions on Vercel. Unawaited promises without it may be cancelled.

Verification

• Local runtime test, not Node: wrangler dev or @cloudflare/vitest-pool-workers, netlify dev, vercel dev, supabase functions serve, deno test.
• Bundle size checked against the plan limit (wrangler deploy --dry-run --outdir dist then inspect, or the build output size report).
• TTFB compared from at least three regions before and after the move (curl -w "%{time_starttransfer}\n" -o /dev/null -s <url> from each, or a synthetic monitor).
• Failure path tested: upstream down, missing cookie, invalid JWT, unknown country.
• Production deploys only after explicit user approval.

Gotchas

• Middleware that runs on every request, including static assets, adds latency and cost. Restrict it with a matcher to the paths that need it.
• Response.redirect requires an absolute URL in several runtimes; build it with new URL(path, req.url).
• Date.now() and timers may be coarse or frozen during a request in some isolates (a Spectre mitigation); do not use them for fine-grained benchmarking inside the function.
• Environment variables are read differently per runtime (env binding in Workers, Netlify.env.get, Deno.env.get, process.env on Vercel). Centralize access behind one helper.
• Geolocation headers are best-effort; never use them as an authorization control.