How to add feature flags and experiments to a Next.js app

npm install @amplitude/unified

NEXT_PUBLIC_AMPLITUDE_API_KEY=your-project-api-key
NEXT_PUBLIC_AMPLITUDE_DEPLOYMENT_KEY=your-client-deployment-key

import * as amplitude from '@amplitude/analytics-browser';
import { Experiment } from '@amplitude/experiment-js-client';

amplitude.init(process.env.NEXT_PUBLIC_AMPLITUDE_API_KEY!, undefined, { autocapture: true });
export const experiment = Experiment.initializeWithAmplitudeAnalytics(
  process.env.NEXT_PUBLIC_AMPLITUDE_DEPLOYMENT_KEY!,
);

// Amplitude drops user IDs shorter than 5 characters, and a user who has one
// ID in the browser and another on the server becomes two users. Every file
// that sends a user ID, browser or server, goes through this function.
export function toAmplitudeUserId(appUserId: string | number): string {
  return `user-${appUserId}`;
}

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

let started = false;
let flagsVersion = 0;
let fetchGeneration = 0;
let ready: Promise<unknown> = Promise.resolve();
const listeners = new Set<() => void>();

function notifyFlagsChanged() {
  flagsVersion += 1;
  listeners.forEach((listener) => listener());
}

async function refetchFlags() {
  const generation = ++fetchGeneration;
  try {
    // Remote evaluation. On failure or timeout the SDK returns and keeps
    // retrying in the background, so this always settles.
    await ready; // initAll is typed void, but the Next.js guide awaits it
    await amplitude.experiment()?.fetch();
  } finally {
    // Only the newest fetch updates components, so an anonymous fetch that
    // finishes after sign-in can't overwrite the signed-in result.
    if (generation === fetchGeneration) notifyFlagsChanged();
  }
}

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

  const apiKey = process.env.NEXT_PUBLIC_AMPLITUDE_API_KEY;
  if (!apiKey) {
    console.warn('NEXT_PUBLIC_AMPLITUDE_API_KEY is not set; Amplitude is off.');
    notifyFlagsChanged(); // let flag hooks fall back instead of loading forever
    return;
  }

  ready = Promise.resolve(amplitude.initAll(apiKey, {
    analytics: {
      autocapture: true,
    },
    experiment: {
      // Falls back to the project API key (the default deployment) if unset.
      deploymentKey: process.env.NEXT_PUBLIC_AMPLITUDE_DEPLOYMENT_KEY,
      fetchTimeoutMillis: 3000,
    },
  }));

  void refetchFlags();
}

export function identifyUser(userId: string) {
  initAmplitude();
  amplitude.setUserId(userId);
  void refetchFlags();
}

export function resetUser() {
  initAmplitude();
  amplitude.reset(); // clears the user ID and issues a new device ID
  amplitude.experiment()?.clear(); // drops the previous user's variants
  void refetchFlags();
}

export function subscribeFlags(listener: () => void) {
  listeners.add(listener);
  return () => {
    listeners.delete(listener);
  };
}

export function getFlagsVersion() {
  return flagsVersion;
}

export function whenAmplitudeReady() {
  return ready;
}

export { amplitude };

'use client';

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

export function AnalyticsProvider({ children }: { children: React.ReactNode }) {
  // Guarded: a no-op on the server and on every render after the first.
  initAmplitude();
  return <>{children}</>;
}

import { AnalyticsProvider } from '@/components/AnalyticsProvider';

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

'use client';

import { useEffect, useState, useSyncExternalStore } from 'react';
import { amplitude, getFlagsVersion, subscribeFlags } from '@/lib/amplitude';

export function useFlag(flagKey: string) {
  const version = useSyncExternalStore(subscribeFlags, getFlagsVersion, () => 0);
  const [value, setValue] = useState<string | null | undefined>(undefined);

  useEffect(() => {
    if (version === 0) return; // the first fetch hasn't settled yet
    // Reading the variant here, in an effect of the component that renders
    // it, is what ties the exposure to someone who reached this component.
    setValue(amplitude.experiment()?.variant(flagKey)?.value ?? null);
  }, [flagKey, version]);

  return { loading: value === undefined, value };
}

'use client';

import { useFlag } from '@/hooks/useFlag';

export function PricingTable() {
  const { loading, value } = useFlag('pricing-page-v2');

  if (loading) {
    return <div aria-busy="true" style={{ minHeight: 480 }} />;
  }

  if (value === 'on') {
    return <section>{/* the new pricing table */}New pricing</section>;
  }

  return <section>{/* the current pricing table */}Current pricing</section>;
}

import { PricingTable } from '@/components/PricingTable';

export default function PricingPage() {
  return (
    <main>
      <h1>Pricing</h1>
      <PricingTable />
    </main>
  );
}

'use client';

