Installation (Next.js 16)

In Next.js 16, middleware was renamed to proxy. The key differences are:

• File: proxy.ts (or proxy.js) replaces middleware.ts.
• Export: The handler function should be exported as proxy (named export) or as the default export.
• Runtime: Proxy runs on the Node.js runtime by default (middleware previously defaulted to Edge).

The NextRequest and NextResponse APIs remain the same. The HUMAN Enforcer works identically in both conventions—the only difference is the file name and the export name.

Prerequisites

• Next.js 16 or newer
• Node.js 20.9+ (required by Next.js 16)
• An existing Next.js application. If you don’t have one, create a new application.
• Your unique HUMAN information:
  • Application ID
  • Cookie encryption key
  • Authentication token

Installing the NextJS Enforcer

Integrate the HUMAN Enforcer into your NextJS project by setting it as a proxy in your project.

While only one proxy.ts file is supported per project, you can still organize your logic modularly. Placing the HUMAN Enforcer proxy first ensures that all incoming requests are evaluated for security threats before any other processing occurs. If you have additional logic, use the onPass and onResponse custom functions.

Installation

1. Install the HUMAN NextJS Enforcer NPM package into your existing NextJS project.

$
npm install --save perimeterx-nextjs

2. In the root directory of your project, create a proxy.ts (or proxy.js if you’re using JavaScript) file to configure and set up the HUMAN proxy.
3. Initiate a configuration object containing px_app_id (your Application ID), px_cookie_secret (your cookie encryption key), and px_auth_token (your authentication token). Import and use the perimeterx function.

1
import { perimeterx } from "perimeterx-nextjs";
2
import { PerimeterXConfigurations } from "perimeterx-nextjs";
3
4
// define HUMAN configuration
5
const pxConfig: PerimeterXConfigurations = {
6
    px_app_id: '<APP_ID>',
7
    px_cookie_secret: '<COOKIE_SECRET>',
8
    px_auth_token: '<AUTH_TOKEN>',
9
}
10
export const proxy = perimeterx(pxConfig)

Optional: route matcher

To limit which routes the proxy (and thus the Enforcer) runs on, export a config object alongside the proxy:

1
import { perimeterx } from "perimeterx-nextjs";
2
import { PerimeterXConfigurations } from "perimeterx-nextjs";
3
4
const pxConfig: PerimeterXConfigurations = {
5
    px_app_id: '<APP_ID>',
6
    px_cookie_secret: '<COOKIE_SECRET>',
7
    px_auth_token: '<AUTH_TOKEN>',
8
}
9
export const proxy = perimeterx(pxConfig)
10
11
export const config = {
12
    matcher: [
13
        // Run on all paths except static assets and metadata files
14
        '/((?!api|_next/static|_next/image|favicon.ico|sitemap.xml|robots.txt).*)',
15
    ],
16
}

See the Next.js proxy documentation for full matcher syntax.

If you already use middleware/proxy in your project

Add implementation to the built-in onResponse and onPass custom functions in your configuration object, in order to execute your own logic after HUMAN verifies the request.

1
const pxConfig: PerimeterXConfigurations = {
2
    px_app_id: '<APP_ID>',
3
    px_cookie_secret: '<COOKIE_SECRET>',
4
    px_auth_token: '<AUTH_TOKEN>',
5
    onPass: (request: NextRequest) => {
6
        const response = NextResponse.next();
7
        response.headers.set('test-header', 'test');
8
9
        // Return the customized response
10
        return response;
11
    },
12
    // ...
13
}
14
15
export const proxy = perimeterx(pxConfig)

1
const pxConfig: PerimeterXConfigurations = {
2
    px_app_id: '<APP_ID>',
3
    px_cookie_secret: '<COOKIE_SECRET>',
4
    px_auth_token: '<AUTH_TOKEN>',
5
    onResponse: (request: NextRequest, response: NextResponse) => {
6
        const nextResponse = NextResponse.next();
7
        nextResponse.headers.set('X-PX-Status', response.headers.get('test'));
8
9
        // Return the customized response
10
        return nextResponse;
11
    },
12
    // ...
13
}
14
15
export const proxy = perimeterx(pxConfig)

Client IP in the Node.js proxy runtime

In Next.js 16, the proxy runs on the Node.js runtime by default. In some deployment environments, request.ip may not be populated. The Enforcer automatically falls back to the x-forwarded-for header when request.ip is unavailable.

If you run behind a load balancer or reverse proxy and need accurate client IP resolution, configure px_ip_headers so the Enforcer knows which header(s) to use:

1
const pxConfig: PerimeterXConfigurations = {
2
    px_app_id: '<APP_ID>',
3
    px_cookie_secret: '<COOKIE_SECRET>',
4
    px_auth_token: '<AUTH_TOKEN>',
5
    px_ip_headers: ['x-forwarded-for', 'x-real-ip'],
6
}
7
8
export const proxy = perimeterx(pxConfig)

The headers are traversed in the order listed. The first header with a non-empty value is used as the client IP.

Migrating from middleware.ts (Next.js 14/15)

If you are upgrading an existing Next.js 14/15 application that already uses the HUMAN Enforcer via middleware.ts:

1. Rename middleware.ts to proxy.ts.
2. Change the export from export const middleware = perimeterx(pxConfig) (or export default) to export const proxy = perimeterx(pxConfig) (or keep export default).
3. No changes are needed to the configuration object or any onPass/onResponse handlers — they work exactly the same.

Next.js also provides an automated codemod for the rename:

1
npx @next/codemod@canary middleware-to-proxy .

All configuration options from the Configuration page remain fully supported. No changes to Enforcer configuration are required when upgrading to Next.js 16.