Install Qlyne on a Next.js app

For a Next.js app on Vercel, or on any host that runs Next.js, without Cloudflare. Qlyne runs as the app’s middleware and decides before each page and API route. On Next.js it runs the waiting room and rate limits, and passes signals to your app.

1. Add the file and the middleware

In the dashboard, open your site, Connector › Configuration, “Install on Next.js”, and click Download qlyne-next.mjs. The file already carries your site ID, the Qlyne address and the key that checks the rules. Put it at the root of the project, next to package.json.

Create proxy.js at the root too (Next.js 16; on Next.js 13 to 15 the file is middleware.js, with the same content):

import { qlyne } from './qlyne-next.mjs';

export default qlyne();
export const config = { matcher: ['/((?!_next/static|_next/image|favicon.ico).*)'] };

The matcher keeps Next.js’s own files out, so they don’t count as visits. If the project already has a middleware, call Qlyne first and keep yours for what Qlyne lets through:

import { qlyne } from './qlyne-next.mjs';

const protect = qlyne();

export default async function proxy(request, event) {
  const response = await protect(request, event);
  if (!response.headers.get('x-middleware-next')) return response; // refused or sent to the waiting room
  return yourMiddleware(request, event);
}

2. Add the secret and deploy

Add the environment variable QLYNE_SECRET with the connector secret (in Connector › Configuration, “Generate secret”). On Vercel: Settings, Environment Variables, for Production and Preview. Then deploy.

Leave the mode on “Observe only” at first and check the last 24 hours in the site Overview. When the numbers make sense, switch to “Enforce” in Connector › Configuration. Changes reach the middleware within a minute, with no new deploy.

What works and what doesn’t

A middleware decides before the app answers, but never sees the answer. So:

Rule	On Next.js
Waiting room	Yes, by rate, without the cap on people at once (see Waiting Room)
Rate limits	Counted by the Qlyne server, adding up every instance of your app (one call to Qlyne on limited routes, about tens of milliseconds); if it doesn’t answer in time, each instance counts on its own until it’s back. qlyne({ rateLimit: 'memory' }) keeps the count in each instance only
Signals to your app	Yes, as request headers, like Qlyne-Country (the country comes from Vercel, x-vercel-ip-country)
Protected forms	No: the middleware can’t add the hidden fields to the page. Use the form captcha

Read the signals in a route handler or server component with headers() from next/headers.

The rest of the dashboard (bot score and challenge, IP lists, your rules, managed rules, login protection, access gates, security headers) is not supported on Next.js yet. For those, use the Qlyne proxy or the Cloudflare connector.

The visitor’s IP

On Vercel the middleware reads the IP from x-real-ip and x-forwarded-for, which Vercel sets and the visitor can’t forge. On your own server, make sure the reverse proxy in front of Next.js (nginx, Caddy) overwrites those headers with the real address; otherwise a visitor could send a fake one and dodge the per-IP limits.

Updating

The version is on the first line of the file. To update, download it again, replace it and deploy. Your rules stay in the dashboard; the file only carries the code.