Next.js SDK | Documentation

Use the Next.js SDK for App Router and Pages Router apps. It wraps the Web SDK and adds React helpers plus a route handler proxy.

Install

npm install @flash-analytics/nextjs@2.2.0

pnpm add @flash-analytics/nextjs@2.2.0

App Router setup

import { FlashAnalyticsComponent } from '@flash-analytics/nextjs';

export default function RootLayout({
  children,
}: Readonly<{ children: React.ReactNode }>) {
  return (
    <html lang="en">
      <body>
        <FlashAnalyticsComponent
          appId={process.env.NEXT_PUBLIC_FLASH_ANALYTICS_APP_ID!}
          endpoint={process.env.NEXT_PUBLIC_FLASH_ANALYTICS_ENDPOINT ?? 'https://api.flashanalytics.app'}
          capturePageViews
          captureErrors
          captureVariants
        />
        {children}
      </body>
    </html>
  );
}

Pages Router setup

import type { AppProps } from 'next/app';
import { FlashAnalyticsComponent } from '@flash-analytics/nextjs';

export default function App({ Component, pageProps }: AppProps) {
  return (
    <>
      <FlashAnalyticsComponent
        appId={process.env.NEXT_PUBLIC_FLASH_ANALYTICS_APP_ID!}
        endpoint="https://api.flashanalytics.app"
        capturePageViews
      />
      <Component {...pageProps} />
    </>
  );
}

Client helpers

'use client';

import { useFlashAnalytics } from '@flash-analytics/nextjs';

export function ExampleButton() {
  const analytics = useFlashAnalytics();

  return (
    <button onClick={() => analytics.track('button_clicked')}>
      Track
    </button>
  );
}

useFlashAnalytics() exposes browser-side helpers including track, identify, setGlobalProperties, getSession, assignExperiment, autoAssignExperiments, getAllExperiments, getExperimentById, fetchRemoteConfig, and revenue helpers.

Experiments

Enable captureVariants to keep a local cache of assignments in sync automatically. On each new session all experiments are fetched; after identify() only profile-mode assignments are refreshed; on session expiry only session-mode entries are removed.

'use client';

import { useFlashAnalytics } from '@flash-analytics/nextjs';

export function PricingBanner() {
  const analytics = useFlashAnalytics();

  // All cached assignments — no API call
  const all = analytics.getAllExperiments();

  // Single experiment — checks cache first, falls back to API if not found
  const assignment = await analytics.getExperimentById('checkout-cta');
  console.log(assignment?.variantName);
}

Route handler proxy

import { createRouteHandler } from '@flash-analytics/nextjs/server';

export const { GET, POST } = createRouteHandler({
  endpoint: 'https://api.flashanalytics.app',
});

Use clientSecret when you want the proxy to attach it server-side.

Error tracking

captureErrors emits js_error and unhandled_promise_rejection
FlashErrorBoundary emits client_error with errorType: react_render_error
useAutoErrorTracking() still exists for legacy setups

import { FlashAnalyticsComponent, FlashErrorBoundary } from '@flash-analytics/nextjs';

export default function RootLayout({ children }: { children: React.ReactNode }) {
  const appId = process.env.NEXT_PUBLIC_FLASH_ANALYTICS_APP_ID!;
  const endpoint = process.env.NEXT_PUBLIC_FLASH_ANALYTICS_ENDPOINT ?? 'https://api.flashanalytics.app';

  return (
    <html lang="en">
      <body>
        <FlashAnalyticsComponent
          appId={appId}
          endpoint={endpoint}
          capturePageViews
          captureErrors
        />
        <FlashErrorBoundary
          clientId={appId}
          apiUrl={`${endpoint}/track`}
          fallback={<h1>Something went wrong.</h1>}
        >
          {children}
        </FlashErrorBoundary>
      </body>
    </html>
  );
}