How to add product analytics to a Next.js app

npm install @amplitude/unified @amplitude/analytics-node

NEXT_PUBLIC_AMPLITUDE_API_KEY=your-project-api-key
AMPLITUDE_API_KEY=your-project-api-key

import * as amplitude from '@amplitude/unified';

let started = false;

function initAmplitude() {
  // Server rendering has no window; Fast Refresh re-runs modules.
  if (typeof window === 'undefined' || started) return;

  const apiKey = process.env.NEXT_PUBLIC_AMPLITUDE_API_KEY;
  if (!apiKey) {
    console.warn('NEXT_PUBLIC_AMPLITUDE_API_KEY is not set; Amplitude is off.');
    return;
  }

  started = true;
  amplitude.initAll(apiKey, {
    analytics: {
      autocapture: {
        elementInteractions: true, // clicks are off unless you name them
      },
    },
  });
}

initAmplitude();

export { amplitude };

'use client';

import type { ReactNode } from 'react';
import '@/lib/amplitude';

export function AnalyticsProvider({ children }: { children: ReactNode }) {
  return <>{children}</>;
}

import type { ReactNode } from 'react';
import { AnalyticsProvider } from '@/components/AnalyticsProvider';

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

'use client';

import { useEffect } from 'react';
import { amplitude } from '@/lib/amplitude';
import { useAuth } from '@/lib/auth'; // your auth hook

export function IdentifyUser() {
  const { user } = useAuth();

  useEffect(() => {
    // Signed out or still loading: keep the same device ID.
    // Call amplitude.reset() only from your sign-out handler.
    if (!user) return;

    // Amplitude drops IDs shorter than 5 characters. Use the same
    // string the server sends as user_id in step 6.
    amplitude.setUserId(`user-${user.id}`);

    const identify = new amplitude.Identify();
    identify.set('plan', user.plan);
    amplitude.identify(identify);
  }, [user?.id, user?.plan]);

  return null;
}

'use client';

import { amplitude } from '@/lib/amplitude';

export function NewProjectButton({ template }: { template: string }) {
  function handleClick() {
    // ... your create-project logic
    amplitude.track('Project Created', { template });
  }

  return <button onClick={handleClick}>Create project</button>;
}

import { init, track, flush } from '@amplitude/analytics-node';

let started = false;

function ensureInit() {
  if (started) return;
  init(process.env.AMPLITUDE_API_KEY!);
  started = true;
}

export async function trackServerEvent(
  eventType: string,
  userId: string,
  eventProperties?: Record<string, unknown>,
) {
  ensureInit();
  track(eventType, eventProperties, { user_id: userId });
  // Serverless functions can freeze as soon as the action returns.
  await flush().promise;
}

'use server';

import { trackServerEvent } from '@/lib/amplitude-server';
import { getCurrentUser } from '@/lib/auth'; // your server-side auth helper

export async function upgradePlan(plan: string) {
  const user = await getCurrentUser();

  // ... your billing logic

  await trackServerEvent('Plan Upgraded', `user-${user.id}`, {
    plan,
    source: 'billing_page',
  });
}

// -- .env.local --
NEXT_PUBLIC_AMPLITUDE_API_KEY=your-project-api-key
AMPLITUDE_API_KEY=your-project-api-key

// -- lib/amplitude.ts --
import * as amplitude from '@amplitude/unified';

let started = false;

function initAmplitude() {
  if (typeof window === 'undefined' || started) return;

  const apiKey = process.env.NEXT_PUBLIC_AMPLITUDE_API_KEY;
  if (!apiKey) {
    console.warn('NEXT_PUBLIC_AMPLITUDE_API_KEY is not set; Amplitude is off.');
    return;
  }

  started = true;
  amplitude.initAll(apiKey, {
    analytics: {
      autocapture: {
        elementInteractions: true,
      },
    },
  });
}

initAmplitude();

export { amplitude };

// -- components/AnalyticsProvider.tsx --
'use client';

import type { ReactNode } from 'react';
import '@/lib/amplitude';

export function AnalyticsProvider({ children }: { children: ReactNode }) {
  return <>{children}</>;
}

// -- components/IdentifyUser.tsx --
'use client';

import { useEffect } from 'react';
import { amplitude } from '@/lib/amplitude';
import { useAuth } from '@/lib/auth';

export function IdentifyUser() {
  const { user } = useAuth();

  useEffect(() => {
    if (!user) return;
    amplitude.setUserId(`user-${user.id}`);
    const identify = new amplitude.Identify();
    identify.set('plan', user.plan);
    amplitude.identify(identify);
  }, [user?.id, user?.plan]);

  return null;
}

// -- app/layout.tsx --
import type { ReactNode } from 'react';
import { AnalyticsProvider } from '@/components/AnalyticsProvider';
import { IdentifyUser } from '@/components/IdentifyUser';

export default function RootLayout({ children }: { children: ReactNode }) {
  return (
    <html lang="en">
      <body>
        <AnalyticsProvider>
          <IdentifyUser />
          {children}
        </AnalyticsProvider>
      </body>
    </html>
  );
}

// -- components/NewProjectButton.tsx --
'use client';

import { amplitude } from '@/lib/amplitude';

export function NewProjectButton({ template }: { template: string }) {
  function handleClick() {
    amplitude.track('Project Created', { template });
  }

  return <button onClick={handleClick}>Create project</button>;
}

// -- lib/amplitude-server.ts --
import { init, track, flush } from '@amplitude/analytics-node';

let started = false;

function ensureInit() {
  if (started) return;
  init(process.env.AMPLITUDE_API_KEY!);
  started = true;
}

export async function trackServerEvent(
  eventType: string,
  userId: string,
  eventProperties?: Record<string, unknown>,
) {
  ensureInit();
  track(eventType, eventProperties, { user_id: userId });
  await flush().promise;
}

// -- app/actions/upgrade.ts --
'use server';

import { trackServerEvent } from '@/lib/amplitude-server';
import { getCurrentUser } from '@/lib/auth';

export async function upgradePlan(plan: string) {
  const user = await getCurrentUser();
  await trackServerEvent('Plan Upgraded', `user-${user.id}`, {
    plan,
    source: 'billing_page',
  });
}

Add Amplitude product analytics to this Next.js App Router project by
following https://amplitude.com/build/nextjs-product-analytics exactly.
Install @amplitude/unified and @amplitude/analytics-node. Initialize the
browser SDK once at module scope in lib/amplitude.ts behind a typeof window
check and a started flag, reading NEXT_PUBLIC_AMPLITUDE_API_KEY, with
autocapture elementInteractions on. Import it from a 'use client'
AnalyticsProvider in app/layout.tsx. Set the user ID as "user-" + id where
auth resolves, call reset() on sign-out, and send the same "user-" + id from
server actions through lib/amplitude-server.ts, awaiting flush().promise.
Do not initialize in useEffect, do not add a manual page view hook, don't
hardcode keys, and don't invent event names; check the existing taxonomy
with the Amplitude MCP server if it's connected. Report every file you
changed and what to add to .env.local.