Next.js — App Router

This guide is for Next.js projects that use the /app directory (Next.js 13+). If your project has a /pages folder instead, use this guide

Before starting: Get your API key from Settings

Step 1 — Install the SDK

npm install analytiq

Step 2 — Create `components/analytics.tsx` (One-time setup)

Create this file anywhere in your project. This is the only place Analytiq is configured.

TypeScript (analytics.tsx)
JavaScript (analytics.js)

components/analytics.tsx

'use client'
// ↑ Required — tells Next.js this runs in the browser, not the server

import { Analytiq, identify, reset, track } from 'analytiq/react'
import { useEffect } from 'react'

// Import YOUR app's authentication hook here
import { useAuth } from '@/context/AuthContext'

export function AnalyticsProvider({ children }: { children: React.ReactNode }) {
  const { user } = useAuth()

  // Bridges your Auth system to the Analytics SDK
  useEffect(() => {
    if (user) {
      identify(user)
    } else {
      reset()
    }
  }, [user])

  return (
    <>
      <Analytiq apiKey={process.env.NEXT_PUBLIC_ANALYTIQ_KEY!} />
      {children}
    </>
  )
}

// Re-export track so other files import from here, not the package directly
export { track }

components/analytics.js

'use client'
// ↑ Required — tells Next.js this runs in the browser, not the server

import { Analytiq, identify, reset, track } from 'analytiq/react'
import { useEffect } from 'react'
import { useAuth } from '@/context/AuthContext'

export function AnalyticsProvider({ children }) {
  const { user } = useAuth()

  useEffect(() => {
    if (user) {
      identify(user)
    } else {
      reset()
    }
  }, [user])

  return (
    <>
      <Analytiq apiKey={process.env.NEXT_PUBLIC_ANALYTIQ_KEY} />
      {children}
    </>
  )
}

export { track }

Add your API key to .env.local:

NEXT_PUBLIC_ANALYTIQ_KEY=pk_live_your_actual_key_here

The prefix must be NEXT_PUBLIC_. Any other prefix (like VITE_ or just ANALYTIQ_KEY) will make the key undefined on the client.

Step 3 — Wrap your app in `app/layout.tsx`

Open your existing app/layout.tsx and wrap the children with the provider. Make sure it goes inside your Auth provider.

TypeScript (layout.tsx)
JavaScript (layout.js)

app/layout.tsx

import { AuthProvider } from '@/context/AuthContext'
import { AnalyticsProvider } from '@/components/analytics'

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

app/layout.js

import { AuthProvider } from '@/context/AuthContext'
import { AnalyticsProvider } from '@/components/analytics'

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

Setup is complete! You never need to touch these two files again for analytics purposes.

What the setup handles automatically

Action	What happens
App loads (user logged out)	`init()` runs once, anonymous tracking begins
App loads (user already logged in)	`userId` restored from `localStorage`, user identified instantly
User logs in (your auth changes)	`useEffect` detects new user → `identify(user)` called automatically
User logs out (your auth clears)	`user` becomes `null` → `reset()` called automatically

Step 4 — Track Custom Events

For specific actions (page views, button clicks, purchases), import track() from your analytics.tsx file and call it where the action happens. Always add 'use client' at the top since track() is browser-only.

Track a page view
Button click
After API call

app/page.tsx

'use client'
import { useEffect } from 'react'
import { track } from '@/components/analytics'   // Import from your hub!

export default function HomePage() {
  useEffect(() => {
    track('Home_page_view')
  }, [])

  return <main><h1>Home</h1></main>
}

app/pricing/page.tsx

'use client'
import { track } from '@/components/analytics'

export default function PricingPage() {
  return (
    <button onClick={() => track('upgrade_clicked', { plan: 'Pro' })}>
      Upgrade to Pro
    </button>
  )
}

app/checkout/page.tsx

'use client'
import { track } from '@/components/analytics'

async function handlePayment(data: any) {
  const result = await processPayment(data)

  if (result.success) {
    track('order_completed', { order_id: result.id, total: result.total })
  } else {
    track('payment_failed', { reason: result.error })
  }
}

Step 5 — Verify it’s working

Run: npm run dev
Log into your app (so your useAuth returns a user)
Open http://localhost:3000, press F12 → Network tab, filter by track
You should see a POST /api/events/track request for any event you fire manually

Common Mistakes

Mistake	Symptom	Fix
Missing `'use client'` on any file using `track()`	Build error about server components	Add `'use client'` as the very first line
Using `ANALYTIQ_KEY` without `NEXT_PUBLIC_`	`undefined` key warning in console	Rename to `NEXT_PUBLIC_ANALYTIQ_KEY`
`AnalyticsProvider` outside `AuthProvider`	`useAuth()` context error	Auth must wrap Analytics in `layout.tsx`
Importing `track` directly from `analytiq`	Events may fire before SDK initializes	Always import from your local `analytics.tsx` hub

Getting Started

Framework Guides

Guides

Help

Next.js — App Router

Step 1 — Install the SDK

Step 2 — Create `components/analytics.tsx` (One-time setup)

Step 3 — Wrap your app in `app/layout.tsx`

What the setup handles automatically

Step 4 — Track Custom Events

Step 5 — Verify it’s working

Common Mistakes

​Step 1 — Install the SDK

​Step 2 — Create components/analytics.tsx (One-time setup)

​Step 3 — Wrap your app in app/layout.tsx

​What the setup handles automatically

​Step 4 — Track Custom Events

​Step 5 — Verify it’s working

​Common Mistakes

Step 1 — Install the SDK

Step 2 — Create `components/analytics.tsx` (One-time setup)

Step 3 — Wrap your app in `app/layout.tsx`

What the setup handles automatically

Step 4 — Track Custom Events

Step 5 — Verify it’s working

Common Mistakes