botversion
v0.2.0
Published
Serve AI-optimized versions of your Next.js pages. Detect AI browsers automatically or build AI-native sites.
Maintainers
eliotherbstReadme
botversion
Serve AI-optimized versions of your Next.js pages. Detect AI browsers automatically, or build AI-native sites where humans opt-in to the rich experience.
Install
npm install botversionQuick Start
1. Add the middleware
// middleware.ts
import { withBotVersion } from 'botversion/middleware';
export default withBotVersion();2. Add the provider to your layout
// app/layout.tsx
import { isAIBot } from 'botversion/server';
import { BotVersionProvider } from 'botversion/react';
export default async function RootLayout({ children }: { children: React.ReactNode }) {
return (
<html>
<body>
<BotVersionProvider isAIBot={await isAIBot()}>
{children}
</BotVersionProvider>
</body>
</html>
);
}3. Use in your pages
// app/page.tsx
import { ForAI, ForHumans } from 'botversion/react';
export default function Page() {
return (
<main>
<h1>My Product</h1>
<ForHumans>
<InteractiveCarousel />
<AnimatedPricing />
<VideoReviews />
</ForHumans>
<ForAI>
<p>Price: $49.99</p>
<p>A detailed, structured description of the product...</p>
<ul>
<li>Feature 1</li>
<li>Feature 2</li>
</ul>
</ForAI>
</main>
);
}Two Modes
Auto-Detect (default)
Detects AI crawlers (GPTBot, ClaudeBot, PerplexityBot, and 30+ others) via user-agent. Human visitors get the normal site. AI bots get your optimized version.
export default withBotVersion(); // default: auto-detectAI-Native
Your site is AI-first by default. Human visitors opt-in to the rich version via a query parameter (e.g. ?human=true). The preference is persisted in a cookie.
export default withBotVersion({
mode: 'ai-native',
humanParam: 'human', // default — customize if you want ?view=rich, etc.
});Client-Side Mode Switching
In Next.js App Router, layouts persist across client-side navigations. Use switchToHuman and switchToAI for instant mode switching without a full page reload:
'use client';
import { switchToHuman, switchToAI } from 'botversion/react';
export function ModeToggle() {
return (
<>
<button onClick={() => switchToHuman()}>Humans Click Here</button>
<button onClick={() => switchToAI()}>Switch to AI View</button>
</>
);
}These functions update the cookie and the BotVersionProvider context in one step. The ?human=true query param still works for direct links and initial page loads.
API Reference
botversion/middleware
withBotVersion(config?) — Creates a Next.js middleware function.
withBotVersion({
mode: 'auto-detect' | 'ai-native', // default: 'auto-detect'
humanParam: string, // query param for ai-native mode, default: 'human'
humanCookie: string, // cookie name for persistence, default: 'botversion-human'
additionalBots: BotInfo[], // extend the built-in bot list
headerName: string, // custom header name, default: 'x-botversion'
})detectAndAnnotate(request, config?) — Lower-level function for composing with existing middleware.
import { detectAndAnnotate } from 'botversion/middleware';
export function middleware(request: NextRequest) {
const { headers, detection, isHuman } = detectAndAnnotate(request);
// Your own logic...
if (!isHuman) {
console.log(`AI bot: ${detection.bot?.name}`);
}
return NextResponse.next({ request: { headers } });
}botversion/server
For use in Server Components and Route Handlers.
import { isAIBot, getAIBotInfo } from 'botversion/server';
// Simple boolean
const bot = await isAIBot();
// Full detection info
const info = await getAIBotInfo();
// { isAIBot: true, bot: { name: 'GPTBot', operator: 'OpenAI', ... }, matchedPattern: 'GPTBot' }botversion/react
Client-side components and hooks. Requires BotVersionProvider in your layout.
import { ForAI, ForHumans, useIsAIBot, BotVersionProvider, switchToHuman, switchToAI } from 'botversion/react';
// Conditional rendering
<ForAI>Only visible to AI bots</ForAI>
<ForHumans>Only visible to humans</ForHumans>
// With fallbacks
<ForAI fallback={<p>Human version</p>}>AI version</ForAI>
// Hook
const isBot = useIsAIBot();
// Client-side mode switching (ai-native)
switchToHuman() // set human cookie + update context
switchToAI() // clear human cookie + update contextbotversion/detect
Pure detection engine. Zero dependencies, works anywhere (Edge, Node, browser, Deno).
import { detectAIBot, isAIBot, createDetector, AI_BOTS } from 'botversion/detect';
// Simple check
isAIBot('Mozilla/5.0 (compatible; GPTBot/1.0)'); // true
// Detailed info
detectAIBot('Mozilla/5.0 (compatible; ClaudeBot/1.0)');
// { isAIBot: true, bot: { name: 'ClaudeBot', operator: 'Anthropic', category: 'ai-crawler' }, matchedPattern: 'ClaudeBot' }
// Custom detector with extra bots
const detect = createDetector([
{ name: 'MyInternalBot', operator: 'MyCompany', category: 'ai-crawler' }
]);Detected Bots
30+ AI bots detected out of the box including:
| Bot | Operator | |-----|----------| | GPTBot, ChatGPT-User, OAI-SearchBot | OpenAI | | ClaudeBot, Claude-SearchBot | Anthropic | | PerplexityBot | Perplexity | | Google-Extended, Gemini-Deep-Research | Google | | Bytespider | ByteDance | | CCBot | Common Crawl | | DeepSeekBot | DeepSeek | | Meta-ExternalAgent | Meta | | Amazonbot, NovaAct | Amazon | | And many more... | |
License
MIT