Adding an Edge Function

When a write needs secrets, external HTTP, or multi-step logic → it's an Edge Function. See Backend for the model and Shared Kit for utilities.

1. Pick the type & name

Type	When	Name pattern	verify_jwt
Type A	user-facing (has a JWT)	domain-action	true
Type B	cron / internal (service-role)	domain-noun-verb	false
Webhook	external caller	—	false

2. Scaffold

supabase/functions/{name}/
  index.ts       ← entrypoint (shared skeleton)
  helpers.ts     ← complex business logic
  tests/         ← Deno tests (mandatory)

3. Write the entrypoint

import { handleCors } from '../_shared/cors.ts'
import { requireAuth } from '../_shared/auth.ts'      // requireAdmin | optionalAuth
import { ValidationError } from '../_shared/errors.ts'
import { ok, err } from '../_shared/response.ts'

Deno.serve(async (req) => {
  const preflight = handleCors(req); if (preflight) return preflight
  try {
    const { user, serviceClient } = await requireAuth(req)
    const body = await req.json()
    if (!body.action) throw new ValidationError('action is required.')
    // ...business logic (complex parts in helpers.ts)
    return ok({ result })
  } catch (e) {
    return err('{name}', e)
  }
})

Add a JSDoc header (name, purpose, Type, request/response shapes). docs:gen reads the first real sentence of it for the EF index.

4. Config

• Set verify_jwt for the function in supabase/config.toml.
• Pin @supabase/supabase-js to the single repo version (2.30.0).
• Register the name in the feature EDGE_FN map (UPPER_SNAKE_CASE key) — never inline the string.

5. Tests (mandatory, green before deploy)

Co-located Deno tests/ covering: success, validation failure, auth/authz failure, safe 500 (no leakage), edge cases.

npm run test:ef      # deno test --allow-env --allow-net (from supabase/functions)

6. Deploy & promote

npm run functions:deploy -- --project-ref <dev-ref>  --only {name}   # Dev first
npm run functions:deploy -- --project-ref <prod-ref> --only {name}   # then Prod

Explicit --project-ref is always required. Promote to both projects deliberately — Deployment & Promotion.

7. Docs

npm run docs:gen     # refresh the EF index

Add a per-function contract page from the EF template if the function is non-trivial. Update EDGE_FUNCTION_GUIDELINES.md if a standard changed.

Checklist