Add Edge Middleware
Before you start
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:
- Ability to clone a GitHub repository.
- Node.js v16+ installed locally.
- An application with edge-side personalization activated.
- The application configured to be deployed to Vercel. You can use their free tier if you do not have an account.
- The Vercel CLI is installed and configured. See instructions above.
- 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.
Pick your journey
This guide provides the following options to get started:
- Option 1 - if you would like to start with a more feature rich demo to experience the power of edge-side personalization.
- 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.
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.
Open a terminal and enter the following:
git clone https://github.com/uniformdev/examples.git
cd examples/context-edge-vercel
Ensure your npm access token is configured properly.
About this stepThe sample code includes a file
.npmrc
that is set to look for an environment variableNPM_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.Enter the following command:
npm install
About this stepIf 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.
Enter the following command:
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 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.
Add the following environment variable to your workstation:
Name Value NPM_TOKEN
The npm access token from Uniform. About this stepYou 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.
Add the following file to the root of your application:
/.npmrc//registry.npmjs.org/:_authToken=${NPM_TOKEN}
engine-strict = trueRun the following command:
npm i @uniformdev/context-edge @uniformdev/context-edge-vercel buffer
Add the following file into the same level as your
/pages
directory:File location is importantPlease 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.tsimport { 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 stepThe 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.
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.jsconst 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.
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.