Vercel setup

This section explains how to configure and enable edge-side personalization 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.
2. Login to Vercel.

Next steps

Now you are ready to create the Vercel Edge Middleware, which is the component that executes the personalization instructions exposed by your front-end application.

Activation for your application

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

tip

If you do not have your own application and you just want to see a working example as quickly as possible, see the personalization demo.

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 v14+ 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 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.

Write Vercel Edge Middleware code

Next.js version alert

The code in this example is compatible with Next.js version 12.1.x. Changes introduced in version 12.2.0 prevent this approach from working. We are working to update our implementation to support the v12.2.0 API.

You have two options for writing the Vercel Edge Middleware. You can build it from scratch or use a functional example provided by Uniform.

Steps

tip

This section guides you through the process of building a Vercel Edge Middleware 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:

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

   This file ensures you can access the private packages required for edge-side personalization.

3. Open a terminal to the root of your web application.

4. Enter the following command:

   vercel link
   About this step

   For more information on project linking, see the Vercel documentation.

5. Add the following packages:

   @uniformdev/context-edge
   @uniformdev/context-edge-vercel
   buffer
   About this step

   This package includes the components needed to execute personalization instructions in Vercel Edge Middleware.

6. Add the following file:

   /pages/_middleware.js

   import { NextResponse } from "next/server";
   import { createEdgeContext } from "@uniformdev/context-edge";
   import { createUniformEdgeMiddleware } from "@uniformdev/context-edge-vercel";
   About this step

   This imports functions from the file you copied in the previous step.

7. Add the following code:

   import manifest from "../contextManifest.json";
   About this step

   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.

8. Add the following code:

   const IGNORED_PATHS = /\/.*\.(ico|png|jpg|jpeg|svg|css|js|json)(?:\?.*|$)$/g;
   About this step

   The Vercel Edge Middleware will be applied to all paths. 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.

9. Add the following code:

   export default async function middleware(request) {
   };
   About this step

   This is the function that runs when the Vercel Edge Middleware is invoked.

10. Add the following code:

    export default async function middleware(request) {
      if (process.env.NODE_ENV === "development") {
        console.log("Middleware disabled in development");
        return;
      }
    };
    About this step

    This function passes control back to Vercel if the application is running in development mode.

11. Add the following code:

    export default async function middleware(request) {
      if (process.env.NODE_ENV === "development") {
        console.log("Middleware disabled in development");
        return;
      }
    
      if (!process.env.VERCEL_URL) {
        console.error("VERCEL_URL environment is not defined");
        return new Response("Configuration Error", {
          status: 500,
        });
      }
    };
    About this step

    This function returns an error if the code is not being run on Vercel.

12. Add the following code:

    export default async function middleware(request) {
      if (process.env.NODE_ENV === "development") {
        console.log("Middleware disabled in development");
        return;
      }
    
      if (!process.env.VERCEL_URL) {
        console.error("VERCEL_URL environment is not defined");
        return new Response("Configuration Error", {
          status: 500,
        });
      }
    
      if (
        request.method.toUpperCase() !== "GET" ||
        request.nextUrl.pathname.match(IGNORED_PATHS)
      ) {
        return NextResponse.next();
      }
    };
    About this step

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

13. Add the following code:

    export default async function middleware(request) {
      if (process.env.NODE_ENV === "development") {
        console.log("Middleware disabled in development");
        return;
      }
    
      if (!process.env.VERCEL_URL) {
        console.error("VERCEL_URL environment is not defined");
        return new Response("Configuration Error", {
          status: 500,
        });
      }
    
      if (
        request.method.toUpperCase() !== "GET" ||
        request.nextUrl.pathname.match(IGNORED_PATHS)
      ) {
        return NextResponse.next();
      }
    
      const context = createEdgeContext({
        manifest,
        request,
      });
    };
    About this step

    This creates the context object that has controls how the personalization process works.

