@faircite/nextjs-middleware

Official Next.js middleware for FairCite bot detection and analytics. Provides intelligent request batching to efficiently track and analyze bot traffic at scale.

Features

• 🚀 High Performance - Non-blocking middleware with intelligent batching
• 📦 Smart Batching - Automatically batches requests for efficient processing
• 🔄 Automatic Retry - Built-in retry logic with exponential backoff
• 🎯 Zero Config - Works out of the box with sensible defaults
• 📊 Real-time Analytics - Track bot traffic patterns in real-time
• 🔒 Secure - API key authentication with server-side processing
• 🌐 Edge Compatible - Works with Vercel Edge Runtime and Node.js

Installation

npm install @faircite/nextjs-middleware
# or
yarn add @faircite/nextjs-middleware
# or
pnpm add @faircite/nextjs-middleware

Quick Start

1. Create middleware file

Create middleware.ts in your project root:

import { fcMiddleware } from '@faircite/nextjs-middleware';

export const middleware = fcMiddleware({
  siteId: 'pub_xxxxx',  // Your FairCite site ID
  apiKey: 'fc_xxxxx'    // Your FairCite API key
});

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

2. Set environment variables (recommended)

Instead of hardcoding credentials, use environment variables:

# .env.local
FC_SITE_ID=pub_xxxxx
FC_API_KEY=fc_xxxxx

Then simplify your middleware:

import { fcMiddleware } from '@faircite/nextjs-middleware';

export const middleware = fcMiddleware();

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

Configuration Options

fcMiddleware({
  // Required (if not using env vars)
  siteId?: string;        // Your FairCite site ID
  apiKey?: string;        // Your FairCite API key
  
  // Optional
  edgeUrl?: string;       // Custom edge worker URL (default: https://edge.faircite.com/v1/analyze)
  enabled?: boolean;      // Enable/disable middleware (default: true)
  batchSize?: number;     // Batch size threshold (default: 10)
  flushInterval?: number; // Flush interval in ms (default: 1000)
  debug?: boolean;        // Enable debug logging (default: false)
})

Environment Variables

All configuration options can be set via environment variables:

| Variable | Description | Default | |----------|-------------|---------| | FC_SITE_ID | Your FairCite site ID | - | | FC_API_KEY | Your FairCite API key | - | | FC_EDGE_URL | Custom edge worker URL | https://edge.faircite.com/v1/analyze | | FC_ENABLED | Enable/disable middleware | true | | FC_BATCH_SIZE | Number of requests to batch | 10 | | FC_FLUSH_INTERVAL | Batch flush interval (ms) | 1000 | | FC_DEBUG | Enable debug logging | false |

Performance

• Minimal Overhead: < 1ms added to request processing
• Non-blocking: Async processing doesn't delay responses
• Memory Efficient: Automatic cleanup and size limits
• Network Optimized: Batching reduces API calls by 10-100x

Compatibility

• Next.js 13.0+ (App Router)
• Next.js 12.2+ (Middleware support)
• Node.js 16.8+
• Vercel Edge Runtime
• Self-hosted deployments

TypeScript

Full TypeScript support with exported types:

import type { FairCiteConfig, Detection } from '@faircite/nextjs-middleware';

Security

• API keys are never exposed to the client
• All processing happens server-side
• Automatic sanitization of collected data
• No personally identifiable information (PII) collected

Support

• 📧 Email Support

License

MIT © FairCite

Built with ❤️ by the FairCite team