Skip to main content

Add Edge Middleware

Before you start​

Next.js 13 required, 13.1 is recommended

Next.js 13 introduced a capability to rewrite response body at the edge, which is required to run Uniform edge-side personalization. We specifically recommend using Next.js 13.1 where the feature this capability is built on is not experimental anymore.

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 Vercel. You can use their free tier if you do not have an account.
  5. The Vercel 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.

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

Configure CLI​

Vercel CLI enables you to send commands to Vercel without having to log into the Vercel dashboard.

  1. Install Vercel CLI with:
    npm i -g vercel
  2. Login to Vercel with:
    vercel login

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.

Option 1: Quick start demo​

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

tip

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 Vercel Edge Middleware.

If you have your own personalized application and you want it to run on Vercel using Vercel Edge Middleware, see this option instead.

  1. Open a terminal and enter the following:

    git clone https://github.com/uniformdev/examples.git
    cd examples/context-edge-vercel

  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
    About this step

    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@^17.0.0' is not in this registry.

  4. Enter the following command:

    vercel --build-env NPM_TOKEN=[!!! YOUR NPM TOKEN !!!] --prod

    You must replace [!!! YOUR NPM TOKEN !!!] with your npm access token.

  5. After the application is deployed, you can visit the site to see personalization executed by Vercel Edge Middleware. You can now disable JavaScript and experience personalization without any JS runtime!

    https://yourapp.vercel.app/?utm_campaign=unfrmconf

Option 2: Add edge-side personalization into your application​

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

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: Add Vercel Edge Middleware​

This section gets you to having a Vercel Edge Middleware that can execute Uniform personalization instructions as quickly as possible. It does not explain each line of code.

  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 following file to the root of your application:

    /.npmrc
    //registry.npmjs.org/:_authToken=${NPM_TOKEN}
    engine-strict = true

  3. Run the following command:

    npm i @uniformdev/context-edge @uniformdev/context-edge-vercel buffer

  4. Add the following file into the same level as your /pages directory:

    File location is important

    Please double check the location of this file. It should be located in the same level as the /pages directory. If this file is placed in incorrect location, Vercel will not build and deploy edge middleware.

    /middleware.ts
    import { NextRequest, NextResponse } from "next/server";
    import {
      Context,
      CookieTransitionDataStore,
      ManifestV2,
    } from "@uniformdev/context";
    import { createUniformEdgeMiddleware } from "@uniformdev/context-edge-vercel";
    import manifest from "./lib/uniform/context-manifest.json";

    export async function middleware(request: NextRequest) {
      const path = request.nextUrl.pathname;
      const data = request.headers.get("x-nextjs-data");
      // add more ignore path filters so you do not process more requests than needed
      if (path.startsWith("/images") || path.startsWith("/_next") || Boolean(data)) {
        return NextResponse.next();
      }

      const context = new Context({
        defaultConsent: true,
        manifest: manifest as ManifestV2,
        transitionStore: new CookieTransitionDataStore({
          serverCookieValue: request.headers.get("cookie") || "",
        }),
      });

      const handler = createUniformEdgeMiddleware();

      const response = await handler({
        context,
        origin: new URL(request.url),
        request,
      });

      response.headers.set("Cache-Control", "no-cache, no-store, must-revalidate");

      return response;
    }

    About this step

    The manifest 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.

  5. Only if you are running a version of Next.js earlier than 13.1, you will need to add a special experimental setting in order to allow the edge middleware to modify the response body, add allowMiddlewareResponseBody=true to next.config.js:

    next.config.js
    const nextConfig = {
      experimental: {
        allowMiddlewareResponseBody: true,
      },
    };

    module.exports = nextConfig;

Step 2: Build the app​

You can run the build locally with:

npm run build

Step 3: Deploy your application​

Run the following command to build your app locally and deploy to Vercel:

vercel --build-env NPM_TOKEN=[!!! YOUR NPM TOKEN !!!] --prod

You must replace [!!! YOUR NPM TOKEN !!!] with your npm access token.

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

You can confirm personalization is running in Vercel 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 Vercel.

Next steps

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