Edge Functions

Overview

Supabase Edge Functions are server-side TypeScript functions that run on Deno, distributed globally at the edge. They’re perfect for running custom business logic, integrations with third-party services, or any server-side code.

Base URL

Edge Functions are available at:

https://<PROJECT_REF>.supabase.co/functions/v1/

Invoking Functions

Basic Invocation

Invoke a function with a POST request.

curl -X POST 'https://<PROJECT_REF>.supabase.co/functions/v1/hello-world' \
  -H "apikey: YOUR_ANON_KEY" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name": "Functions"}'

function_name

string

required

The name of the function to invoke (in the URL path).

apikey

string

required

Your Supabase API key.

Authorization

string

Bearer token for authenticated requests (optional for public functions).

Content-Type

string

Set to application/json for JSON payloads.

Response

{
  "message": "Hello Functions!"
}

GET Request

Invoke a function with a GET request.

curl 'https://<PROJECT_REF>.supabase.co/functions/v1/hello-world?name=Functions' \
  -H "apikey: YOUR_ANON_KEY"

Custom Headers

Pass custom headers to your function.

curl -X POST 'https://<PROJECT_REF>.supabase.co/functions/v1/webhook-handler' \
  -H "apikey: YOUR_ANON_KEY" \
  -H "X-Custom-Header: custom-value" \
  -H "Content-Type: application/json" \
  -d '{"event": "user.created"}'

Function Examples

Basic Function

A simple Edge Function that returns a greeting.

// supabase/functions/hello-world/index.ts
import { serve } from 'https://deno.land/std@0.168.0/http/server.ts'

serve(async (req) => {
  const { name } = await req.json()
  
  const data = {
    message: `Hello ${name}!`,
  }

  return new Response(
    JSON.stringify(data),
    { headers: { 'Content-Type': 'application/json' } },
  )
})

Database Access

Access your Supabase database from an Edge Function.

import { serve } from 'https://deno.land/std@0.168.0/http/server.ts'
import { createClient } from 'https://esm.sh/@supabase/supabase-js@2'

serve(async (req) => {
  const supabaseClient = createClient(
    Deno.env.get('SUPABASE_URL') ?? '',
    Deno.env.get('SUPABASE_ANON_KEY') ?? '',
    {
      global: {
        headers: { Authorization: req.headers.get('Authorization')! },
      },
    }
  )

  const { data, error } = await supabaseClient
    .from('countries')
    .select('*')
    .limit(10)

  if (error) {
    return new Response(
      JSON.stringify({ error: error.message }),
      { status: 500, headers: { 'Content-Type': 'application/json' } }
    )
  }

  return new Response(
    JSON.stringify(data),
    { headers: { 'Content-Type': 'application/json' } }
  )
})

OpenAI Integration

Integrate with third-party APIs like OpenAI.

import { serve } from 'https://deno.land/std@0.168.0/http/server.ts'
import { Configuration, OpenAIApi } from 'https://esm.sh/openai@3.1.0'

serve(async (req) => {
  const { prompt } = await req.json()

  const configuration = new Configuration({
    apiKey: Deno.env.get('OPENAI_API_KEY'),
  })
  const openai = new OpenAIApi(configuration)

  const completion = await openai.createChatCompletion({
    model: 'gpt-3.5-turbo',
    messages: [{ role: 'user', content: prompt }],
  })

  return new Response(
    JSON.stringify({
      response: completion.data.choices[0].message?.content,
    }),
    { headers: { 'Content-Type': 'application/json' } }
  )
})

Webhook Handler

Handle webhooks from third-party services.

import { serve } from 'https://deno.land/std@0.168.0/http/server.ts'
import { createClient } from 'https://esm.sh/@supabase/supabase-js@2'

