Advanced analytics package for Next.js applications with bot detection and comprehensive tracking
npm install @jillen/analyticsAdvanced analytics package for Next.js applications with intelligent bot detection, comprehensive visitor tracking, and Web Vitals performance monitoring.
- 🤖 Smart Bot Detection: Advanced bot filtering using comprehensive bot registry and multiple detection methods
- 📊 Comprehensive Tracking: Detailed visitor analytics with geolocation and device info
- ⚡ Web Vitals Monitoring: Automatic collection of Core Web Vitals (CLS, FID, LCP, FCP, TTFB, INP)
- 🚀 Next.js Optimized: Built specifically for Next.js 13+ with App Router support
- 📱 Mobile-First: Responsive tracking with mobile device detection
- 🔒 Privacy-Focused: GDPR compliant with DNT (Do Not Track) support
- 🏎️ Performance-First: Lightweight, non-blocking analytics with fire-and-forget tracking
- 🌍 Zero-Config: No environment variables required - works out of the box
- 🔧 Next.js 15+ Compatible: Proper client/server separation prevents build errors
Next.js project with middleware and app router support
This package uses separate entry points for client and server code to ensure compatibility with Next.js 15+:
- Client components: Import from @jillen/analytics
- Server utilities: Import from @jillen/analytics/server
This prevents build errors like "usePathname is not exported from 'next/navigation'" in Next.js 15.3.1+.
``bash`
npm install @jillen/analyticsor
bun add @jillen/analytics
Add the setupAnalyticsMiddleware utility to your middleware
`typescript
// middleware.ts
import { NextResponse } from 'next/server';
import type { NextRequest } from 'next/server';
import { setupAnalyticsMiddleware } from '@jillen/analytics/server';
export function middleware(request: NextRequest) {
// Setup analytics (pathname header + bot tracking)
const { headers } = setupAnalyticsMiddleware(request);
return NextResponse.next({
request: { headers },
});
}
export const config = {
matcher: [
'/((?!api|_next/static|_next/image|favicon.ico).*)',
],
};
`
Create a client component to handle analytics:
`typescript
// components/analytics-provider.tsx
"use client";
import { VisitorTracker } from '@jillen/analytics';
import { useUser } from "@clerk/nextjs"; // or your auth system
export function AnalyticsProvider() {
const { isLoaded, user } = useUser();
// Wait for auth to load before initializing analytics
if (!isLoaded) {
return null;
}
// Use username, fallback to user ID, or null for anonymous
const username = user?.username ?? user?.id ?? null;
return
}
`
Alternative auth systems:
`typescript
// For NextAuth.js
import { useSession } from "next-auth/react";
export function AnalyticsProvider() {
const { status, data: session } = useSession();
if (status === "loading") return null;
const username = session?.user?.email ?? session?.user?.id ?? null;
return
}
// For Supabase Auth
import { useUser } from "@supabase/auth-helpers-react";
export function AnalyticsProvider() {
const user = useUser();
const username = user?.email ?? user?.id ?? null;
return
}
`
Add analytics tracking to your layout:
`typescript
// app/layout.tsx
import { AnalyticsProvider } from "@/components/analytics-provider";
export default function RootLayout({
children,
}: {
children: React.ReactNode;
}) {
return (
$3
Deploy to production. Analytics automatically:
- ✅ Detects bots and tracks them separately
- ✅ Collects Web Vitals performance metrics
- ✅ Tracks user sessions and page views
- ✅ Works in production only (disabled in development)
What Gets Tracked
$3
- Page views and session tracking
- User identification (if username provided)
- Device info (screen resolution, viewport, mobile detection)
- Geographic data (via Vercel headers)
- Referrer information$3
- Core Web Vitals: CLS, LCP, FID/INP
- Loading Metrics: FCP, TTFB
- Resource Performance: Automatic classification and timing
- User Experience: Real user monitoring data$3
- Comprehensive bot registry (search engines, social crawlers, monitoring tools)
- Separate tracking pipeline for bot visits
- Protection against analytics pollutionAPI Reference
$3
####
VisitorTracker
`typescript
interface VisitorTrackerProps {
username?: string | null; // Optional user identifier
}
`$3
####
setupAnalyticsMiddleware(request: NextRequest)
Sets up analytics middleware for automatic bot detection and header processing.Import from server entry point:
`typescript
import { setupAnalyticsMiddleware } from '@jillen/analytics/server';
`$3
Export types for custom implementations:
-
BaseEventData
- HumanEventData
- PerformanceEventData
- BotEventData
- ServerEnrichedFieldsMigration from v4.0.14 and Earlier
If upgrading from versions before 4.0.15, update your server imports:
`diff
// middleware.ts
- import { setupAnalyticsMiddleware } from '@jillen/analytics';
+ import { setupAnalyticsMiddleware } from '@jillen/analytics/server';
`Client component imports remain unchanged:
`typescript
// components/analytics-provider.tsx
import { VisitorTracker } from '@jillen/analytics'; // ✅ No change needed
`Troubleshooting
$3
If you see errors like:
- "usePathname is not exported from 'next/navigation'"
- "useRef is not exported from 'react'"
Solution: Ensure you're using the correct import paths:
- Server code:
import { setupAnalyticsMiddleware } from '@jillen/analytics/server'
- Client components: import { VisitorTracker } from '@jillen/analytics'`