14. Add the following code:

    export default async function middleware(request) {
      if (process.env.NODE_ENV === "development") {
        console.log("Middleware disabled in development");
        return;
      }
    
      if (!process.env.VERCEL_URL) {
        console.error("VERCEL_URL environment is not defined");
        return new Response("Configuration Error", {
          status: 500,
        });
      }
    
      if (
        request.method.toUpperCase() !== "GET" ||
        request.nextUrl.pathname.match(IGNORED_PATHS)
      ) {
        return NextResponse.next();
      }
    
      const context = createEdgeContext({
        manifest,
        request,
      });
    
      const middleware = createUniformEdgeMiddleware();
    };
    About this step

    This code creates the component that makes a request to the origin and executes any personalization instructions in the response.

15. Add the following code:

    export default async function middleware(request) {
      if (process.env.NODE_ENV === "development") {
        console.log("Middleware disabled in development");
        return;
      }
    
      if (!process.env.VERCEL_URL) {
        console.error("VERCEL_URL environment is not defined");
        return new Response("Configuration Error", {
          status: 500,
        });
      }
    
      if (
        request.method.toUpperCase() !== "GET" ||
        request.nextUrl.pathname.match(IGNORED_PATHS)
      ) {
        return NextResponse.next();
      }
    
      const context = createEdgeContext({
        manifest,
        request,
      });
    
      const middleware = createUniformEdgeMiddleware();
    
      const response = await middleware({
        context,
        origin: new URL(`https://${process.env.VERCEL_URL}`),
        request,
      });
    };
    About this step

    This code uses the proxy edge handler to make a request to the origin and execute the personalization instructions in the response.

16. Add the following code:

    export default async function middleware(request) {
      if (process.env.NODE_ENV === "development") {
        console.log("Middleware disabled in development");
        return;
      }
    
      if (!process.env.VERCEL_URL) {
        console.error("VERCEL_URL environment is not defined");
        return new Response("Configuration Error", {
          status: 500,
        });
      }
    
      if (
        request.method.toUpperCase() !== "GET" ||
        request.nextUrl.pathname.match(IGNORED_PATHS)
      ) {
        return NextResponse.next();
      }
    
      const context = createEdgeContext({
        manifest,
        request,
      });
    
      const middleware = createUniformEdgeMiddleware();
    
      const response = await middleware({
        context,
        origin: new URL(`https://${process.env.VERCEL_URL}`),
        request,
      });
    
      return new Response(response.body, {
        ...response,
        headers: {
          ...response.headers,
          "Cache-Control": "no-store, must-revalidate",
          Expires: "0",
        },
      });
    };
    About this step

    This code creates a new response using the result of the middleware function.

17. Enter the following command:

    npm run build
    About this step

    This ensures the build process is working.

Complete

tip

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:

   Name	Value
   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:

   /pages/_middleware.js

   import { NextResponse } from "next/server";
   import { createEdgeContext } from "@uniformdev/context-edge";
   import { createUniformEdgeMiddleware } from "@uniformdev/context-edge-vercel";
   import manifest from "../contextManifest.json";
   
   const IGNORED_PATHS = /^\/.*\.(ico|png|jpg|jpeg|svg)$/g;
   
   export default async function middleware(request) {
     if (process.env.NODE_ENV === "development") {
       console.log("Middleware disabled in development");
       return;
     }
   
     if (!process.env.VERCEL_URL) {
       console.error("VERCEL_URL environment is not defined");
       return new Response("Configuration Error", {
         status: 500,
       });
     }
   
     if (
       request.method.toUpperCase() !== "GET" ||
       request.nextUrl.pathname.match(IGNORED_PATHS)
     ) {
       return NextResponse.next();
     }
   
     const context = createEdgeContext({
       manifest,
       request,
     });
   
     const middleware = createUniformEdgeMiddleware();
   
     const response = await middleware({
       context,
       origin: new URL(`https://${process.env.VERCEL_URL}`),
       request,
     });
   
     return new Response(response.body, {
       ...response,
       headers: {
         ...response.headers,
         "Cache-Control": "no-store, must-revalidate",
         Expires: "0",
       },
     });
   }
   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. Enter the following command:

   npm run build
   About this step

   This ensures the build process is working.

Deploy your application

1. Enter the following command:

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

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

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

   About this step

   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.

Personalization demo

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

tip

If you have your own personalized application and you want it to run on Netlify using Vercel Edge Middleware, see the section on activation for your application.

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 v14+ installed locally.
3. The Vercel 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.

About this demo app

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. It does not implement best practices or follow any patterns that you might expect of an app designed to be used in production.

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

   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.