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 Forums 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 `/old-path`, execute `logRedirect` or `logInSpanish` handler
# based on country
/old-path  /new-path       301    EdgeHandler=logRedirect  Country=us
/old-path  /new-path       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 `/old-path`, execute `logRedirect` handler
# if `country` is `us`
[[redirects]]
from = "/old-path"
to = "/new-path"
status = 301
edge_handler = "logRedirect"
conditions = {Country = ["us"]}

# On requests to `/old-path`, execute `logInSpanish` handler
# if `country` is `es`
[[redirects]]
from = "/old-path"
to = "/new-path"
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

# Local development

To develop and test Edge Handlers locally before deploying them to Netlify, install Netlify CLI and use Netlify Dev to start a development environment that executes your handlers on local requests.

Enter the following command from your project’s root directory to start the environment. (The --edgeHandlers flag is in early access.)

netlify dev --edgeHandlers

This command inspects your project for Edge Handler sources and reloads them whenever you make a modification.

# Geolocation

Netlify uses a commercial localization database to add visitor geolocation data to each handler request’s payload. This localization database is not provided in the development environment.

There are two options for working with and testing geolocation data in a development environment. You can use your own location database or inject Geolocation information.

# Use your own location database

You can download your own location database in MaxMind DB (MMDB) format and start a public live session to get an address for your local environment.

Enter the following command to launch a public live session with Edge Handler support. (The --edgeHandlers flag is in early access.)

netlify dev --edgeHandlers --live --location-db /PATH_TO_FILE/ip-db.mmdb

The --live flag creates a unique subdomain for your local session under netlify.live. Your Edge Handler receives your public IP address once you use the URL to access your site. --location-db specifies the path to the location database you downloaded earlier.

# Inject geolocation information

You can also inject the geolocation information you’d like to test directly into your request headers.

For example, if you want to test a handler’s behavior from a different country, you can set the X-NF-Country-Code header in a curl request like this:

curl -H 'X-NF-Country-Code: ES' http://localhost

If you want to modify the request headers that your browser sends to a local handler, use a browser extension like ModHeader.

You can find more information on the geolocation headers we inject into each request in the Edge Handlers API overview.