Edge Function default export with fetch handler
Export an Edge Function as a default export with a `fetch` property that implements the HTTP handler. The handler receives a request object and a context object containing Supabase client and metadata.
Supabase · Edge Functions · all subjects
edge functions/basics
132 notes in this subject, read out of this brain and free to use. This is page 1 of 3.
Edge request processing flow
Requests follow this flow: request enters an edge gateway which routes traffic and handles auth headers/JWT validation; auth and policies are applied by the gateway or function; the Edge Runtime executes the function on a regionally-distributed node closest to the user; functions can call Supabase APIs or third-party APIs; invocations emit logs and metrics to the dashboard; the gateway returns the response to the client.
Design Edge Functions for short-lived operations
Edge Functions are subject to cold starts and concurrency limits. They should be designed for short-lived, idempotent operations. Heavy long-running jobs should be moved to background workers.
Edge Functions use cases
Edge Functions are suitable for: authenticated or public HTTP endpoints needing low latency; webhook receivers (Stripe, GitHub, etc.); on-demand image or Open Graph generation; small AI inference tasks or orchestrating calls to external LLM APIs like OpenAI; sending transactional emails; building messaging bots for Slack, Discord, etc.
Edge Functions runtime is Deno
Supabase Edge Functions run on Deno, a TypeScript-first runtime. Functions are .ts files that export a handler. Deno is open source and portable.
Warm starts: isolates remain active for reuse
Isolates can remain active for a period (plan-dependent) to handle subsequent requests without restarting, providing warm start performance benefits.
Edge Functions: serverless compute at the network edge
Edge functions are serverless compute resources that run at the edge of the network, close to users, enabling low-latency execution for tasks like API endpoints, webhooks, and real-time data processing.
Cold starts: millisecond-level latency
Cold starts for edge functions are fast, occurring in milliseconds, due to the compact ESZip format and minimal Deno runtime overhead.
V8 isolate: one per function invocation
A new V8 isolate is spun up for each function invocation. V8 is the JavaScript engine used by Chrome and Node.js, providing a lightweight, sandboxed environment. Each isolate has its own memory heap and execution thread, ensuring complete isolation with no interference between concurrent requests.
Concurrency: multiple isolates in same edge location
Multiple isolates can run simultaneously in the same edge location, supporting high traffic and concurrent requests.
Edge Locations: distributed data centers worldwide
Supabase maintains a network of edge locations, which are data centers worldwide where functions are replicated. The ESZip bundle is automatically distributed to these locations upon deployment.
Global API Gateway: entry point and geolocation routing
The Global API Gateway acts as the entry point for all requests. It uses the requester's IP address to determine geographic location and routes the request to the nearest edge location, such as routing a request from Amsterdam to Frankfurt.
Common use cases: real-time transformations, APIs, webhooks, personalization
Common use cases for edge functions include real-time data transformations such as image processing, API integrations and webhooks, and personalization and A/B testing at the edge.
Stateless execution: no persistent state between runs
Edge functions execute with no persistent state; each run is stateless, making them ideal for ephemeral tasks. Isolates prevent side effects from one function affecting others, enhancing reliability.
Request handling flow: client to response
A client sends an HTTP request (e.g., POST) to the function's URL, including parameters like auth headers, image ID, and filter type. The global API gateway routes it to the nearest edge location. At the edge, Supabase's edge runtime validates the request, such as checking authorization. A new V8 isolate is spun up, the ESZip bundle is loaded, and the function code runs. After execution, the response is sent back to the client.
Edge functions handle compute-intensive tasks server-side
Edge functions handle compute-intensive tasks without burdening the client device or the database. Execution happens server-side but at the edge, ensuring speed and scalability.
Checking if request body is gzip compressed
To verify if a request body is gzip compressed, check the 'content-encoding' header from the request. If it equals 'gzip', the body is compressed.
Memory risk with large compressed payloads
When handling compressed payloads in edge functions, be cautious about the size of the payload. Large compressed payloads can exceed the 150MB memory limit and cause out-of-memory errors.
Edge functions runtime memory limit
Edge functions have a runtime memory limit of 150MB. Overly large compressed payloads may result in an out-of-memory error.
Handle unhandled rejections in background tasks
You can add an event listener to unhandledrejection to handle any promises without a rejection handler. Example: ```tsx addEventListener('unhandledrejection', (ev) => { console.log('unhandledrejection', ev.reason) ev.preventDefault() }) ```
Handle errors in background tasks with try/catch
Use try/catch blocks within your background task function to handle errors in background tasks.
Background task duration limits
The maximum duration for background tasks is capped based on wall-clock, CPU, and memory limits. The function will shut down when it reaches one of these limits.
EdgeRuntime.waitUntil does not block requests
You can call EdgeRuntime.waitUntil inside the request handler and it will not block the request. The task runs in the background while the response is sent immediately.
Use beforeunload event to detect function shutdown
You can listen to the beforeunload event handler to be notified when the Function is about to be shut down. This allows you to save state or log the current progress before the function terminates.
Background tasks with EdgeRuntime.waitUntil
Edge Function instances can process background tasks outside of the request handler using EdgeRuntime.waitUntil(promise). The Function instance continues to run until the promise completes. This allows you to respond to users immediately while processing continues asynchronously without blocking the response.
Import corsHeaders from @supabase/supabase-js for v2.95.0+
For @supabase/supabase-js v2.95.0 and later, import corsHeaders directly from npm:@supabase/supabase-js@^2/cors to automatically get all required headers. This ensures your Edge Functions automatically include new headers when they are added to the Supabase SDK, preventing CORS errors.
withSupabase wrapper handles CORS automatically
The withSupabase wrapper automatically handles CORS and preflight OPTIONS requests, so you do not need to add CORS headers manually when using this wrapper.
Manual CORS handling with corsHeaders import
To manually handle CORS, import corsHeaders from npm:@supabase/supabase-js@^2/cors and add these headers to your responses. Handle OPTIONS requests by returning a response with status 200 and corsHeaders. Include corsHeaders in all responses: successful responses, errors, and preflight requests.
Hardcoded CORS headers for @supabase/supabase-js before v2.95.0
For @supabase/supabase-js versions before v2.95.0, hardcode the CORS headers in a cors.ts file. The required headers are: 'Access-Control-Allow-Origin': '*' and 'Access-Control-Allow-Headers': 'authorization, x-client-info, apikey, content-type'.
Create _shared folder for CORS headers in older versions
For @supabase/supabase-js before v2.95.0, create a cors.ts file within a _shared folder to store the hardcoded CORS headers, then import this file in your functions.
Dart Edge enables Dart language for Edge Functions
Dart Edge is an experimental project that enables you to write Supabase Edge Functions using the Dart programming language. It is built and maintained by Invertase.
Dart Edge project maintenance status
The Dart Edge project is currently not actively maintained due to numerous breaking changes in Dart's development of WebAssembly (WASM) support.
Function configuration via config.toml
Configure individual functions using the config.toml file. Settings like `verify_jwt` and `import_map` can be configured per function under `[functions.function_name]` sections. Example: `[functions.hello-world]` with `verify_jwt = false`. This ensures function configurations are consistent across all environments and deployments.
Use fat functions to minimize cold starts
Develop few, large functions by combining related functionality rather than many small functions. This approach minimizes cold starts in production.
Install Deno CLI for editor support and tooling
You should install Deno CLI separately from the Supabase CLI for editor autocompletion, type checking, and testing. This allows you to use the Deno LSP and Deno's built-in tools such as deno fmt, deno lint, and deno test. Verify installation with deno --version.
Function naming conventions for Supabase Edge Functions
Use hyphens (-) for function names as they are the most URL-friendly approach. Store shared code in a folder prefixed with an underscore (_).
Recommended Supabase project structure for Edge Functions
The recommended project structure is: supabase/functions/ containing deno.json (top-level Deno configuration), _shared/ (shared code with underscore prefix for files like supabaseAdmin.ts, supabaseClient.ts, cors.ts), function-one/index.ts, function-two/index.ts; plus supabase/tests/ for unit tests with naming convention function-name-test.ts; supabase/migrations; and config.toml in the root.
Supabase CLI uses Edge Runtime instead of standard Deno CLI
The Supabase CLI does not use the standard Deno CLI to serve functions locally. Instead, it uses its own Edge Runtime to keep the development and production environment consistent.
Error types for Edge Functions invocation
The supabase-js library provides three error types for handling errors when invoking Edge Functions: FunctionsHttpError (when the function returns an error), FunctionsRelayError (when there is a relay error), and FunctionsFetchError (when there is a fetch error).
Edge Functions entrypoint file format support
You can use any .ts, .js, .tsx, .jsx, or .mjs file as the entrypoint for an Edge Function.
Recommended Edge Functions folder structure
The recommended folder structure is: supabase/functions with import_map.json at the top level, a _shared folder for shared code and clients, individual function folders with hyphenated names containing index.ts, and a tests folder for test files.
Unit test folder structure
Use a separate folder for unit tests including the name of the function followed by a -test suffix. For example, function-one-test.ts for tests related to function-one.
Shared code folder structure
Store shared code between two or more Edge Functions in a folder prefixed with an underscore (_). This allows code reuse across functions.
Fat functions organization pattern
It is recommended to develop few large functions rather than many small functions. This pattern is called developing 'fat functions'.
Naming convention for Edge Functions
Use hyphens to name Edge Functions because hyphens are the most URL-friendly of all naming conventions (compared to snake_case, camelCase, or PascalCase).
When to use Database Functions vs Edge Functions
For data-intensive operations, use 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, use Edge Functions which are globally-distributed and can be written in TypeScript.
HTML content not supported in Edge Functions
HTML content is not supported in Edge Functions. GET requests that return text/html will be rewritten to text/plain.
Best practice for function error messages
Functions that fail silently are hard to debug. Functions with clear error messages get fixed fast. Always include descriptive error messages in responses and log errors to console.
Basic error handling pattern in Edge Functions
Use try-catch blocks in Deno.serve to handle errors. Return JSON responses with appropriate HTTP status codes: 200 for success, 500 for server errors. Log errors to console using console.error() for debugging in the Logs tab. The pattern is: try { process request and return 200 status }, catch { log error and return 500 status with error message in JSON body }.
Accessing Edge Function error response data
When catching a FunctionsHttpError, use await error.context.json() to parse the JSON response body containing the error message returned by the function.
Client-side error handling with instanceof checks
Import FunctionsHttpError, FunctionsRelayError, and FunctionsFetchError from '@supabase/supabase-js'. Check error type using instanceof: if (error instanceof FunctionsHttpError) for function errors, if (error instanceof FunctionsRelayError) for network issues, if (error instanceof FunctionsFetchError) for unreachable functions. For FunctionsHttpError, access response data using await error.context.json().
Three types of client-side Edge Function errors
FunctionsHttpError occurs when the function executed but returned an error status (4xx/5xx). FunctionsRelayError occurs when there is a network issue between client and Supabase. FunctionsFetchError occurs when the function couldn't be reached at all. These error classes are imported from '@supabase/supabase-js'.
Error response body format
Include helpful error messages in the response body. Return JSON format with 'Content-Type': 'application/json' header. Error messages should be descriptive to aid in debugging.
Production error logs location
View production error logs in the Logs tab of the Supabase Dashboard.
HTTP status codes for Edge Function responses
Use 400 status code for bad user input, 404 when something doesn't exist, 500 for server errors. Using the right status code for each situation helps with debugging and lets client apps handle different error types appropriately.
Extract client IP from x-forwarded-for header
Client IP addresses can be extracted from the x-forwarded-for header in the request. The header may contain multiple comma-separated IP addresses, so split by a comma pattern with optional whitespace and use the first entry.
Invoke Edge Function from client
Edge Functions can be invoked from the client using supabase.functions.invoke() with the function name and an options object containing the request body: await supabase.functions.invoke('cloudflare-turnstile', { body: { token } }).
withSupabase wrapper for CORS and preflight handling
The withSupabase helper function handles CORS and preflight requests automatically. It accepts an options object with an auth property (set to 'none' to disable authentication) and a callback function that receives the request and returns a response.
withSupabase handler wrapper
Edge Functions use the `withSupabase` wrapper from `@supabase/server` to handle Supabase integration. It accepts options like `{ auth: 'none' }` to disable JWT verification, and provides the request object.
Configure individual Edge Function settings in config.toml
Function-specific configuration can be set in `config.toml` using the section `[functions.function-name]`. Example: `[functions.hello-world]` followed by `verify_jwt = false` disables JWT verification for that specific function.