Claude Code for Supabase Edge Functions — Guide

Written by Michael Lip · Solo founder of Zovo · $400K+ on Upwork · 100% JSS Join 50+ builders · More at zovo.one

The Setup

You are deploying serverless functions with Supabase Edge Functions, which run Deno-based TypeScript functions on the edge close to your users. Edge Functions integrate natively with Supabase’s database, auth, and storage services. Claude Code can create serverless functions, but it generates AWS Lambda or Vercel Functions code instead of Supabase’s Deno-based edge functions.

What Claude Code Gets Wrong By Default

  1. Writes Node.js Lambda handlers. Claude creates exports.handler = async (event, context) => {} for AWS Lambda. Supabase Edge Functions use Deno’s Deno.serve() with Request/Response web standard APIs.

  2. Imports npm packages with require. Claude writes const express = require('express'). Edge Functions use Deno — import from URLs (import { serve } from "https://deno.land/std/http/server.ts") or use the npm: prefix for npm packages.

  3. Connects to Supabase with service key in code. Claude hardcodes createClient(url, serviceKey). Edge Functions have automatic access to Supabase services — use environment variables SUPABASE_URL and SUPABASE_SERVICE_ROLE_KEY which are pre-configured.

  4. Deploys with custom infrastructure. Claude creates Terraform or Dockerfile for deployment. Edge Functions deploy with supabase functions deploy function-name — no infrastructure configuration needed.

The CLAUDE.md Configuration

# Supabase Edge Functions

## Serverless
- Platform: Supabase Edge Functions (Deno runtime)
- API: Web standard Request/Response
- Deploy: supabase functions deploy
- Integration: native Supabase DB, auth, storage access

## Edge Function Rules
- Handler: Deno.serve(async (req) => new Response(...))
- Imports: Deno-style URLs or npm: prefix
- Env: Deno.env.get('SUPABASE_URL') for config
- CORS: handle in function with headers
- Auth: verify JWT from Authorization header
- DB: createClient with auto-configured env vars
- Local: supabase functions serve for development

## Conventions
- One function per supabase/functions/[name]/index.ts
- Use import_map.json for shared dependencies
- Verify auth token for protected functions
- Return JSON with proper Content-Type header
- Handle CORS with OPTIONS preflight
- Use supabase functions serve for local testing
- Secrets: supabase secrets set KEY=value

Workflow Example

You want to create an edge function that processes webhook events. Prompt Claude Code:

“Create a Supabase Edge Function that receives Stripe webhook events, verifies the webhook signature, updates the user’s subscription status in the Supabase database, and returns a 200 response. Handle CORS and authentication.”

Claude Code should create supabase/functions/stripe-webhook/index.ts with Deno.serve(), verify the Stripe signature using the crypto web API, create a Supabase client with SUPABASE_SERVICE_ROLE_KEY, update the user’s subscription in the database, add CORS headers, and return appropriate status codes.

Common Pitfalls

  1. Missing CORS headers. Claude does not handle CORS in edge functions. Browser requests to edge functions need CORS headers. Add an OPTIONS handler and Access-Control-Allow-Origin headers to all responses.

  2. Cold start performance issues. Claude imports large libraries at the top level. Edge functions have cold starts — minimize imports and defer heavy initialization to keep cold start times low.

  3. Not using import maps for shared code. Claude duplicates utility code across functions. Supabase Edge Functions support import_map.json for shared dependencies — define common imports once and reuse across all functions.