serve(async (req) => {
  // Verify webhook signature
  const signature = req.headers.get('x-webhook-signature')
  if (!verifySignature(signature, await req.text())) {
    return new Response('Unauthorized', { status: 401 })
  }

  const payload = await req.json()
  const supabaseClient = createClient(
    Deno.env.get('SUPABASE_URL') ?? '',
    Deno.env.get('SUPABASE_SERVICE_ROLE_KEY') ?? ''
  )

  // Process webhook
  await supabaseClient
    .from('webhook_events')
    .insert({
      event_type: payload.type,
      data: payload.data,
    })

  return new Response('OK', { status: 200 })
})

function verifySignature(signature: string | null, body: string): boolean {
  // Implement signature verification logic
  return true
}

Environment Variables

Access environment variables in your functions.

const supabaseUrl = Deno.env.get('SUPABASE_URL')
const apiKey = Deno.env.get('SUPABASE_ANON_KEY')
const serviceRoleKey = Deno.env.get('SUPABASE_SERVICE_ROLE_KEY')
const customVar = Deno.env.get('MY_CUSTOM_VAR')

Built-in Environment Variables

SUPABASE_URL

string

Your Supabase project URL.

SUPABASE_ANON_KEY

string

Your Supabase anon key.

SUPABASE_SERVICE_ROLE_KEY

string

Your Supabase service role key (use with caution).

SUPABASE_DB_URL

string

Direct connection string to your Postgres database.

Request and Response

Request Object

Access request properties.

serve(async (req) => {
  // HTTP method
  const method = req.method // GET, POST, etc.

  // Headers
  const contentType = req.headers.get('Content-Type')
  const auth = req.headers.get('Authorization')

  // URL and query params
  const url = new URL(req.url)
  const name = url.searchParams.get('name')

  // Body
  const body = await req.json() // For JSON
  const text = await req.text() // For text
  const formData = await req.formData() // For forms

  return new Response('OK')
})

Response Object

Return different types of responses.

// JSON response
return new Response(
  JSON.stringify({ message: 'Success' }),
  {
    status: 200,
    headers: {
      'Content-Type': 'application/json',
      'Cache-Control': 'no-cache',
    },
  }
)

// Plain text
return new Response('Hello World', {
  headers: { 'Content-Type': 'text/plain' },
})

// HTML
return new Response('<h1>Hello World</h1>', {
  headers: { 'Content-Type': 'text/html' },
})

// Redirect
return new Response(null, {
  status: 302,
  headers: { Location: 'https://example.com' },
})

// Error
return new Response(
  JSON.stringify({ error: 'Not found' }),
  {
    status: 404,
    headers: { 'Content-Type': 'application/json' },
  }
)

CORS

Handle CORS for browser requests.

import { serve } from 'https://deno.land/std@0.168.0/http/server.ts'
import { corsHeaders } from '../_shared/cors.ts'

serve(async (req) => {
  // Handle CORS preflight
  if (req.method === 'OPTIONS') {
    return new Response('ok', { headers: corsHeaders })
  }

  // Your function logic
  const data = { message: 'Hello from CORS-enabled function' }

  return new Response(
    JSON.stringify(data),
    {
      headers: { ...corsHeaders, 'Content-Type': 'application/json' },
    }
  )
})

CORS Headers

// _shared/cors.ts
export const corsHeaders = {
  'Access-Control-Allow-Origin': '*',
  'Access-Control-Allow-Headers': 'authorization, x-client-info, apikey, content-type',
}

Authentication

Verify JWT

Verify the user’s JWT token.

import { serve } from 'https://deno.land/std@0.168.0/http/server.ts'
import { createClient } from 'https://esm.sh/@supabase/supabase-js@2'

serve(async (req) => {
  const supabaseClient = createClient(
    Deno.env.get('SUPABASE_URL') ?? '',
    Deno.env.get('SUPABASE_ANON_KEY') ?? '',
    {
      global: {
        headers: { Authorization: req.headers.get('Authorization')! },
      },
    }
  )

  // Get the current user
  const {
    data: { user },
    error,
  } = await supabaseClient.auth.getUser()

  if (error || !user) {
    return new Response(
      JSON.stringify({ error: 'Unauthorized' }),
      { status: 401, headers: { 'Content-Type': 'application/json' } }
    )
  }

  return new Response(
    JSON.stringify({ userId: user.id, email: user.email }),
    { headers: { 'Content-Type': 'application/json' } }
  )
})

