Next.js Middleware Quickstart

The fastest way to add PerfectSearch to a Next.js application is with the Edge Middleware package. Install the package, add a middleware file, set two environment variables, and every bot request will be intercepted at the edge and served a pre-rendered snapshot — no infrastructure changes required.

What do I need before starting?

You need a Next.js 14 or 15 project with the App Router or Pages Router, a PerfectSearch account, and a site created in the PerfectSearch dashboard. The middleware runs on Vercel Edge Runtime or any platform that supports the Web standard Request and Response APIs.

• Next.js 14.x or 15.x
• A PerfectSearch account — sign up free
• A site created in the PerfectSearch dashboard with your production domain

How do I install the middleware package?

Install the @perfectsearch/middleware package from npm using your preferred package manager. The package is lightweight with zero external dependencies and runs entirely on the Edge Runtime, so it adds no measurable latency to human visitor requests.

bun add @perfectsearch/middleware

Or with npm:

npm install @perfectsearch/middleware

How do I configure middleware.ts?

Create a middleware.ts file at the root of your project (next to next.config.ts). The middleware intercepts every incoming request, checks the User-Agent against known bot signatures, and serves a pre-rendered snapshot for bots while letting human traffic pass through untouched.

import { perfectSearchMiddleware } from '@perfectsearch/middleware';

export const middleware = perfectSearchMiddleware({
  apiKey: process.env.PERFECTSEARCH_API_KEY!,
});

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

The matcher pattern excludes Next.js internals, API routes, and the favicon. Adjust the pattern if you have additional static paths you want to skip.

How do I set environment variables?

The middleware requires one environment variable to authenticate your site with the PerfectSearch Snapshot API. You can find your API key in the PerfectSearch dashboard under your site's Settings page. Add it to your .env.local file for local development and to your hosting provider for production.

PERFECTSEARCH_API_KEY=your-api-key-from-dashboard

• PERFECTSEARCH_API_KEY— Generated under Settings → API Keys

How do I verify the integration?

After deploying with the middleware configured, use the PerfectSearch Visibility Test tool to confirm that bots receive pre-rendered content. The tool sends a request with a bot User-Agent to your URL and shows you exactly what search engines and AI crawlers see, including the response headers PerfectSearch adds.

Open the Visibility Test tool →

You can also verify manually by sending a request with a known bot User-Agent string and checking for the x-perfectsearch: hit response header.