Configure and deploy Edge Handlers

This feature is in early access BETA.

This document will help you get started with Edge Handlers. You can visit our sign-up form to request an invitation to the early access beta program or go to our Community forum to join the conversation about Edge Handlers.

Configure Edge Handlers

Edge Handler behaviors are defined in files you store in your site repository. At deploy time, Netlify's build bots detect your handlers by looking for an edge-handlers directory in the site's base directory in your repository. The handler files can't be organized into subdirectories within edge-handlers.

If you want to customize the Edge Handlers directory name or location, you can do so in the Netlify configuration file in the build settings. The path is either relative to the root of the repository, or, if a base directory is set, it's relative to the base directory.

[build]
edge_handlers = "src/my-edge-handlers"

Declare Edge Handlers

Before our CDN edge nodes can use your handlers to filter or alter requests, you must declare them with redirect rules. You can add these rules to the _redirects file or the Netlify configuration file to declare Edge Handlers, using identifiers that match handler file names. In both _redirects and netlify.toml syntax, each redirect rule can contain one handler identifier only.

In _redirects, use the EdgeHandler parameter to set up rules like this:

# On requests to `/foo`, execute `logRedirect` or `logInSpanish` handler
# based on country
/foo  /bar       301    EdgeHandler=logRedirect  Country=us
/foo  /bar       301    EdgeHandler=logInSpanish Country=es

# Execute `filterRequests` handler for any browser request to the site
# except for requests that already matched a rule above
/*    /:splat    200    EdgeHandler=filterRequests

In the netlify.toml file, specify the handler's identifier in a [[redirects]] section using the edge_handler keyword like this:

# On requests to `/foo`, execute `logRedirect` handler 
# if `country` is `us`
[[redirects]]
from = "/foo"
to = "/bar"
status = 301
edge_handler = "logRedirect"
conditions = {Country = ["us"]}

# On requests to `/foo`, execute `logInSpanish` handler 
# if `country` is `es`
[[redirects]]
from = "/foo"
to = "/bar"
status = 301
edge_handler = "logInSpanish"
conditions = {Country = ["es"]}

# Execute filterRequests handler for any browser request to the site
# except for requests that already matched a rule above
[[redirects]]
from = "/*"
to = "/:splat"
status = 200
edge_handler = "filterRequests"

Deploy Edge Handlers

Edge Handler deploys are atomic. This means that modifying assets in the edge-handlers directory in a separate branch won't change the behavior of any handlers in production. If you're using continuous deployment, Edge Handlers updates move to production only when you merge changes into your production branch and publish the new production deploy.

You can also deploy a site with Edge Handlers to production using the Netlify CLI deploy command with the --prod flag.

Bundle your code

Since Edge Handlers run in isolation from the rest of your project, they must be bundled before deployment. We handle that step for you using the integrated @netlify/plugin-edge-handlers build plugin. This plugin uses Rollup to bundle your Edge Handler code and any accompanying dependencies into a single JavaScript file.

To test that your handler and any dependencies bundle properly, you can build and then deploy to a unique draft URL for previewing and testing. Run the Netlify CLI build and deploy commands or a combined command.

netlify deploy --build