import { useEffect } from 'react';
import { identifyUser } from '@/lib/amplitude';
import { toAmplitudeUserId } from '@/lib/amplitude-ids';

export function IdentifyUser({ appUserId }: { appUserId: string | null }) {
  useEffect(() => {
    if (appUserId) identifyUser(toAmplitudeUserId(appUserId));
  }, [appUserId]);

  return null;
}

// -- .env.local --
NEXT_PUBLIC_AMPLITUDE_API_KEY=your-project-api-key
NEXT_PUBLIC_AMPLITUDE_DEPLOYMENT_KEY=your-client-deployment-key

// -- lib/amplitude-ids.ts --
export function toAmplitudeUserId(appUserId: string | number): string {
  return `user-${appUserId}`;
}

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

let started = false;
let flagsVersion = 0;
let fetchGeneration = 0;
let ready: Promise<unknown> = Promise.resolve();
const listeners = new Set<() => void>();

function notifyFlagsChanged() {
  flagsVersion += 1;
  listeners.forEach((listener) => listener());
}

async function refetchFlags() {
  const generation = ++fetchGeneration;
  try {
    await ready; // initAll is typed void, but the Next.js guide awaits it
    await amplitude.experiment()?.fetch();
  } finally {
    if (generation === fetchGeneration) notifyFlagsChanged();
  }
}

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

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

  ready = Promise.resolve(amplitude.initAll(apiKey, {
    analytics: {
      autocapture: true,
    },
    experiment: {
      deploymentKey: process.env.NEXT_PUBLIC_AMPLITUDE_DEPLOYMENT_KEY,
      fetchTimeoutMillis: 3000,
    },
  }));

  void refetchFlags();
}

export function identifyUser(userId: string) {
  initAmplitude();
  amplitude.setUserId(userId);
  void refetchFlags();
}

export function resetUser() {
  initAmplitude();
  amplitude.reset();
  amplitude.experiment()?.clear();
  void refetchFlags();
}

export function subscribeFlags(listener: () => void) {
  listeners.add(listener);
  return () => {
    listeners.delete(listener);
  };
}

export function getFlagsVersion() {
  return flagsVersion;
}

export function whenAmplitudeReady() {
  return ready;
}

export { amplitude };

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

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

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

// -- app/layout.tsx --
import { AnalyticsProvider } from '@/components/AnalyticsProvider';

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

// -- hooks/useFlag.ts --
'use client';

import { useEffect, useState, useSyncExternalStore } from 'react';
import { amplitude, getFlagsVersion, subscribeFlags } from '@/lib/amplitude';

export function useFlag(flagKey: string) {
  const version = useSyncExternalStore(subscribeFlags, getFlagsVersion, () => 0);
  const [value, setValue] = useState<string | null | undefined>(undefined);

  useEffect(() => {
    if (version === 0) return;
    setValue(amplitude.experiment()?.variant(flagKey)?.value ?? null);
  }, [flagKey, version]);

  return { loading: value === undefined, value };
}

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

import { useFlag } from '@/hooks/useFlag';

export function PricingTable() {
  const { loading, value } = useFlag('pricing-page-v2');

  if (loading) {
    return <div aria-busy="true" style={{ minHeight: 480 }} />;
  }

  if (value === 'on') {
    return <section>New pricing</section>;
  }

  return <section>Current pricing</section>;
}

// -- app/pricing/page.tsx --
import { PricingTable } from '@/components/PricingTable';

export default function PricingPage() {
  return (
    <main>
      <h1>Pricing</h1>
      <PricingTable />
    </main>
  );
}

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

import { useEffect } from 'react';
import { identifyUser } from '@/lib/amplitude';
import { toAmplitudeUserId } from '@/lib/amplitude-ids';

export function IdentifyUser({ appUserId }: { appUserId: string | null }) {
  useEffect(() => {
    if (appUserId) identifyUser(toAmplitudeUserId(appUserId));
  }, [appUserId]);

  return null;
}

Add Amplitude Feature Experiment to this Next.js App Router app by following
https://amplitude.com/build/nextjs-feature-flags exactly. Install
@amplitude/unified and call initAll once from lib/amplitude.ts behind a
started flag and a typeof window check, with experiment.deploymentKey read
from NEXT_PUBLIC_AMPLITUDE_DEPLOYMENT_KEY (a client deployment key, never a
server key). Call initAmplitude() during render in a 'use client'
AnalyticsProvider mounted in app/layout.tsx, not in useEffect. Read the
pricing-page-v2 flag only inside the component that renders it, in an
effect, never in a layout or shared hook, because variant() tracks an
exposure. Send user IDs through toAmplitudeUserId so they match the server.
Refetch on sign-in, and call reset() plus experiment()?.clear() only from
the sign-out handler. Don't enable Session Replay. Don't hardcode keys and
don't invent flag keys. Report every file you changed.