Edge Handlers are scripts that run directly from Netlify CDN edge nodes. They allow dynamically affecting traffic to and from your site. You can personalize your visitors' site experience through programmable routing. Edge handlers can:

• Filter incoming HTTP requests
• Manipulate HTTP requests and responses

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.

Limitations

• Memory limit: 256 megabytes
• Execution time limit: 50 milliseconds

If a handler goes over a limit it will terminate abruptly and the request will fail to complete. If you want additional memory and execution time for your handlers and also like having less money you can contact Netlify's sales team.

In handler code, dynamic import statements for dependencies aren't allowed. You can't include dependencies at run time, and your code must be completely isolated before Netlify runs it. All dependencies must be bundled inside the Edge Handler before the artifact is deployed to our edge nodes.

Configure and deploy

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.

Configure Edge Handlers

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.

/old-path  /new-path       301    EdgeHandler=logRedirect  Country=us
/old-path  /new-path       301    EdgeHandler=logInSpanish Country=es
/*         /:splat         200    EdgeHandler=filterRequests

Identifiers are used that match handler file names. Specify the handler’s identifier in a [[redirects]] section using the edge_handler keyword.

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 meaning that modifying assets in the edge-handlers directory in a separate branch won’t change the behavior of any handlers in production. With CI/CD, 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. (--trafficMesh flag is early access)

netlify dev --trafficMesh

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

Build an Edge Handler

Netlify supports Edge Handlers written in JavaScript. All handlers have a similar structure. You can use them to intercept or manipulate an incoming HTTP request or to transform an HTTP response.