Vercel Middleware Integration

Vercel is a cloud platform that allows to deploy Web applications to the cloud. It is a great platform for deploying static sites, serverless functions, and full-stack applications. This page explains how to integrate redirection.io with a Vercel application.

In order to install redirection.io in your application hosted on Vercel, there are mainly two options:

• using the redirection.io managed instances, which are hosted by redirection.io and do not require any specific setup on your side. This is the easiest way to use redirection.io, but please note that Vercel does not specificaly recommend using a reverse proxy in front of their platform, except if you run the Enterprise plan, which allows for custom networking configurations.
• using the redirection.io Vercel middleware. In the setup, redirection.io will be executed as a middleware in your Vercel application, and will be able to intercept and analyze the requests and responses. Due to Vercel restrictions on 3rd party reverse proxies, this is the recommended way to use redirection.io with Vercel.

Prerequisites

Before starting the integration of redirection.io with your Vercel application, you need to have:

• the ability to install a package in your Vercel application;
• the ability to deploy a Vercel application and to configure environment variables.

Using the redirection.io Vercel middleware

Deploying redirection.io on Vercel requires several steps:

1. create a redirection.io account;
2. create a redirection.io organization and a project. At this step, you may want to invite your co-workers ;
3. Install the redirection.io Vercel middleware in your Vercel application;
4. Configure the redirection.io Vercel middleware with your project key using a Vercel environment variable;
5. Deploy your Vercel application.

Install the redirection.io Vercel middleware

In your Vercel application, install the @redirection.io/vercel-middleware package:

npm install @redirection.io/vercel-middleware

// or with yarn
yarn add @redirection.io/vercel-middleware

This package is available as an open-source package on npm and on our GitHub page.

Use the redirection.io middleware in your application

Once installed, the middleware has to be used by your Vercel application. The approach depends on whether your application already uses a middleware or not.

My application does not have any middleware

If no middleware is currently used by your application, we'll have to create one! To do so, create a new file named middleware.ts in the root of your Vercel application (at the same level as the app or pages folders, possibly in a src folder if your project uses one), and add the following code:

import redirectionioMiddleware from '@redirection.io/vercel-middleware';

export default redirectionioMiddleware;

export const config = {
  unstable_allowDynamic: [
    '/node_modules/@redirection.io/**',
  ],
}

My application already uses a Vercel middleware

If your application already contains Vercel middleware, the integration mode described above will not be suitable for you. Instead, you will need to modify the exiting middleware in order to have the redirection.io middleware wrap it.

Say your current middleware looks like this:

export default async function middleware(req: NextRequest) {
  // here
  // your
  // middleware
  // code
}

export const config = {
  matcher: ['/((?!api|static|.*\\..*|_next|favicon.ico|robots.txt).*)'],
};

Move your code in a dedicated function:

const handle = async (req: NextRequest) => {
  // here
  // your
  // middleware
  // code
};

export const config = {
  matcher: ['/((?!api|static|.*\\..*|_next|favicon.ico|robots.txt).*)'],
};

If your middleware configuration contains the "matcher" option (to restrict hich requests must go though the middleware), you will obviously need to remove it (because you want all the requests to use the redirection.io middleware) and turn it into a check at the top of your middleware function.

Please note that the regular expression is bit different than the one that was in the matcher option: it now starts with a ^ and end with a $

const handle = async (req: NextRequest) => {
  const url = req.nextUrl;

  if (!url.pathname.match("^/((?!api|static|.*\\..*|_next|favicon.ico|robots.txt).*)$")) {
    return NextResponse.next();
  }

  // here
  // your
  // middleware
  // code
};

export const config = {};

Then, use the createRedirectionIoMiddleware from @redirection.io/vercel-middleware/next to wrap your middleware code in the redirection.io middleware:

import { createRedirectionIoMiddleware } from "@redirection.io/vercel-middleware/next";

const handle = async (req: NextRequest) => {
  const url = req.nextUrl;

  if (!url.pathname.match("^/((?!api/|_next/|_static/|_vercel|.*\\..*|[\\w-]+\\.\\w+).*)$")) {
    return NextResponse.next();
  }

  // here
  // your
  // middleware
  // code
};

const middleware = createRedirectionIoMiddleware({ nextMiddleware: handle });
export default middleware;

export const config = {
  unstable_allowDynamic: ["/node_modules/@redirection.io/**"],
};

If you are using pnpm, the install location of the module is not in /node_modules but in a .pnpm folder. In that case, you may rather use unstable_allowDynamic: ["/node_modules/.pnpm/**/@redirection.io/**"],

If your project is not based on Next.js, the code above can be adapted to import from @redirection.io/vercel-middleware instead of @redirection.io/vercel-middleware/next.

Configure the redirection.io Vercel middleware

In the settings of your Vercel application, add a new environment variable named REDIRECTIONIO_TOKEN with the value of your redirection.io project key:

Deploy your Vercel application

Once the redirection.io Vercel middleware is installed and configured, you can deploy your Vercel application. The redirection.io Vercel middleware will be executed on each request, it will analyze the requests and responses and allow for easy response modifications.

Supported environment variables

The behavior of the redirection.io Vercel Middleware can be cusomized using several environment variables to create in the Vercel project settings:

REDIRECTIONIO_TOKEN

• This directive is required
• Description: this is the "project key" of the redirection.io project that the traffic for this site must be associated to

REDIRECTIONIO_ADD_HEADER_RULE_IDS

• This directive is optional
• Default: false
• Description: set this to true to append a response Header X-RedirectionIo-RuleIds containing the executed redirection.io rules identifier, separated by a ;

REDIRECTIONIO_INSTANCE_NAME

• This directive is optional
• Default: redirection-io-vercel-middleware
• Description: this is the name for this Vercel middleware instance, as it should be displayed in the redirection.io manager "instances" screen

REDIRECTIONIO_TIMEOUT

• This directive is optional
• Default: 500
• Description: define the maximal timeout to the redirection.io API calls (in ms). If this timeout is reached, no rule is applied to the request.

Troubleshooting

Which version of Next.js is this middleware compatible with?

The redirection.io Vercel Middleware is compatible with Next.js 14.2 at least.

Why do you use unstable_allowDynamic in the middlware config?

The Next.js documentation explains that some features are disabled in the Next.js Edge runtime, in particular dynamic code execution.

The unstable_allowDynamic configuration directive is a way to relax the static code analysis, and can be used to allow loading specific files in a middleware even if some part of them contain unsupported features. This is particularly useful if you depend on a feature offered by library that bundles such unsupported statements.

The redirection.io middleware relies on the getrandom library to generate some random data when using a samping trigger. Unfortunately, parts of this library, that will never be executed by the redirection.io middleware, can lead to dynamic code execution in very specific conditions (on node.js, when a specific module is not available) that cannot be met when using the middleware.

This is the only reason why unstable_allowDynamic is required to run the redirection.io middleware.