Skip to main content

Add Edge Function

This section explains how to configure and enable edge-side personalization on Netlify.

Before you start

Front-end framework use

This guide is using Next.js as the front-end framework, however, this approach is compatible with any server-side renderable React or Vue meta-frameworks. Please contact us if you are using a different framework and need help putting it together.

You must have the following available in order to complete the instructions in this section:

  1. Ability to clone a GitHub repository.
  2. Node.js v16+ installed locally.
  3. An application with edge-side personalization activated.
  4. The application configured to be deployed to Netlify. You can use their free tier if you do not have an account.
  5. The Netlify CLI is installed and configured. See instructions above.
  6. npm access token from Uniform. Edge-side personalization requires private packages. If you do not have an access token, contact us. :::

Configure CLI

Netlify CLI enables you to send commands to Netlify without having to log into the Netlify dashboard. In fact, some Netlify functionality is not available through the dashboard.

  1. Install Netlify CLI with:
    npm install netlify-cli -g
  2. Authenticate to Netlify with:
    netlify login

Now you are ready to create the Netlify Edge Function, which executes the personalization instructions exposed by your front-end application.

Pick your journey

This guide provides the following options to get started:

  1. Option 1 - if you would like to start with a more feature rich demo to experience the power of edge-side personalization.
  2. Option 2 - if you would like to go through all the steps to add an edge function into your application and understand all the mechanics first.
  3. Option 3 - if you are starting a new project and would like to begin with a "hello world" starter kit.

Option 1: Quick start demo

This section guides you through the process of getting a pre-built sample application deployed and running on Netlify with personalization executed using Netlify Edge Functions.

Before you start

Do not use this application as a foundation or starting point to build your own application. This is a sample app designed to demonstrate edge-side personalization using Netlify Edge Functions.

You must have the following available in order to complete the instructions in this section:

  1. Ability to clone a GitHub repository.
  2. Node.js v16+ installed locally.
  3. The Netlify CLI is installed and configured. See instructions above.
  4. Npm access token from Uniform. Edge-side personalization requires private packages. If you do not have an access token, contact us.
  1. Open a terminal and enter the following:

    git clone https://github.com/uniformdev/examples.git
    cd examples/context-edge-netlify
  2. Ensure your npm access token is configured properly.

    About this step

    The sample code includes a file .npmrc that is set to look for an environment variable NPM_TOKEN. You can set an environment variable on your workstation to your npm access token in order to meet this requirement.

    Another option is to set your npm access token directly in the .npmrc file.

  3. Enter the following command:

    npm install
    Beware

    If you get an error like the following, the problem is most likely that either you do have have your npm access token configured correctly, or the access token has expired:

    '@uniformdev/context-edge-netlify@^17.0.0' is not in this registry.
  4. Enter the following command, which runs a local instance of Netlify, allowing you to experience the edge-side personalizaiton before deploying it:

    netlify dev
  5. Open your browser to the following URL:

    http://localhost:8888/?utm_campaign=unfrmconf

    You should see the personalized hero for "Call for papers".

  6. In your browser, disable JavaScript. You should still see the personalized hero because personalization is happening in the Netlify Edge Function, not in the browser.

  7. Enter the following command:

    netlify deploy --build --prod
  8. After the application is deployed, you can visit the site to see personalization executed by Netlify Edge Functions.

Option 2: Add Edge Function to your app

This section guides you through the process of activating edge-side personalization on an existing web application using Netlify Edge Functions.

If you do not have your own application and you just want to see a working example as quickly as possible, see the Option 2 and Option 3 below.

Step 1: Add Uniform Context into your app

First, make sure your web app is instrumented with Uniform Context SDK and configured to run in edge mode by following this guide. These steps are independent of which CDN you are using.

Step 2: Create your Edge Function

