Get started with Edge Functions

This feature is in BETA.

The Edge Functions beta is enabled by default for all accounts. To try the feature, add edge functions code to your site.

# Create an edge function

Each edge function has two required parts:

  • A function file with logic for modifying requests and responses
  • A declaration associating a path on your site with a function to execute on requests to that path

To create an edge function to deploy with your site, write a JavaScript or TypeScript file stored in your edge functions directory, and declare the edge function in your site’s Netlify configuration file.

  1. Create a function file at netlify/edge-functions/hello.js with the content below:

    export default () => new Response("Hello world");
    

    The edge functions directory netlify/edge-functions is relative to your site’s base directory.

  2. Declare the hello edge function for the /test route by adding the following to netlify.toml:

    [[edge_functions]]
    path = "/test"
    function = "hello"
    

# Test locally

You can use Netlify CLI to test edge functions locally before deploying them to Netlify.

  1. Ensure you have the latest version of Netlify CLI installed:

    npm install netlify-cli -g
    
  2. Launch Netlify Dev to start a development environment that executes edge functions on local requests:

    netlify dev
    
  3. Visit localhost:8888/test to execute the hello edge function declared for the /test route.

Changes to edge functions are applied on new requests.

  1. Edit hello.js to change the Response:

    export default () => new Response("Updated hello!");
    
  2. Save your updated function file.

  3. Reload localhost:8888/test and note that the response has changed.

To debug edge functions locally, launch Netlify Dev with the edgeInspect or edgeInspectBrk flag. For details, visit the CLI docs.

By default, the geo location used is the location of your local environment. To override this to a default mock location of San Francisco, CA, USA, use the --geo=mock flag. To mock a specific country, use --geo=mock --country= with a two-letter country code. For more information about the --geo flag, visit the CLI docs.

# Deploy

Use continuous deployment or Netlify CLI manual deploys to deploy your edge functions.

If a project has TypeScript and JavaScript edge functions with the same name, for example, my-function.ts and my-function.js, the TypeScript function is ignored while the JavaScript function is deployed.

# Invoke

Invoke the deployed production version of your hello edge function declared for the /test route by accessing yoursitename.netlify.app/test

Deploys of edge functions are atomic. This means that when a new deploy includes changes to function logic or declarations, the behavior of edge functions in old deploys won’t be impacted. Updates to edge functions move to production only when you publish a new production deploy.

# Monitor

To access logs for your production edge functions:

  1. In the Netlify UI, visit your site’s Edge Functions tab.

To access logs for other versions of your edge functions:

  1. In the Netlify UI, go to your site’s Deploys tab.
  2. Find the deploy of interest.
  3. Follow the Edge Functions link in the deploy detail page header.

In both cases, Netlify provides a running log for the last 24 hours of activity, including:

  • Timestamp of each invocation
  • Any console statements included in your edge function code