Next.js Setup

This guide covers the complete setup of Adopture in Next.js applications, supporting both App Router and Pages Router architectures.

Prerequisites

Before starting, make sure you have:

Installed the Adopture Next.js SDK
Set up your environment variables
A Next.js project (13.0.0 or higher)

App Router Setup

If you're using the modern App Router (app/ directory), follow these steps:

1. Add Provider to Root Layout

Wrap your entire application with the AdoptureProvider:

app/layout.tsx

import { AdoptureProvider } from '@adopture/next';

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

2. Optional Provider Configuration

You can customize the provider with additional options:

app/layout.tsx

import { AdoptureProvider } from '@adopture/next';

const adoptureConfig = {
  debug: process.env.NODE_ENV === 'development',
  batchSize: 50,
  flushInterval: 5000,
};

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

Pages Router Setup

If you're using the traditional Pages Router (pages/ directory), follow these steps:

1. Add Provider to _app.tsx

Wrap your application with the AdopturePagesProvider:

pages/_app.tsx

import { AdopturePagesProvider } from '@adopture/next';
import type { AppProps } from 'next/app';

export default function App({ Component, pageProps }: AppProps) {
  return (
    <AdopturePagesProvider>
      <Component {...pageProps} />
    </AdopturePagesProvider>
  );
}

2. Optional Provider Configuration

You can customize the provider with additional options:

pages/_app.tsx

import { AdopturePagesProvider } from '@adopture/next';
import type { AppProps } from 'next/app';

const adoptureConfig = {
  debug: process.env.NODE_ENV === 'development',
  batchSize: 50,
  flushInterval: 5000,
};

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

Configuration Options

The provider accepts several configuration options:

Option	Type	Default	Description
`debug`	`boolean`	`false`	Enable debug logging
`batchSize`	`number`	`50`	Number of events to batch
`flushInterval`	`number`	`5000`	Interval (ms) to flush events
`fallback`	`ReactNode`	`null`	Fallback component for errors
`loadingComponent`	`ReactNode`	`null`	Loading component while initializing

Advanced Configuration Example

import { AdoptureProvider } from '@adopture/next';

const config = {
  debug: process.env.NODE_ENV === 'development',
  batchSize: 100,
  flushInterval: 3000,
};

const LoadingFallback = () => (
  <div>Initializing analytics...</div>
);

const ErrorFallback = () => (
  <div>Analytics temporarily unavailable</div>
);

export default function RootLayout({
  children,
}: {
  children: React.ReactNode;
}) {
  return (
    <html lang="en">
      <body>
        <AdoptureProvider
          config={config}
          loadingComponent={<LoadingFallback />}
          fallback={<ErrorFallback />}
        >
          {children}
        </AdoptureProvider>
      </body>
    </html>
  );
}

Verification

After setting up the provider, verify that everything is working:

1. Check for Errors

Open your browser's developer console and look for any Adopture-related errors or warnings.

2. Test Basic Tracking

Create a simple test component:

components/TestButton.tsx

'use client';

import { useTrack } from '@adopture/next';

export function TestButton() {
  const { track } = useTrack();

  const handleClick = () => {
    track('test-button-click', {
      timestamp: new Date().toISOString(),
      location: 'test-page',
    });
    console.log('Event tracked!');
  };

  return (
    <button onClick={handleClick}>
      Test Tracking
    </button>
  );
}

3. Check Network Activity

In your browser's Network tab, you should see requests to Adopture's API when events are tracked.

Troubleshooting

Provider not found errors

Make sure the provider is correctly imported and wraps your entire application:

// ✅ Correct - Provider wraps everything
<AdoptureProvider>
  <Component {...pageProps} />
</AdoptureProvider>

// ❌ Incorrect - Provider inside components
<Component {...pageProps}>
  <AdoptureProvider>
    <SomeComponent />
  </AdoptureProvider>
</Component>

Events not being tracked

Ensure your API key is correctly set in .env.local
Check that your components use the 'use client' directive
Verify the provider is properly configured
Check browser console for JavaScript errors

TypeScript errors

If you see TypeScript errors, make sure you have the latest type definitions:

npm install --save-dev @types/react @types/react-dom

Next Steps

Now that your provider is set up, you can start tracking events:

Migration from Other SDKs

If you're migrating from another analytics platform:

Replace your existing provider with AdoptureProvider
Update your tracking calls to use Adopture hooks
Remove old analytics dependencies
Test thoroughly before deploying

For specific migration guides, contact our support team.

Next.js Setup

On this page