[![npm](https://img.shields.io/npm/v/@entrolytics/nextjs-sdk.svg?logo=npm)](https://www.npmjs.com/package/@entrolytics/nextjs-sdk) [![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](https://opensource.org/licenses/MIT) [![TypeScript](https://img.shields.io/badge/TypeScript-5.0-3178C6.svg?logo=typescript&logoColor=white)](https://www.typescriptlang.org/) [![Next.js](https://img.shields.io/badge/Next.js-14+-000000.svg?logo=next.js)](https://nextjs.org/)

--- ## Overview **@entrolytics/nextjs-sdk** is the official Next.js SDK for Entrolytics - first-party growth analytics for the edge. Built specifically for Next.js 13+ App Router with SSR safety and zero-config setup. **Why use this SDK?** - App Router native with proper server/client separation - Zero hydration mismatches - SSR safe from the ground up - Server-side tracking from API routes and Server Actions - Proxy mode for ad-blocker bypass ## Key Features

### Analytics - Automatic page view tracking - Custom event and revenue tracking - User identification - A/B testing with tag segmentation

### Developer Experience - `` zero-config component - `useEntrolytics` hook for all functionality - Server Actions and API route support - Next.js config plugin for proxy mode

## Quick Start

1. Install
npm i @entrolytics/nextjs-sdk 2. Add Component
<Analytics /> in layout 3. Configure
Set Website ID in .env.local 4. Track
View analytics in dashboard

## Installation ```bash pnpm add @entrolytics/nextjs-sdk ``` ```tsx // app/layout.tsx import { Analytics } from '@entrolytics/nextjs-sdk'; export default function RootLayout({ children }: { children: React.ReactNode }) { return ( {children} ); } ``` That's it! The `` component automatically reads from your `.env.local`: ```bash NEXT_PUBLIC_ENTROLYTICS_WEBSITE_ID=your-website-id NEXT_PUBLIC_ENTROLYTICS_HOST=https://entrolytics.click ``` ### 2. Track Events ```tsx 'use client'; import { useEntrolytics } from '@entrolytics/nextjs'; export function SignupButton() { const { track } = useEntrolytics(); return ; } ``` ## Configuration ### Simple Configuration (Recommended) Use the `` component with props: ```tsx ``` All configuration options are optional - the component reads `websiteId` and `host` from environment variables. ### Advanced Configuration For more control, use `` directly: ```tsx import { EntrolyticsProvider } from '@entrolytics/nextjs'; { // Transform/filter if (isAdmin) return null; return payload; }} > {children} ; ``` The provider sends requests to the canonical collection endpoint, or to the configured proxy path when proxy mode is enabled. ## Hooks ### useEntrolytics ```tsx const { track, // Track events trackView, // Manual page view identify, // User identification trackRevenue, // Revenue tracking trackOutboundLink, // Outbound link tracking setTag, // Change A/B test tag generateEnhancedIdentity, // Browser metadata isReady, // Tracker ready state isEnabled, // Tracking enabled state } = useEntrolytics(); ``` ### usePageView ```tsx // Basic - tracks on mount usePageView(); // Custom URL usePageView({ url: '/virtual-page' }); // With dependencies usePageView({ url: dynamicPath, deps: [dynamicPath] }); // Conditional usePageView({ enabled: isAuthenticated }); ``` ### useEventTracker ```tsx const { trackEvent, createClickHandler } = useEventTracker({ eventName: 'button-click', defaultData: { section: 'header' }, }); // Track with defaults trackEvent(); // Use as click handler ; ``` ## Components ### TrackEvent ```tsx // Track on click // Track on visibility

Pricing

// Track on form submit ``` ### OutboundLink ```tsx GitHub ``` ## Server-Side Tracking ### API Routes / Server Actions ```ts import { trackServerEvent } from '@entrolytics/nextjs/server'; export async function POST(request: Request) { await trackServerEvent( { host: process.env.ENTROLYTICS_HOST!, websiteId: process.env.ENTROLYTICS_WEBSITE_ID!, }, { event: 'api-call', data: { endpoint: '/api/users' }, request, }, ); return Response.json({ success: true }); } ``` ### Proxy Mode ```ts // app/api/collect/[...path]/route.ts import { createProxyHandler } from '@entrolytics/nextjs/server'; export const { GET, POST } = createProxyHandler({ host: process.env.ENTROLYTICS_HOST!, websiteId: process.env.ENTROLYTICS_WEBSITE_ID, mode: 'cloak', }); ``` ### Middleware ```ts // middleware.ts import { withEntrolyticsMiddleware } from '@entrolytics/nextjs/server'; const entrolytics = withEntrolyticsMiddleware({ host: process.env.ENTROLYTICS_HOST!, websiteId: process.env.ENTROLYTICS_WEBSITE_ID!, trackRoutes: ['/api/*'], }); export async function middleware(request: NextRequest) { return entrolytics(request); } ``` ## Next.js Config Plugin ```ts // next.config.ts import { withEntrolytics } from '@entrolytics/nextjs/plugin'; export default withEntrolytics({ websiteId: process.env.NEXT_PUBLIC_ENTROLYTICS_WEBSITE_ID!, host: process.env.NEXT_PUBLIC_ENTROLYTICS_HOST, proxy: { enabled: true, mode: 'cloak', }, })({ reactStrictMode: true, }); ``` ## License MIT © [Entrolytics](https://entrolytics.click)