supabase/apps/docs/pages/guides/functions/quickstart.mdx

import Layout from '~/layouts/DefaultGuideLayout'

export const meta = {
  id: 'functions-quickstart',
  title: 'Edge Functions Quickstart',
  description: 'Globally distributed TypeScript Functions.',
  sidebar_label: 'Quickstart',
  video: 'https://www.youtube.com/v/rzglqRdZUQE',
}

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

<div className="video-container">
  <iframe
    src="https://www.youtube-nocookie.com/embed/rzglqRdZUQE"
    frameBorder="1"
    allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture"
    allowFullScreen
  ></iframe>
</div>

## Prerequisites

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

- Install the Supabase CLI. [Docs](/docs/guides/cli).
- Login to the CLI using the command: `supabase login`. [Docs](/docs/reference/cli/usage#supabase-login).
- Initialize Supabase inside your project using the command: `supabase init`. [Docs](/docs/guides/getting-started/local-development#getting-started).
- Link to your Remote Project using the command `supabase link --project-ref your-project-ref`. [Docs](/docs/reference/cli/usage#supabase-link).
- Setup your environment: Follow [the steps below](/docs/guides/functions/quickstart#setting-up-your-environment).

## Create an Edge Function

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

```bash
supabase functions new hello-world
```

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

## Deploy to production

### Deploy a specific function

```bash
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.

<Admonition type="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](https://github.com/supabase/supabase/tree/master/examples/edge-functions/supabase/functions/stripe-webhooks) etc.), you need to pass the `--no-verify-jwt` flag when deploying your function.

</Admonition>

### Deploy all functions

```bash
supabase functions deploy
```

Since Supabase CLI [v1.62.0](https://github.com/supabase/cli/releases/tag/v1.62.0) you can deploy all functions with a single command. This is useful for example when [deploying with GitHub Actions](/docs/guides/functions/cicd-workflow).

Individual function configuration like [JWT verification](/docs/reference/cli/config#functions.function_name.verify_jwt) and [import map location](/docs/reference/cli/config#functions.function_name.import_map) can be set via the `config.toml` file.

```toml
[functions.hello-world]
verify_jwt = false
```

## Invoking remote functions

You can invoke Edge Functions using curl:

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

<Admonition type="note">

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

</Admonition>

or using one of the [client libraries](/docs#reference-documentation), e.g. using [supabase-js](/docs/reference/javascript/functions-invoke):

```js
// https://supabase.com/docs/reference/javascript/installing
import { createClient } from '@supabase/supabase-js'

// Create a single supabase client for interacting with your database
const supabase = createClient('https://xyzcompany.supabase.co', 'public-anon-key')

const { data, error } = await supabase.functions.invoke('hello-world', {
  body: { name: 'Functions' },
})
```

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

## Importing Node npm modules

We recommend using [esm.sh](https://esm.sh/) for importing Node.js modules that are published to npm. To do so you simply put `https://esm.sh/` in front of the package name.

For example, when you want to use supabase-js within Supabase Edge Functions, you would import `createClient` as follows:

```ts
import { createClient } from 'https://esm.sh/@supabase/supabase-js@2'
```

As long as your environment is set up properly and the module you're importing is exporting types, the import will have types and autocompletion support.

## Setting Up Your Environment

You can follow the [Deno guide](https://deno.com/manual@v1.32.5/getting_started/setup_your_environment) for setting up your development environment with your favorite editor/IDE.

### Deno with Visual Studio Code (vscode)

Install the Deno language server [via this link](vscode:extension/denoland.vscode-deno) or by browsing the extensions in vscode and choosing to install the _Deno_ extension.

#### Partially Deno enabling a workspace

In a given workspace (or workspace folder), sub-paths can be enabled for Deno, while code outside those paths will be not be enabled and the vscode built-in JavaScript/TypeScript language server will be used.

For example if you have a project like this:

```
project
├── app
└── supabase
  └── functions
```

Where you only want to enabled the `supabase/functions` path (and its subpaths) to be Deno enabled, you will want to add `./supabase/functions` to the list of _Deno: Enable Paths_ in the configuration. In your `.vscode/settings.json` file add:

```json
{
  "deno.enablePaths": ["./supabase/functions"],
  "deno.importMap": "./supabase/functions/import_map.json"
}
```

#### Multi-root workspaces

Alternatively, you can utilize [multi-root workspaces](https://code.visualstudio.com/docs/editor/workspaces#_multiroot-workspaces).

<div className="video-container">
  <iframe
    src="https://www.youtube-nocookie.com/embed/lFhU3L8VoSQ"
    frameBorder="1"
    allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture"
    allowFullScreen
  ></iframe>
</div>

For example, see this `edge-functions.code-workspace` configuration for a CRA (create react app) client with Supabase Edge Functions. You can find the complete example on [GitHub](https://github.com/supabase/supabase/tree/master/examples/edge-functions).

```json
{
  "folders": [
    {
      "name": "project-root",
      "path": "./"
    },
    {
      "name": "client",
      "path": "app"
    },
    {
      "name": "supabase-functions",
      "path": "supabase/functions"
    }
  ],
  "settings": {
    "files.exclude": {
      "node_modules/": true,
      "app/": true,
      "supabase/functions/": true
    },
    "deno.importMap": "./supabase/functions/import_map.json"
  }
}
```

## Database Functions vs Edge Functions

For data-intensive operations we recommend using [Database Functions](/docs/guides/database/functions), which are executed within your database
and can be called remotely using the [REST and GraphQL API](/docs/guides/api).

For use-cases which require low-latency we recommend [Edge Functions](/docs/guides/functions), which are globally-distributed and can be written in TypeScript.

## 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 recommend this folder structure:

```bash
└── 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
    ├── migrations
    └── config.toml
```

## 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).

## Using HTTP Methods

Edge Functions supports `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](https://github.com/supabase/supabase/tree/master/examples/edge-functions/supabase/functions/restful-tasks) to learn how to handle different HTTP methods in your function.

## Limitations

- Deno Deploy limitations
  - Deno does not support outgoing connections to ports `25`, `465`, and `587`.
  - Cannot read or write to File System
  - NPM modules are not supported.
- Edge Functions
  - Serving of HTML content is not supported (`GET` requests that return `text/html` will be rewritten to `text/plain`).

export const Page = ({ children }) => <Layout meta={meta} children={children} />

export default Page