# Vercel Middleware Integration

[Vercel](https://vercel.com/) 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:

- **using the [redirection.io managed instances](/content/documentation/managed-instances/what-are-managed-instances/index.html)**, 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](https://vercel.com/guides/can-i-use-a-proxy-on-top-of-my-vercel-deployment) in front of their platform. However, it will perfectly work provided you whitelist [the redirection.io managed instances IP addresses](/content/documentation/managed-instances/frequently-asked-questions#which-are-the-managed-instances-proxification-ip-addresses-used-by-redirection-io/index.html) in your Vercel application firewall settings.
- **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 [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:

- 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 [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](/content/manager/register/index.html);
2. [create a redirection.io organization and a project](/content/documentation/user-documentation/what-are-organizations-and-projects/index.html). At this step, you may want to [invite your co-workers](/content/documentation/user-documentation/invite-new-collaborators/index.html);
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:

```bash
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](https://www.npmjs.com/package/@redirection.io/vercel-middleware) and on our [GitHub page](https://github.com/redirectionio/vercel-middleware).

### 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:

```javascript
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:

- `/api/*` routes
- `/next/*` (Next.js internals)
- `/static/*` (inside `/public`)
- all root files inside `/public` (e.g. `/favicon.ico`)

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

```javascript
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`:

```javascript
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:

```javascript
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:

```javascript
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):

```javascript
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):

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

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

```javascript
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:

```bash
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:

```javascript
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:

```javascript
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)

- 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 [Permalink to this section](/content/documentation/developer-documentation/vercel-middleware-integration#redirectionio-add-header-rule-ids "Permalink to this section"/index.html)

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

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

- 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 [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](https://github.com/redirectionio/nextjs-examples) that includes several examples of integrating Next.js with redirection.io:

- **Storyblok Integration**: a demo showcasing how to integrate redirection.io with a Next.js app using [Storyblok CMS](https://www.storyblok.com/).
- **Auth0 Integration**: an example of setting up Next.js with [Auth0](https://auth0.com/) authentication and redirection.io.
- **Next-intl Integration**: a guide demonstrating how to use Next.js with [next-intl](https://github.com/amannn/next-intl) for internationalization, combined with redirection.io.

Each example comes with detailed setup instructions in their respective sub-directories within [the examples repository](https://github.com/redirectionio/nextjs-examples).

### 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](https://nextjs.org/docs/app/api-reference/edge#unsupported-apis), 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](https://github.com/rust-random/getrandom) library to generate some random data when using a [sampling trigger](/content/documentation/user-documentation/triggers-and-markers-reference#the-sampling-trigger/index.html). 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](https://pnpm.io/), 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:

```javascript
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