This section guides you through the process of building a Netlify Edge Function that can execute Uniform personalization instructions by explaining each step. It takes longer to go through, but it will help you understand why each line of code is needed.

  1. Add the following environment variable to your workstation:

    NameValue
    NPM_TOKEN
    The npm access token from Uniform.
    About this step

    You cannot set this value in the .env file. That file defines environment varibles available within your app, while this environment is needed by another app (i.e. npm).

    You can set the environment variable to be system wide or just active in your current terminal.

  2. Add the .npmrc file to the root of your application. This file ensures you can access the private packages required for edge-side personalization:

    /.npmrc
    //registry.npmjs.org/:_authToken=${NPM_TOKEN}
    engine-strict = true
  3. Add the following package that includes the SDK to execute personalization via Netlify Edge Functions:

    npm install @uniformdev/context-edge-netlify
  4. Add the following packages as dev dependencies to add cross-platform utility to copy files and run multiple npm scripts (this is optional if you'd like to manage the copy:deno npm script differently):

    npm install shx --save-dev
    npm install npm-run-all --save-dev
  5. Add the following two npm scripts to package.json:

    /package.json
      "scripts": {
    "copy:deno": "shx cp node_modules/@uniformdev/context-edge-netlify/dist/index.deno.js lib/uniform",
    "postinstall": "run-s copy:deno"

    Netlify Edge Functions run in the Deno runtime instead of Node.js. The package @uniformdev/context-edge-netlify is Deno-compatible. The file in this package must be packaged with the Edge Function during the build process. This script copies the file to a place where it can be picked up at build-time.

  6. Run the following command to copy the deno file to expected location:

    npm run copy:deno
  7. Create an empty context-middleware.ts file under /netlify/edge-functions folder.

  8. Add the following imports:

    /netlify/edge-functions/context-middleware.ts
    import {
    createEdgeContext,
    createUniformEdgeHandler,
    } from "../../lib/uniform/index.deno.js";
    import manifest from '../../contextManifest.json' assert { type: 'json' };
    // @ts-ignore: deno imports failing next build
    import type { Context } from "netlify:edge";

    This import statement assumes the name and location of your Uniform manifest. If you file is in another location, you will need to change this statement.

  9. Add the edge function body:

    /netlify/edge-functions/context-middleware.ts
    export default async (request: Request, netlifyContext: Context) => {
    const IGNORED_PATHS = /\/.*\.(ico|png|jpg|jpeg|svg|css|js|json)(?:\?.*|$)$/g;

    if (request.method.toUpperCase() !== "GET" || request.url.match(IGNORED_PATHS)) {
    return await netlifyContext.next({ sendConditionalRequest: true });
    }

    // this creates the context object that has controls how the personalization process works.
    const context = createEdgeContext({
    manifest,
    request,
    });

    // This code creates the component that makes a request
    // to the origin and executes any personalization instructions in the response.
    const originResponse = await netlifyContext.next();
    const handler = createUniformEdgeHandler();

    // This code uses the proxy edge handler to make a request to the
    // origin and execute the personalization instructions in the response.
    const { processed, response } = await handler({
    context,
    request,
    response: originResponse,
    });

    if (!processed) {
    return response;
    }

    return new Response(response.body, {
    ...response,
    headers: {
    // ...response.headers, Symbol cannot be destructured
    'Cache-Control': 'no-store, must-revalidate',
    'Content-Type': 'text/html; charset=utf-8', // To apply automatic deno compression, more info https://deno.com/deploy/docs/compression
    Expires: '0',
    },
    });
    };
    About this step

    The Netlify Edge Function will be applied to all paths. (This is not a requirement. It is simply the way this example is implemented.) Therefore, the function will need to know which paths it should evaluate and which it should not. The paths that match this expression are known to be static files that have no personalization instructions in them.

    The function passes control back to Netlify if the request that is not an HTTP GET or if it matches the ignored path expression. This means the Netlify Edge Function will not try to execute personalization instructions for the request.

Step 3: Deploy your application

  1. Add the following file:

    /netlify.toml
    [[plugins]]
    package = "@netlify/plugin-nextjs"

    [[edge_functions]]
    path = "/*"
    function = "context-middleware"
    About this step

    Netlify uses this file during the build and deployment process. This file provides the following instructions to Netlify:

    • Use the Next.js plugin during the build process.
    • Route all requests to the specified Edge Function.
  2. Enter the following command to do a production build and deployment of the site:

    netlify deploy --build --prod

    During the build process you will see log messages in the console.

  3. In Netlify, navigate to Deploys, where you will see your application was deployed:

    deploys
  4. Click the deployment and you will see the edge functions were deployed:

    deploy-summary
  5. After the application is deployed, you can visit the site to see personalization executed by Netlify Edge Functions.

    You can confirm personalization is running in Netlify if you have personalization based on a query string parameter. Disable JavaScript on your browser and then view a page with personalization. If you see personalized content, you know the personalization was executed in Netlify.

Next steps

Now that you have Netlify delivering edge-side personalization, you might want to take advantage of another feature available when you run personalization using Netlify Edge Functions: location-based personalization.

Option 3: Use Next.js starter

If you are kicking off a new project using Next.js, consider using this option.

Before you start

You must have the following available in order to complete the instructions in this section:

  1. Ability to clone a GitHub repository.
  2. Node.js v16+ installed locally.
  3. The Netlify CLI is installed and configured. See instructions above.
  4. Npm access token from Uniform. Edge-side personalization requires private packages. If you do not have an access token, contact us.

Step 1: Get started locally

  1. Open a terminal and enter the following:

    git clone https://github.com/uniformdev/examples.git
    cd examples/netlify-edge-functions-nextjs-starter
  2. Ensure your npm access token is configured properly.

    About this step

    The sample code includes a file .npmrc that is set to look for an environment variable NPM_TOKEN. You can set an environment variable on your workstation to your npm access token in order to meet this requirement.

    Another option is to set your npm access token directly in the .npmrc file.

  3. Enter the following command:

    npm install
    Beware

    If you get an error like the following, the problem is most likely that either you do have have your npm access token configured correctly, or the access token has expired:

    '@uniformdev/context-edge-netlify@^17.0.0' is not in this registry.
  4. Enter the following command, which runs a local instance of Netlify, allowing you to experience the edge-side personalizaiton before deploying it:

    netlify dev
  5. Open your browser to the following URL:

    http://localhost:8888/?utm_campaign=launch

    You should see the personalized hero matching the signal that evaluates when utm_campaign=launch is on the http request.

  6. In your browser, disable JavaScript. You should still see the personalized hero because personalization is happening in the Netlify Edge Function, not in the browser.

Step 2: Deploy this app to your own Netlify account

Run this command to build and deploy this app to production:

netlify deploy --build --prod

After the application is deployed, you can visit the site to see personalization executed by Netlify Edge Functions.

Step 3: Wire this app to your own Uniform project

  1. Signup for a free Uniform account here.
  2. If that's your first time creating a team, your first project will have the Hello World starter already installed.
  3. Head over to the Project Integrations -> Hello World
  4. Scroll to the section where steps 1-4 are displayed and click on the "Generate environment variables" button.
  5. Paste this environment variables into your .env file instead of the demo environment variables.

Now you are connected to your own Uniform project. You can now re-deploy it.