Deployment

Deploy via CLI

# Deploy a single function
supabase functions deploy hello-world

# Deploy all functions
supabase functions deploy

# Deploy with environment variables
supabase secrets set MY_SECRET=value
supabase functions deploy hello-world

Deploy via GitHub Actions

name: Deploy Functions

on:
  push:
    branches:
      - main

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      
      - uses: supabase/setup-cli@v1
        with:
          version: latest
      
      - name: Deploy functions
        run: supabase functions deploy
        env:
          SUPABASE_ACCESS_TOKEN: ${{ secrets.SUPABASE_ACCESS_TOKEN }}
          PROJECT_REF: ${{ secrets.PROJECT_REF }}

Limits and Pricing

Free Tier

500,000 invocations per month
1GB bandwidth per month
100 concurrent executions

Pro Tier

2,000,000 invocations per month
5GB bandwidth per month
500 concurrent executions

Execution Limits

Timeout: 60 seconds per invocation
Memory: 150MB RAM
CPU: Limited based on plan
Cold start: ~1-3 seconds

Best Practices

Keep functions focused

Each function should do one thing well. Create multiple functions for different use cases.

Use environment variables for secrets

Never hardcode API keys or secrets in your functions:

supabase secrets set OPENAI_API_KEY=sk-...

Implement error handling

Always handle errors gracefully:

try {
  // Your logic
} catch (error) {
  return new Response(
    JSON.stringify({ error: error.message }),
    { status: 500 }
  )
}

Use TypeScript

TypeScript provides better developer experience and catches errors early.

Cache responses when possible

Use appropriate cache headers to reduce function invocations:

headers: { 'Cache-Control': 'public, max-age=3600' }

Monitoring

View function logs and metrics in the Supabase Dashboard:

Logs: Real-time function execution logs
Metrics: Invocation count, error rate, execution time
Traces: Request/response details

Next Steps

Deploy Your First Function

Learn how to create and deploy Edge Functions

Client Libraries

Invoke functions from your app

Client Libraries

REST API

GraphQL API

Realtime API

Overview

Base URL

Invoking Functions

Basic Invocation

Response

GET Request

Custom Headers

Function Examples

Basic Function

Database Access

OpenAI Integration

Webhook Handler

Environment Variables

Built-in Environment Variables

Request and Response

Request Object

Response Object

CORS

CORS Headers

Authentication

Verify JWT

Deployment

Deploy via CLI

Deploy via GitHub Actions

Limits and Pricing

Free Tier

Pro Tier

Execution Limits

Best Practices

Monitoring

Next Steps

Deploy Your First Function

Client Libraries

Client Libraries

REST API

GraphQL API

Realtime API

​Overview

​Base URL

​Invoking Functions

​Basic Invocation

​Response

​GET Request

​Custom Headers

​Function Examples

​Basic Function

​Database Access

​OpenAI Integration

​Webhook Handler

​Environment Variables

​Built-in Environment Variables

​Request and Response

​Request Object

​Response Object

​CORS

​CORS Headers

​Authentication

​Verify JWT

​Deployment

​Deploy via CLI

​Deploy via GitHub Actions

​Limits and Pricing

​Free Tier

​Pro Tier

​Execution Limits

​Best Practices

​Monitoring

​Next Steps

Deploy Your First Function

Client Libraries

Overview

Base URL

Invoking Functions

Basic Invocation

Response

GET Request

Custom Headers

Function Examples

Basic Function

Database Access

OpenAI Integration

Webhook Handler

Environment Variables

Built-in Environment Variables

Request and Response

Request Object

Response Object

CORS

CORS Headers

Authentication

Verify JWT

Deployment

Deploy via CLI

Deploy via GitHub Actions

Limits and Pricing

Free Tier

Pro Tier

Execution Limits

Best Practices

Monitoring

Next Steps