nxpage

Serve structured JSON for AI agents/crawlers while keeping normal Next.js behavior for regular users.

Why nxpage

nxpage is designed for traffic from AI agents and crawlers (for example ChatGPT/OpenAI agents, Claude/Anthropic, Perplexity, and similar systems).

Instead of sending heavy browser-focused HTML and hydration payloads, NxPage can return compact JSON data for those requests.

Benefits:

• faster response for bot/agent traffic,
• significantly lower bandwidth and transfer costs,
• less server load for non-human traffic,
• consistent machine-readable page output.

For bot-targeted responses, transfer size can drop by up to ~99% depending on the page content.

How it works (two outputs)

NxPage uses the same Next.js build as input, then creates two different response outputs:

1. Human output (HTML build)
   Standard Next.js pages generated by next build and served normally for human/browser traffic.
2. Bot output (JSON build)
   NxPage reads generated HTML files and creates per-route JSON pages for AI agents.

So in practice you get:

• normal Next HTML for users,
• lightweight JSON pages for AI agents (ChatGPT/OpenAI, Claude, Perplexity, and others).

Build flow

# 1) Normal Next.js build (HTML output)
next build

# 2) NxPage bot build (JSON output)
nxpage build

After this, your app has both artifacts:

• Next HTML output in .next/*
• NxPage JSON output in .next/nxpage-pages/*

Install

npm i nxpage

Exports

• createNxPageServer(options?)
• generateNxPageManifest(options?)

createNxPageServer

Create a custom server that:

• detects bot/agent traffic,
• serves prebuilt NxPage JSON manifest for matching routes,
• falls back to normal Next request handling for other cases.

Options

• port?: number (default 3000)
• manifestPath?: string (default .next/nxpage-pages/server/app)
• isBot?: (req) => boolean
• includeRoutePatterns?: (string | RegExp)[]
• blockRoutePatterns?: (string | RegExp)[]

Route pattern behavior

• If includeRoutePatterns is provided, only matching routes are eligible.
• blockRoutePatterns always excludes matched routes.
• Final rule: route must pass include filter (if any) and not match block filter.

Example

import { createNxPageServer } from "nxpage";

createNxPageServer({
  port: 3000,
  includeRoutePatterns: ["/docs/**", "/blog/**"],
  blockRoutePatterns: ["/docs/internal/**"],
});

End-to-end usage

1) Build Next.js app

next build

2) Generate NxPage route JSON

import { generateNxPageManifest } from "nxpage";

await generateNxPageManifest({
  distDir: ".next",
  includeRoutePatterns: ["/docs/**", "/blog/**"],
  blockRoutePatterns: ["/docs/internal/**"],
});

3) Start NxPage server

import { createNxPageServer } from "nxpage";

createNxPageServer({
  port: Number(process.env.PORT ?? 3000),
  includeRoutePatterns: ["/docs/**", "/blog/**"],
  blockRoutePatterns: ["/docs/internal/**"],
});

4) Result

• AI agents receive NxPage JSON for allowed routes.
• Blocked or non-included routes fall back to normal Next.js handling.
• Human users continue to receive standard HTML pages.

generateNxPageManifest

Scans Next build output HTML and generates JSON manifest files consumed by the server.

Options

• distDir?: string (default .next)
• manifestPath?: string
• includeRoutePatterns?: (string | RegExp)[]
• blockRoutePatterns?: (string | RegExp)[]

Example

import { generateNxPageManifest } from "nxpage";

await generateNxPageManifest({
  distDir: ".next",
  includeRoutePatterns: ["/docs/**"],
  blockRoutePatterns: ["/docs/internal/**"],
});

CLI

The package includes a CLI:

nxpage build

This runs manifest generation with default options.

Local Development (Monorepo)

cd newupdate/packages/nxpage
npm install
npm run build