Edge Functions declarations

This feature is in BETA.

Unlike regular functions, edge functions aren’t automatically assigned a URL route for you to use as a function endpoint. Instead, you configure your edge functions to run on specific URL patterns.

You can configure the edge function path inline in the function code or in netlify.toml.

# Declare edge functions inline

To configure the edge function path in the same file as the function code, export a config object with a path property.

import { Config } from "https://edge.netlify.com"

export default async () => new Response("Hello, world!")

export const config: Config = {
  path: "/test"
}

This property can be a string if you want the edge function to run on a single path or an array of strings if you want to configure multiple paths.

In both cases, you can use glob-style expressions to match multiple paths.

import { Config } from "https://edge.netlify.com"

export default async () => new Response("Hello, world!")

export const config: Config = {
  path: ["/", "/products/*"]
}

# Declare edge functions in netlify.toml

If you would like to declare multiple edge functions to run on the same path and customize the order they run in, configure edge function paths in netlify.toml instead of inline in the function file.

The edge_functions property maps glob-style routes to an array of functions that will run — in order — for any requests that match the routes.

Each edge function declaration associates one site path pattern with one function to execute on requests that match the path. A single request can execute a chain of edge functions from a series of declarations. A single edge function can be associated with multiple paths across various declarations.

[[edge_functions]]
  path = "/admin"
  function = "auth"

[[edge_functions]]
  path = "/admin"
  function = "injector"

[[edge_functions]]
  path = "/blog/*"
  function = "auth"

[[edge_functions]]
  path = "/blog/*"
  function = "rewriter"

[[edge_functions]]
  path = "/*"
  function = "common"

This example shows how both paths and functions can be configured across multiple declarations.

  • A request for /admin would invoke the auth function first, then injector, and finally common.
  • The auth function runs for the /admin path and any child paths of /blog.

# Declaration processing order

In general, edge functions declared in netlify.toml run before those declared inline. This section outlines the processing order, and any exceptions, in more detail.

When a request is made for a path, such as /admin, edge functions run in this order:

  1. Edge functions your framework generates and declares for the path in netlify.toml.

  2. Edge functions you declare for the path in netlify.toml. If you declare multiple edge functions for the same path, they run in order of declaration in the file, from top to bottom.

    Note that if you declare the same edge function both in netlify.toml and inline, Netlify merges the configurations and treats them as inline declarations (refer to step 4). The inline configuration takes precedence for any duplicate fields.

  3. Edge functions your framework generates and declares for the path with inline configuration.

  4. Edge functions you declare for the path with inline configuration. If you use inline configuration to declare multiple edge functions for the same path, they run in alphabetical order by function file name.

Once all edge functions for the path run, Netlify moves on to evaluate any redirect rules — unless the last edge function returns a response and ends the request chain. A redirect might request a new path that also requires edge functions and the above steps will repeat for that new path.

The request chain continues until it eventually serves static content or returns a request from a serverless function. Learn more about request handling with edge functions.

Use netlify.toml to be explicit about edge function order

If you want to customize the order in which multiple edge functions run on a given path, we recommend that you add the declarations to netlify.toml instead of using inline declarations.

# Processing order caveats

Keep the following caveats in mind as you write and configure your edge functions as these items can interrupt or change the expected order of events:

  • If the edge function for a path returns a response and terminates the request, redirects for that path do not occur.
  • If you declare an edge function for the target path of a rewrite, the edge function will not execute for rewritten requests and a 404 will be returned instead.
  • If the edge function uses fetch() for internal requests, the command will start a new request chain and Netlify will run any edge functions that match that path first. If you want to request a specific static asset or serverless function with the same internal path, and not re-run the same edge functions, use context.rewrite() instead.

Along with considering these caveats, we recommend you also review the edge functions feature limitations.