Vercel Middleware Integration - Developer documentation | Documentation

Vercel Middleware Integration

Vercel is a cloud platform that allows to deploy JavaScript-based applications to the cloud. It is a great platform for deploying serverless functions or full-stack applications. This page explains how to integrate redirection.io with a Vercel application.

While this guide focuses on the integration of redirection.io with Vercel, the redirection.io Vercel middleware can be used in any Next.js application, even if it is not deployed on Vercel. It can also be used in non-next.js applications hosted on Vercel - in this case, you should import the middleware from @redirection.io/vercel-middleware instead of @redirection.io/vercel-middleware/next.

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

Prerequisites [Permalink to this section](/content/documentation/developer-documentation/vercel-middleware-integration#prerequisites "Permalink to this section"/index.html)

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

Using the redirection.io Vercel middleware [Permalink to this section](/content/documentation/developer-documentation/vercel-middleware-integration#using-the-redirection-io-vercel-middleware "Permalink to this section"/index.html)

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 [Permalink to this section](/content/documentation/developer-documentation/vercel-middleware-integration#install-the-redirection-io-vercel-middleware "Permalink to this section"/index.html)

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 [Permalink to this section](/content/documentation/developer-documentation/vercel-middleware-integration#use-the-redirection-io-middleware-in-your-application "Permalink to this section"/index.html)

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 [Permalink to this section](/content/documentation/developer-documentation/vercel-middleware-integration#my-application-does-not-have-any-middleware "Permalink to this section"/index.html)

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 (or proxy.ts, depending on your Next.js version) 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/next';

export default redirectionioMiddleware;

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

By default, our middleware ignores certain routes even if there's an exported configuration. The ignored routes are:

If you want to customize which routes the middleware handles, use the createRedirectionIoMiddleware() function and provide your own regex using the matcherRegex option:

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

const middleware = createRedirectionIoMiddleware({
    matcherRegex: "^/((?!api).*)$" // Your regex here
});

export default middleware;

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

If you want the middleware to handle all routes without any exclusions, you can set the matcherRegex option to null:

createRedirectionIoMiddleware({ matcherRegex: null });

My application already uses a Vercel middleware [Permalink to this section](/content/documentation/developer-documentation/vercel-middleware-integration#my-application-already-uses-a-vercel-middleware "Permalink to this section"/index.html)

If your application already contains a Vercel middleware, the integration mode described above will not be suitable for you. Instead, you will need to modify the existing 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 myMiddleware = async (req: NextRequest) => {
  // here
  // your
  // middleware
  // code
};

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

And use the createRedirectionIoMiddleware from @redirection.io/vercel-middleware/next to wrap your middleware code in the redirection.io middleware, thanks to the previousMiddleware or nextMiddleware options.

If you use previousMiddleware, your middleware's code will be executed before redirection.io runs its logic. If you choose nextMiddleware, then it will be executed after redirection.io has been executed (and, potentially, it may not be executed at all if a redirect is to be run):

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

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

const middleware = createRedirectionIoMiddleware({
    previousMiddleware: myMiddleware,  // In this case your middleware is executed before redirection.io middleware
    nextMiddleware: myMiddleware, // In this case your middleware is executed after redirection.io middleware
});

export default middleware;

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

If your middleware configuration contains the "matcher" option (to restrict which requests must go through the middleware), this will be used upstream of our middleware.

If the regex passes, then our middleware will use a second default regex (which ignores Next.js internals and static files):

^/((?!api|static|.*\..*|_next|favicon.ico|robots.txt).*)$

You can modify this regex by default using the matcherRegex option of the createRedirectionIoMiddleware function:

const middleware = createRedirectionIoMiddleware({
    matcherRegex: "^/((?!api/auth).*)$", // Your regex here
});

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

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

Configure next.config.js [Permalink to this section](/content/documentation/developer-documentation/vercel-middleware-integration#configure-next-config-js "Permalink to this section"/index.html)

If your project uses Webpack, you may experience issues to load the WebAssembly module that is used by the redirection.io Vercel middleware. The error would usually look like:

TypeError: WebAssembly.instantiate(): Argument 0 must be a buffer source or a WebAssembly.Module object

To fix this issue, you can add the following configuration in your next.config.js file:

import { redirectionIoWebpackWasmRule } from "@redirection.io/vercel-middleware/webpack";

const nextConfig: NextConfig = {
  webpack: (config, { isServer }) => {
    if (isServer) {
      config.module.rules.push(redirectionIoWebpackWasmRule);
    }

return config;
  },
};

It implements a custom Webpack rule that allows to load the WebAssembly module used by the redirection.io Vercel middleware.

Log the requests by using Vercel's instrumentation [Permalink to this section](/content/documentation/developer-documentation/vercel-middleware-integration#log-the-requests-by-using-vercel-s-instrumentation "Permalink to this section"/index.html)

The redirection.io Vercel middleware can be configured to log the requests to your redirection.io project. To do so, you need to register the redirection.io instrumentation in your application. Create a instrumentation.ts file in the same folder as the proxy.ts (or middleware.ts) file, with the following content:

import { registerRedirectionIoInstrumentation } from "@redirection.io/vercel-middleware/instrumentation";

export const register = async () => {
  registerRedirectionIoInstrumentation();
};

Configure the redirection.io Vercel middleware [Permalink to this section](/content/documentation/developer-documentation/vercel-middleware-integration#configure-the-redirection-io-vercel-middleware "Permalink to this section"/index.html)

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 [Permalink to this section](/content/documentation/developer-documentation/vercel-middleware-integration#deploy-your-vercel-application "Permalink to this section"/index.html)

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 [Permalink to this section](/content/documentation/developer-documentation/vercel-middleware-integration#supported-environment-variables "Permalink to this section"/index.html)

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

REDIRECTIONIO_TOKEN [Permalink to this section](/content/documentation/developer-documentation/vercel-middleware-integration#redirectionio-token "Permalink to this section"/index.html)

REDIRECTIONIO_ADD_HEADER_RULE_IDS [Permalink to this section](/content/documentation/developer-documentation/vercel-middleware-integration#redirectionio-add-header-rule-ids "Permalink to this section"/index.html)

REDIRECTIONIO_INSTANCE_NAME [Permalink to this section](/content/documentation/developer-documentation/vercel-middleware-integration#redirectionio-instance-name "Permalink to this section"/index.html)

REDIRECTIONIO_TIMEOUT [Permalink to this section](/content/documentation/developer-documentation/vercel-middleware-integration#redirectionio-timeout "Permalink to this section"/index.html)

Troubleshooting [Permalink to this section](/content/documentation/developer-documentation/vercel-middleware-integration#troubleshooting "Permalink to this section"/index.html)

Which version of Next.js is this middleware compatible with? [Permalink to this section](/content/documentation/developer-documentation/vercel-middleware-integration#which-version-of-next-js-is-this-middleware-compatible-with "Permalink to this section"/index.html)

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

Do you have any examples of integrating redirection.io with Next.js? [Permalink to this section](/content/documentation/developer-documentation/vercel-middleware-integration#do-you-have-any-examples-of-integrating-redirection-io-with-next-js "Permalink to this section"/index.html)

We offer a repository that includes several examples of integrating Next.js with redirection.io:

Each example comes with detailed setup instructions in their respective sub-directories within the examples repository.

Why do you use unstable_allowDynamic in the middleware config? [Permalink to this section](/content/documentation/developer-documentation/vercel-middleware-integration#why-do-you-use-unstable-allowdynamic-in-the-middlware-config "Permalink to this section"/index.html)

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 sampling 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.

Do I need to change things if I use pnpm instead of npm or yarn? [Permalink to this section](/content/documentation/developer-documentation/vercel-middleware-integration#do-i-need-to-change-things-if-i-use-pnpm-instead-of-npm-or-yarn "Permalink to this section"/index.html)

If you are using pnpm, the install location of the module is not in /node_modules but in a .pnpm folder. In this case, you may use ['/node_modules/.pnpm/**/@redirection.io/**'] as the configuration value for unstable_allowDynamic.

In other words, in this case you would configure your base middleware like this:

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

export default redirectionioMiddleware;

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

This page has been updated on Apr 16, 2026