Edge Functions Quickstart

Learn how to build an Edge Function locally and deploy it to the Supabase Platform in less than 7 minutes.

Prerequisites#

Follow the steps to prepare your Supabase project on your local machine.

  • Install the Supabase CLI. Docs.
  • Login to the CLI using the command: supabase login. Docs.
  • Initialize Supabase inside your project using the command: supabase init. Docs.
  • Link to your Remote Project using the command supabase link --project-ref your-project-ref. Docs.
  • Optional: Setup your environment: Follow this setup guide to integrate the Deno language server with your editor.

Create a function#

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

supabase functions new hello-world

This creates a function stub in your supabase folder at ./functions/hello-world/index.ts.

Deploy to production#

supabase functions deploy hello-world

This command bundles your Edge Function from ./functions/hello-world/index.ts and deploys it to the Supabase platform. The command outputs a URL to the Supabase Dashboard which you can open to find view more details. Let's open the link to find the execution command.

note

By default, Edge Functions require a valid JWT in the authorization header. This header is automatically set when invoking your function via a Supabase client library.

If you want to use Edge Functions to handle webhooks (e.g. Stripe payment webhooks etc.), you need to pass the --no-verify-jwt flag when deploying your function.

Execute remote functions#

You can execute Edge Functions using curl. Copy the curl command from the Dashboard. It should look like this:

curl --request POST 'https://<project_ref>.functions.supabase.co/hello-world' \
  --header 'Authorization: Bearer ANON_KEY' \
  --header 'Content-Type: application/json' \
  --data '{ "name":"Functions" }'

If you receive an error Invalid JWT, find the ANON_KEY of your project in the Dashboard under Settings > API.

After invoking your Edge Function you should see the response { "message":"Hello Functions!" }.

Debug functions#

You can debug your deployed Edge Functions using the "Functions" section of the Dashboard. There are two types debugging tools available:

  • Invocations: shows the Request and Response for each execution.
  • Logs: shows any platform events, including deployments and errors.

Function invocations.

Develop locally#

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

supabase start # start the supabase stack
supabase functions serve hello-world # start the Function watcher

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

Invoke functions locally#

While serving your local Function, you can execute it using curl:

curl --request POST 'http://localhost:54321/functions/v1/hello-world' \
  --header 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJzdXBhYmFzZS1kZW1vIiwicm9sZSI6ImFub24ifQ.625_WdcF3KHqz5amU0x2X5WWHP-OEs_4qj0ssLNHzTs' \
  --header 'Content-Type: application/json' \
  --data '{ "name":"Functions" }'

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

Implementation details
  • All Edge Functions are POST requests.
  • The Authorization header is required. You can use either the ANON key, the SERVICE_ROLE key, or a logged-in user's JWT.
  • The Function is proxied through the local API (http://localhost:54321)

If you execute 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!

Secrets and Environment Variables#

It's common that you will need to use sensitive information or environment-specific variables inside your Edge Functions. You can access these using Deno's built-in handler

1Deno.env.get(MY_SECRET_NAME)

Default secrets#

By default, Edge Functions have access to these secrets:

  • SUPABASE_URL: The API gateway for your Supabase project.
  • SUPABASE_ANON_KEY: The anon key for your Supabase API. This is safe to use in a browser when you have Row Level Security enabled.
  • SUPABASE_SERVICE_ROLE_KEY: The service_role key for your Supabase API. This is safe to use in Edge Functions, but it should NEVER be used in a browser. This key will bypass Row Level Security.
  • SUPABASE_DB_URL: The URL for your PostgreSQL database. You can use this to connect directly to your database.

Local secrets#

Let's create a local file for storing our secrets, and inside it we can store a secret MY_NAME:

1echo "MY_NAME=Yoda" >> ./supabase/.env.local

This creates a new file ./supabase/.env.local for storing your local development secrets.

caution

Never check your .env files into Git!

Now let's access this environment variable MY_NAME inside our Function. Anywhere in your function, add this line:

1console.log(Deno.env.get('MY_NAME'))

Now we can invoke our function locally, by serving it with our new .env.local file:

supabase functions serve hello-world --env-file ./supabase/.env.local

When the function starts you should see the name “Yoda” output to the terminal.

Production secrets#

Let's create a .env for production. In this case we'll just use the same as our local secrets:

cp ./supabase/.env.local ./supabase/.env

This creates a new file ./supabase/.env for storing your production secrets.

caution

Never check your .env files into Git!

Let's push all the secrets from the .env file to our remote project using supabase secrets set:

supabase secrets set --env-file ./supabase/.env

# You can also set secrets individually using:
supabase secrets set MY_NAME=Chewbacca

You don't need to re-deploy after setting your secrets.

To see all the secrets which you have set remotely, use supabase secrets list:

supabase secrets list

Limitations#

  • Deno Deploy limitations
    • Deno does not support outgoing connections to ports 25, 465, and 587.
    • Cannot write to File System
  • Edge Functions
    • Local development - only one function at a time
    • Serving of HTML content is not supported (GET requests that return text/html will be rewritten to text/plain).