Next.js SDK

The @entro314labs/entro-nextjs package provides seamless integration with Next.js 13+ App Router, including Server Components, Client Components, and Middleware support.

Installation

pnpm add @entro314labs/entro-nextjs

npm install @entro314labs/entro-nextjs

yarn add @entro314labs/entro-nextjs

bun add @entro314labs/entro-nextjs

Quick Start

Add Provider

Wrap your app with EntrolyticsProvider:

app/layout.tsx

import { EntrolyticsProvider } from '@entro314labs/entro-nextjs'

export default function RootLayout({ children }) {
  return (
    <html lang="en">
      <body>
        <EntrolyticsProvider
          websiteId={process.env.NEXT_PUBLIC_ENTROLYTICS_WEBSITE_ID!}
          host={process.env.NEXT_PUBLIC_ENTROLYTICS_HOST}
          autoTrack={true}
        >
          {children}
        </EntrolyticsProvider>
      </body>
    </html>
  )
}

Add Environment Variables

Create a .env.local file:

.env.local

NEXT_PUBLIC_ENTROLYTICS_WEBSITE_ID=your-website-id
NEXT_PUBLIC_ENTROLYTICS_HOST=https://cloud.entrolytics.click

Track Events

Use the useEntrolytics hook in client components:

app/components/SignupButton.tsx

'use client'

import { useEntrolytics } from '@entro314labs/entro-nextjs'

export function SignupButton() {
  const { track } = useEntrolytics()

  return (
    <button
      onClick={async () => {
        await track('signup', { plan: 'pro' })
      }}
    >
      Sign Up
    </button>
  )
}

Configuration

EntrolyticsConfig

interface EntrolyticsConfig {
  /** Website ID (required - or use linkId/pixelId) */
  websiteId?: string;
  /** Link ID for link tracking */
  linkId?: string;
  /** Pixel ID for conversion tracking */
  pixelId?: string;
  /** Custom analytics host URL */
  host?: string;
  /** Auto-track page views (default: true) */
  autoTrack?: boolean;
  /** Tag for A/B testing */
  tag?: string;
  /** Restrict to specific domains */
  domains?: string[];
  /** Strip query params from URLs */
  excludeSearch?: boolean;
  /** Strip hash fragments from URLs */
  excludeHash?: boolean;
  /** Honor Do Not Track */
  respectDoNotTrack?: boolean;
  /** Disable on localhost */
  ignoreLocalhost?: boolean;
  /** Transform/cancel events before sending */
  beforeSend?: BeforeSendCallback;
  /** Auto-track outbound links */
  trackOutboundLinks?: boolean;
  /** Proxy configuration */
  proxy?: ProxyConfig | false;
  /** Enable debug logging */
  debug?: boolean;
}

Tracking Methods

useEntrolytics Hook

'use client';

import { useEntrolytics } from '@entro314labs/entro-nextjs';

function MyComponent() {
  const {
    track,
    trackView,
    identify,
    trackRevenue,
    trackOutboundLink,
    setTag,
    generateEnhancedIdentity,
    isReady,
    isEnabled,
    config,
  } = useEntrolytics();

  // Track event
  await track('button-click');
  await track('button-click', { color: 'blue' });

  // Track page view
  await trackView('/custom-page');

  // Identify user
  await identify('user-123');
  await identify('user-123', { email: 'user@example.com' });

  // Track revenue
  await trackRevenue('purchase', 99.99, 'USD');

  // Track outbound link
  await trackOutboundLink('https://example.com');

  // Set A/B test tag
  setTag('variant-b');

  // Generate enhanced identity
  const identity = generateEnhancedIdentity({
    userId: '123',
    plan: 'pro',
  });
}

Components

TrackEvent Component

Track events declaratively:

import { TrackEvent } from '@entro314labs/entro-nextjs';

<TrackEvent
  name="cta-click"
  data={{ location: 'hero' }}
  trigger="click" // or 'visible' or 'submit'
  once={true}
>
  <button>Click Me</button>
</TrackEvent>

OutboundLink Component

Track external link clicks:

import { OutboundLink } from '@entro314labs/entro-nextjs';

<OutboundLink
  href="https://external-site.com"
  data={{ source: 'sidebar' }}
>
  External Link
</OutboundLink>

Script Component

Alternative to Provider (traditional script-based tracking):

app/layout.tsx

import { Script } from '@entro314labs/entro-nextjs';

