Company Logo
Illustration for How to Install and Initialize Amplitude Analytics in Your React/Next.js Project

How to Install and Initialize Amplitude Analytics in Your React/Next.js Project

Amplitude is a powerful analytics platform for product teams, offering event tracking, session replay, and deep insights into user behavior. Integrating Amplitude into your React or Next.js project is straightforward and unlocks valuable data for improving your product.

Why Use Amplitude Analytics?

  • Product Analytics: Track user actions, funnels, and retention.
  • Session Replay: Watch real user sessions to debug and improve UX.
  • Autocapture: Automatically track clicks and element interactions.
  • Scalable: Works for startups and enterprises alike.

In this guide, you'll learn how to:

  • Install Amplitude SDKs
  • Configure environment variables
  • Initialize Amplitude only in production
  • Track events and enable session replay

Step 1: Install Amplitude SDKs

Use pnpm (the package manager we will use for this example) or you can use npm or yarn if you prefer. To add the official Amplitude SDKs:

pnpm add @amplitude/analytics-browser @amplitude/plugin-autocapture-browser

Step 2: Add Environment Variables

Keep your API key secure and control analytics by environment. Add the following to your environment file:

.env.production

NEXT_PUBLIC_AMPLITUDE_API_KEY=your-amplitude-api-key-here
NEXT_PUBLIC_AMPLITUDE_ENABLED=true

For local development or non-production, disable analytics:

NEXT_PUBLIC_AMPLITUDE_ENABLED=false

Tip: Never commit your real API key to public repos.

Step 3: Create the Amplitude Initialization File

Create a file at:

src/app/lib/amplitude.ts

With the following code:

import * as amplitude from '@amplitude/analytics-browser'
import { autocapturePlugin } from '@amplitude/plugin-autocapture-browser'


export const initAmplitude = () => {
  if (typeof window === 'undefined') return
  const isAmplitudeEnabled =
    process.env.NEXT_PUBLIC_AMPLITUDE_ENABLED === 'true'
  if (!isAmplitudeEnabled) return
  const apiKey = process.env.NEXT_PUBLIC_AMPLITUDE_API_KEY as string
  console.log('Amplitude initializing...', apiKey)


  amplitude.init(apiKey, {
    autocapture: {
      elementInteractions: true,
    },
  })
  amplitude.add(autocapturePlugin())
}

What this does:

  • Only initializes Amplitude in the browser and if enabled.
  • Uses environment variables for safety.
  • Enables autocapture for element interactions.

Step 4: Initialize Amplitude on the Client

Create a client component to initialize Amplitude on every page load. Example:

src/app/components/AppInitializer.tsx

'use client'
import { useEffect } from 'react'
import { initAmplitude } from '@/lib'


export const AppInitializer = () => {
  useEffect(() => {
    initAmplitude()
  }, [])
  return null
}

Add AppInitializer to your root layout:

<body>
  <AppInitializer />
  {/* ...rest of your layout... */}
</body>

Step 5: Track Events

To log custom events anywhere in your app:

import * as amplitude from '@amplitude/analytics-browser'


amplitude.track('EVENT_NAME', {
  /* event properties */
})

Or, if you want to wrap this for DRYness, export amplitude from your lib:

// In src/app/lib/amplitude.ts
export { amplitude }

Then import and use:

import { amplitude } from '@/lib/amplitude'
amplitude.track('Button Clicked', { button: 'Sign Up' })

Best Practices & Troubleshooting

  • Production Only: Only enable Amplitude in production by setting in your environment file:

.env.production

NEXT_PUBLIC_AMPLITUDE_ENABLED=true
  • Keep API Key Secret: Never expose your API key in public code or non-production environments.
  • Session Replay: For advanced features like session replay, see the Amplitude docs.
  • Autocapture: The autocapture plugin tracks clicks and element interactions automatically.

Conclusion

You've now integrated Amplitude analytics and session replay into your React/Next.js project! With this setup, you can:

  • Track user events
  • Watch session replays
  • Analyze product usage

For more advanced analytics, explore Amplitude's documentation and consider event schemas, user properties, and privacy best practices.