Configure Journium Next.js SDK with Provider component, automatic route tracking, and underlying JavaScript SDK options.

Next.js Configuration

The Journium Next.js SDK extends the React SDK with Next.js-specific optimizations including automatic route change tracking for both App Router and Pages Router.

Next.js-Specific Setup

Provider Configuration

app/layout.tsx

import { NextJourniumProvider } from '@journium/nextjs';

const journiumConfig = {
  publishableKey: process.env.NEXT_PUBLIC_JOURNIUM_PUBLISHABLE_KEY!,
  options: {
    debug: process.env.NODE_ENV === 'development',
    autoTrackPageviews: true, // Auto-tracks route changes
    autocapture: true
  }
};

export default function RootLayout({
  children,
}: {
  children: React.ReactNode;
}) {
  return (
    <html lang="en">
      <body>
        <NextJourniumProvider config={journiumConfig}>
          {children}
        </NextJourniumProvider>
      </body>
    </html>
  );
}

pages/_app.tsx

import type { AppProps } from 'next/app';
import { NextJourniumProvider } from '@journium/nextjs';

const journiumConfig = {
  publishableKey: process.env.NEXT_PUBLIC_JOURNIUM_PUBLISHABLE_KEY!,
  options: {
    debug: process.env.NODE_ENV === 'development',
    autoTrackPageviews: true, // Auto-tracks route changes
    autocapture: true
  }
};

export default function App({ Component, pageProps }: AppProps) {
  return (
    <NextJourniumProvider config={journiumConfig}>
      <Component {...pageProps} />
    </NextJourniumProvider>
  );
}

Configuration Options

The config prop accepts a JourniumConfig object with the same options as the JavaScript SDK.

For detailed information about all available configuration options, see the JavaScript SDK Configuration Guide.

Next.js-specific considerations:

autoTrackPageviews - Set to true to automatically track Next.js route changes (recommended)
Environment variables should use NEXT_PUBLIC_ prefix for client-side access
Configuration is SSR-compatible

Next.js Components

`<NextJourniumProvider>`

Provider component with Next.js optimizations and automatic route tracking.

Props:

Prop	Type	Required	Description
`config`	`JourniumConfig`	Yes	Configuration object
`config.publishableKey`	`string`	Yes	Your publishable key
`config.apiHost`	`string`	No	Custom API endpoint
`config.options`	`JourniumLocalOptions`	No	Configuration options
`children`	`ReactNode`	Yes	React children to wrap

Next.js Features:

✅ Automatic route change detection (App Router and Pages Router)
✅ SSR-compatible initialization
✅ Works with next/navigation and next/router
✅ Optimized for serverless deployments

Automatic Route Tracking

The Next.js provider automatically tracks route changes in both App Router and Pages Router:

// Automatically tracked:
router.push('/products/123');
router.replace('/checkout');
<Link href="/about">About</Link>

Disable automatic tracking:

<NextJourniumProvider 
  config={{
    publishableKey: 'pk_...',
    options: {
      autoTrackPageviews: false  // Disable automatic tracking
    }
  }}
>

Then manually track pageviews:

'use client';

import { useTrackPageview } from '@journium/nextjs';
import { usePathname } from 'next/navigation';
import { useEffect } from 'react';

export function PageTracker() {
  const pathname = usePathname();
  const trackPageview = useTrackPageview();
  
  useEffect(() => {
    trackPageview({ pathname });
  }, [pathname, trackPageview]);
  
  return null;
}

React Hooks

The Next.js SDK includes all React hooks. See the React Hooks documentation for details:

useTrackEvent() - Track custom events
useIdentify() - Identify users
useReset() - Reset user identity
useTrackPageview() - Manual pageview tracking
useAutoTrackPageview() - Automatic pageview tracking
useAutocapture() - Control autocapture
useJournium() - Access analytics instance

Server-Side Rendering (SSR)

The SDK is SSR-compatible and will not cause hydration issues:

// ✅ Safe in Next.js
export default function Layout({ children }: { children: React.ReactNode }) {
  return (
    <html>
      <body>
        <NextJourniumProvider config={{ publishableKey: 'pk_...' }}>
          {children}
        </NextJourniumProvider>
      </body>
    </html>
  );
}

The analytics instance is only initialized on the client side.

Environment Variables

App Router / Pages Router

.env.local

NEXT_PUBLIC_JOURNIUM_PUBLISHABLE_KEY=pk_your_key_here

const config = {
  publishableKey: process.env.NEXT_PUBLIC_JOURNIUM_PUBLISHABLE_KEY!
};

Different Keys per Environment

.env.local

# Development
NEXT_PUBLIC_JOURNIUM_PUBLISHABLE_KEY=pk_test_...

# .env.production
NEXT_PUBLIC_JOURNIUM_PUBLISHABLE_KEY=pk_live_...

TypeScript Support

The Next.js SDK is fully typed with the same types as the JavaScript SDK.

For complete type definitions, see the JavaScript SDK TypeScript Types documentation.

import { 
  type JourniumConfig, 
  type JourniumLocalOptions,
  type AutocaptureOptions 
} from '@journium/nextjs';

API Reference

For detailed API method reference, see the JavaScript SDK API Methods.

The Next.js SDK provides the same methods through React hooks:

Hook	Underlying Method	Documentation
`useTrackEvent()`	`analytics.track()`	API Ref
`useIdentify()`	`analytics.identify()`	API Ref
`useReset()`	`analytics.reset()`	API Ref

Deployment Considerations

Vercel

Works out of the box. Environment variables are automatically available with NEXT_PUBLIC_ prefix.

Self-Hosted

Ensure environment variables are configured:

.env.production

NEXT_PUBLIC_JOURNIUM_PUBLISHABLE_KEY=pk_live_...

Then build normally:

npm run build

Next Steps

React Hooks

Learn about all available hooks for Next.js

Configuration Options

See all configuration options in detail

API Methods

Complete API method reference

Next.js Configuration

React Hooks

Configuration Options

API Methods

On this page