export default function RootLayout({ children }) {
  return (
    <html>
      <head>
        <Script
          websiteId={process.env.NEXT_PUBLIC_ENTROLYTICS_WEBSITE_ID!}
          host={process.env.NEXT_PUBLIC_ENTROLYTICS_HOST}
        />
      </head>
      <body>{children}</body>
    </html>
  );
}

Server-Side Tracking

API Routes

app/api/action/route.ts

import { trackServerEvent } from '@entro314labs/entro-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/action' },
      request,
    }
  );

  return Response.json({ success: true });
}

Server Actions

app/actions.ts

'use server';

import { trackServerEvent } from '@entro314labs/entro-nextjs/server';

export async function createUser(formData: FormData) {
  // Create user logic...

  await trackServerEvent(
    {
      host: process.env.ENTROLYTICS_HOST!,
      websiteId: process.env.ENTROLYTICS_WEBSITE_ID!,
    },
    {
      event: 'user-created',
      data: { email: formData.get('email') },
    }
  );
}

Advanced Features

Link & Pixel Tracking

Track link clicks and conversion pixels:

<EntrolyticsProvider
  linkId="link-uuid"
  // OR pixelId="pixel-uuid"
  host={process.env.NEXT_PUBLIC_ENTROLYTICS_HOST}
>
  {children}
</EntrolyticsProvider>

Proxy Configuration

Bypass ad-blockers with proxy mode:

<EntrolyticsProvider
  websiteId="..."
  proxy={{
    enabled: true,
    scriptPath: '/analytics.js',
    collectPath: '/api/collect',
    mode: 'cloak',
  }}
>
  {children}
</EntrolyticsProvider>

Before Send Hook

Transform or cancel events:

<EntrolyticsProvider
  websiteId="..."
  beforeSend={(type, payload) => {
    // Filter out admin users
    if (payload.url?.includes('/admin')) {
      return null; // Cancel tracking
    }

    // Add custom data
    return {
      ...payload,
      data: {
        ...payload.data,
        version: '2.0',
      },
    };
  }}
>
  {children}
</EntrolyticsProvider>

Enhanced Identity

Capture detailed browser metadata:

'use client';

import { useEntrolytics } from '@entro314labs/entro-nextjs';

function ProfilePage() {
  const { identify, generateEnhancedIdentity } = useEntrolytics();

  useEffect(() => {
    const enhanced = generateEnhancedIdentity({
      userId: user.id,
      plan: user.plan,
    });

    identify(user.id, enhanced);
  }, [user]);
}

Hooks

usePageView

Track page views automatically:

'use client';

import { usePageView } from '@entro314labs/entro-nextjs';

function PageComponent() {
  usePageView({
    url: '/custom-url',
    enabled: true,
    deps: [searchParams],
  });
}

Examples

E-commerce Tracking

'use client';

import { useEntrolytics } from '@entro314labs/entro-nextjs';

export function ProductPage({ product }) {
  const { track, trackRevenue } = useEntrolytics();

  useEffect(() => {
    track('product-view', {
      productId: product.id,
      category: product.category,
    });
  }, [product]);

  async function handlePurchase() {
    await trackRevenue('purchase', product.price, 'USD');
  }

  return (
    <button onClick={handlePurchase}>
      Buy ${product.price}
    </button>
  );
}

A/B Testing

'use client';

import { useEntrolytics } from '@entro314labs/entro-nextjs';

export function Hero() {
  const { setTag } = useEntrolytics();
  const variant = Math.random() > 0.5 ? 'a' : 'b';

  useEffect(() => {
    setTag(`hero-${variant}`);
  }, [variant]);

  return variant === 'a' ? <HeroA /> : <HeroB />;
}

TypeScript Support

Full TypeScript support with exported types:

import type {
  EntrolyticsConfig,
  EventData,
  EventPayload,
  TrackedProperties,
  BeforeSendCallback,
} from '@entro314labs/entro-nextjs';

Features

✅ Next.js 13+ App Router support
✅ Server Components & Client Components
✅ Server-side tracking (API routes, Server Actions)
✅ Automatic page view tracking
✅ Declarative event components
✅ Link and pixel tracking support
✅ Proxy mode for ad-blocker bypass
✅ TypeScript-first with full type safety
✅ Zero config required

Support

GitHub Issues
Email: hey@entrolytics.click

Next.js SDK

Table of Contents