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 default edge functions directory netlify/edge-functions is relative to your site’s base directory. Alternatively, you can specify a custom edge functions directory with the edge_functions key in netlify.toml. For example, to use the my-custom-directory directory, add the following to the build section in netlify.toml:

    [build]
    edge_functions = "my-custom-directory"
    
  2. Declare the hello edge function for the /test route by adding the following to netlify.toml:

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

You also have the option to use .jsx and .tsx files for your edge functions. This can be helpful if you want your function to handle server-side rendering (SSR) at the network edge.

For example, this .tsx file contains the code to stream React SSR at the edge without a meta-framework:

import React from 'https://esm.sh/react'
import { renderToReadableStream } from 'https://esm.sh/react-dom/server'
import { Context } from 'https://edge.netlify.com/'

export default async function handler(req: Request, context: Context) {
  const stream = await renderToReadableStream(
    <html>
      <title>Hello</title>
      <body>
        <h1>Hello {context.geo.country?.name}</h1>
      </body>
    </html>,
  )

  return new Response(stream, {
    status: 200,
    headers: { 'Content-Type': 'text/html' },
  })
}

# 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, along with the name of the edge function that generated the output.

To make debugging easier, you can filter the logs by edge function name or path. If desired, you can also use pattern matching as part of your query.