Development tips

Here are a few recommendations when you first start developing Edge Functions.

Using HTTP methods#

Edge Functions support GET, POST, PUT, PATCH, DELETE, and OPTIONS. A Function can be designed to perform different actions based on a request's HTTP method. See the example on building a RESTful service to learn how to handle different HTTP methods in your Function.

Naming Edge Functions#

We recommend using hyphens to name functions because hyphens are the most URL-friendly of all the naming conventions (snake_case, camelCase, PascalCase).

Organizing your Edge Functions#

We recommend developing "fat functions". This means that you should develop few large functions, rather than many small functions. One common pattern when developing Functions is that you need to share code between two or more Functions. To do this, you can store any shared code in a folder prefixed with an underscore (_). We also recommend a separate folder for Unit Tests including the name of the function followed by a -test suffix. We recommend this folder structure:

1
└── supabase
2
    ├── functions
3
    │   ├── import_map.json # A top-level import map to use across functions.
4
    │   ├── _shared
5
    │   │   ├── supabaseAdmin.ts # Supabase client with SECRET key.
6
    │   │   └── supabaseClient.ts # Supabase client with PUBLISHABLE key.
7
    │   │   └── cors.ts # Reusable CORS headers.
8
    │   ├── function-one # Use hyphens to name functions.
9
    │   │   └── index.ts
10
    │   └── function-two
11
    │   │   └── index.ts
12
    │   └── tests
13
    │       └── function-one-test.ts
14
    │       └── function-two-test.ts
15
    ├── migrations
16
    └── config.toml

Using config.toml#

Individual function configuration like JWT verification and import map location can be set via the config.toml file.

1
[functions.hello-world]
2
verify_jwt = false
3
import_map = './import_map.json'

Not using TypeScript#

When you create a new Edge Function, it will use TypeScript by default. However, it is possible to write and deploy Edge Functions using pure JavaScript.

Save your Function as a JavaScript file (e.g. index.js) and then update the supabase/config.toml as follows:

1
[functions.hello-world]
2
# other entries
3
entrypoint = './functions/hello-world/index.js' # path must be relative to config.toml

You can use any .ts, .js, .tsx, .jsx or .mjs file as the entrypoint for a Function.

Error handling#

The supabase-js library provides several error types that you can use to handle errors that might occur when invoking Edge Functions:

1
import { FunctionsFetchError, FunctionsHttpError, FunctionsRelayError } from '@supabase/supabase-js'
2
3
const { data, error } = await supabase.functions.invoke('hello', {
4
  headers: { 'my-custom-header': 'my-custom-header-value' },
5
  body: { foo: 'bar' },
6
})
7
8
if (error instanceof FunctionsHttpError) {
9
  const errorMessage = await error.context.json()
10
  console.log('Function returned an error', errorMessage)
11
} else if (error instanceof FunctionsRelayError) {
12
  console.log('Relay error:', error.message)
13
} else if (error instanceof FunctionsFetchError) {
14
  console.log('Fetch error:', error.message)
15
}

Sending Realtime messages#

To send a Broadcast message from an Edge Function, call httpSend() without subscribing to the channel. httpSend() sends the message in a single HTTP request, so no connection stays open:

1
import { createClient } from 'npm:@supabase/supabase-js@2'
2
3
const SUPABASE_SECRET_KEYS = JSON.parse(Deno.env.get('SUPABASE_SECRET_KEYS')!)
4
const supabase = createClient(Deno.env.get('SUPABASE_URL')!, SUPABASE_SECRET_KEYS['default'])
5
6
Deno.serve(async (req) => {
7
  const { roomId, message } = await req.json()
8
9
  // Verify the caller is allowed to post to this room before sending
10
  const channel = supabase.channel(`room:${roomId}`)
11
  try {
12
    await channel.httpSend('new-message', { message })
13
  } finally {
14
    await supabase.removeChannel(channel)
15
  }
16
17
  return new Response(null, { status: 204 })
18
})

httpSend() requires supabase-js 2.76.0 or later. For other languages, call the Broadcast REST API directly.

Why not subscribe to the channel#

Subscribing from an Edge Function opens more connections than you might expect, and you're billed for each one:

• Each worker that subscribes opens its own WebSocket connection and keeps it until the worker shuts down.
• Under load, a function can run many workers at once.
• Every connection counts toward Realtime Peak Connections.
• Every subscribed worker counts as a recipient of each message on the channel, which adds to Realtime Messages.

Database Functions vs Edge Functions#

For data-intensive operations we recommend using Database Functions, which are executed within your database and can be called remotely using the REST and GraphQL API.

For use-cases which require low-latency we recommend Edge Functions, which are globally-distributed and can be written in TypeScript.