Type-safe Amplitude in Next.js

Analytics in Next.js App Router has two environments to worry about. Client components run in the browser and use @amplitude/analytics-browser. Server Components, Route Handlers, and Server Actions run on Node and use @amplitude/analytics-node. They initialize differently, they authenticate differently (client uses a public key, server uses a private key), and they send different default properties.

That split breaks most typed-analytics setups, which assume one SDK. Ordaze generates two wrappers from the same tracking plan, one for the browser, one for Node, and the scanner understands that a call inside a "use client" file is different from the same call inside a Server Action.

The Amplitude SDK

This guide assumes you are installing the official Amplitude SDK. The typed wrapper Ordaze generates sits on top of it and calls into it directly. You are not replacing your analytics provider, just adding a type-safe layer.

npm install @amplitude/analytics-browser

Setup in 5 steps

1. 1

   Install both Amplitude SDKs

   The browser SDK is for client components. The Node SDK is for Server Actions, Route Handlers, and background jobs. Both are needed if your tracking plan fires events from both sides.

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

2. 2

   Initialize Amplitude in a client provider

   Create a client component that initializes amplitude-browser on mount and wraps your app. Keep the public key in NEXT_PUBLIC_AMPLITUDE_KEY so it is safe to ship to the browser.

   // app/analytics-provider.tsx
   "use client";
   import { useEffect } from 'react';
   import * as amplitude from '@amplitude/analytics-browser';
   
   export function AnalyticsProvider({ children }: { children: React.ReactNode }) {
     useEffect(() => {
       amplitude.init(process.env.NEXT_PUBLIC_AMPLITUDE_KEY!, {
         defaultTracking: false,
       });
     }, []);
     return <>{children}</>;
   }

3. 3

   Define events in Ordaze and generate both wrappers

   In the Ordaze dashboard, export the Amplitude codegen twice: once for the browser target (TypeScript + analytics-browser) and once for the Node target (TypeScript + analytics-node). Both files expose the same typed method names; they differ only in which SDK they call.

4. 4

   Use the client wrapper in components, the Node wrapper in Server Actions

   Import from analytics/events.client.ts inside "use client" files. Import from analytics/events.server.ts inside Server Actions and Route Handlers. The method signatures are identical, so moving a call between client and server only changes the import.

5. 5

   Run the scanner in CI on both client and server code

   The Ordaze scanner reads all TypeScript source, identifies which files are client components vs server code via Next.js conventions, and fails the PR if either side drifts from the plan.

Before and after

// components/UpgradeButton.tsx
"use client";
import * as amplitude from '@amplitude/analytics-browser';

export function UpgradeButton() {
  return <button onClick={() => {
    amplitude.track('Upgrade Started', { Plan: 'pro' });
  }}>Upgrade</button>;
}

// app/api/checkout/route.ts
import { track } from '@amplitude/analytics-node';

export async function POST() {
  track('upgrade_completed', { plan: 'pro' }, { user_id: userId });
  //     ^ different casing vs 'Upgrade Completed' used on the client
}

// components/UpgradeButton.tsx
"use client";
import { track } from '@/analytics/events.client';

export function UpgradeButton() {
  return <button onClick={() => {
    track.upgradeStarted({ plan: 'pro' });
  }}>Upgrade</button>;
}

// app/api/checkout/route.ts
import { track } from '@/analytics/events.server';

export async function POST() {
  track.upgradeCompleted({ plan: 'pro' }, { userId });
}

Next.js + Amplitude gotchas

Why Ordaze for this combo

Frequently asked questions

Keep reading