Developing Edge Functions locally

Get started with Edge Functions on your local machine.

Let's create a basic Edge Function on your local machine and then invoke it using the Supabase CLI.

Initialize a project#

Create a new Supabase project in a folder on your local machine:

1
supabase init

Create an Edge Function#

Let's create a new Edge Function called hello-world inside your project:

1
supabase functions new hello-world

This creates a function stub in your supabase folder:

1
2
3
4
5
└── supabase    ├── functions    │   └── hello-world    │   │   └── index.ts ## Your function code    └── config.toml

How to write the code#

The generated function uses native Deno.serve to handle requests. It gives you access to Request and Response objects.

Here's the generated Hello World Edge Function, that accepts a name in the Request and responds with a greeting:

1
2
3
4
5
6
7
8
Deno.serve(async (req) => {  const { name } = await req.json()  const data = {    message: `Hello ${name}!`,  }  return new Response(JSON.stringify(data), { headers: { 'Content-Type': 'application/json' } })})

Running Edge Functions locally#

You can run your Edge Function locally using supabase functions serve:

1
2
supabase start # start the supabase stacksupabase functions serve # start the Functions watcher

The functions serve command has hot-reloading capabilities. It will watch for any changes to your files and restart the Deno server.

Invoking Edge Functions locally#

While serving your local Edge Function, you can invoke it using curl or one of the client libraries. To call the function from a browser you need to handle CORS requests. See CORS.

1
2
3
4
curl --request POST 'http://localhost:54321/functions/v1/hello-world' \  --header 'Authorization: Bearer SUPABASE_ANON_KEY' \  --header 'Content-Type: application/json' \  --data '{ "name":"Functions" }'

You should see the response { "message":"Hello Functions!" }.

If you execute the function with a different payload, the response will change.

Modify the --data '{"name":"Functions"}' line to --data '{"name":"World"}' and try invoking the command again.

Next steps#

Check out the Deploy to Production guide to make your Edge Function available to the world.

Read on for some common development tips.

Development tips#

Here are a few recommendations when developing Edge Functions.

Skipping authorization checks#

By default, Edge Functions require a valid JWT in the authorization header. If you want to use Edge Functions without Authorization checks (commonly used for Stripe webhooks), you can pass the --no-verify-jwt flag when serving your Edge Functions locally.

1
supabase functions serve hello-world --no-verify-jwt

Be careful when using this flag, as it will allow anyone to invoke your Edge Function without a valid JWT. The Supabase client libraries automatically handle authorization.

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

Using config.toml#

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

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

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.