Next.js

Installation

npm install --save @outlit/browser

pnpm add @outlit/browser

yarn add @outlit/browser

bun add @outlit/browser

Quick start

App Router
Pages Router

Create a client component to initialize Outlit:

// app/providers.tsx
'use client'

import { useEffect } from 'react'
import outlit from '@outlit/browser'

export function OutlitProvider() {
  useEffect(() => {
    outlit.init({
      publicKey: process.env.NEXT_PUBLIC_OUTLIT_KEY!,
      trackPageviews: true,
    })
  }, [])

  return null
}

Add to your root layout:

// app/layout.tsx
import { OutlitProvider } from './providers'

export default function RootLayout({ children }: { children: React.ReactNode }) {
  return (
    <html>
      <body>
        <OutlitProvider />
        {children}
      </body>
    </html>
  )
}

Initialize in _app.tsx:

// pages/_app.tsx
import { useEffect } from 'react'
import type { AppProps } from 'next/app'
import outlit from '@outlit/browser'

export default function App({ Component, pageProps }: AppProps) {
  useEffect(() => {
    outlit.init({
      publicKey: process.env.NEXT_PUBLIC_OUTLIT_KEY!,
      trackPageviews: true,
    })
  }, [])

  return <Component {...pageProps} />
}

Add your public key to .env.local:

NEXT_PUBLIC_OUTLIT_KEY=pk_your_public_key_here

Using the React provider (recommended)

For a better experience with React hooks, use the React provider:

// app/providers.tsx
'use client'

import { OutlitProvider } from '@outlit/browser/react'

export function Providers({ children }: { children: React.ReactNode }) {
  return (
    <OutlitProvider
      publicKey={process.env.NEXT_PUBLIC_OUTLIT_KEY!}
      trackPageviews
    >
      {children}
    </OutlitProvider>
  )
}

// app/layout.tsx
import { Providers } from './providers'

export default function RootLayout({ children }: { children: React.ReactNode }) {
  return (
    <html>
      <body>
        <Providers>{children}</Providers>
      </body>
    </html>
  )
}

See the React integration guide for full React provider documentation.

Tracking events

Track custom events in client components:

// app/dashboard/page.tsx
'use client'

import { useEffect } from 'react'
import outlit from '@outlit/browser'

export default function Dashboard() {
  useEffect(() => {
    outlit.track('dashboard_viewed')
  }, [])

  function handleExport() {
    outlit.track('data_exported', {
      format: 'csv',
      rows: 1500
    })
  }

  return (
    <div>
      <h1>Dashboard</h1>
      <button onClick={handleExport}>Export Data</button>
    </div>
  )
}

With React provider

'use client'

import { useOutlit } from '@outlit/browser/react'

export default function PricingButton() {
  const { track } = useOutlit()

  return (
    <button onClick={() => track('pricing_clicked', { plan: 'pro' })}>
      View Pricing
    </button>
  )
}

Activation event

Track your value milestone as an ordinary event once it succeeds. For example, after your export action confirms completion, call outlit.track('report_exported', { format: 'csv' }) from the client component. Choose that event as your activation event in Outlit. The first matching event records activation once for each eligible resolved person and company, independently. Billing status comes from verified integrations such as Stripe. See Customer journey.

Identifying users

Identify users after authentication:

// app/login/page.tsx
'use client'

import { useState } from 'react'
import { useRouter } from 'next/navigation'
import outlit from '@outlit/browser'

export default function LoginPage() {
  const router = useRouter()
  const [email, setEmail] = useState('')
  const [password, setPassword] = useState('')

  async function handleLogin(e: React.FormEvent) {
    e.preventDefault()

    const user = await login(email, password)

    outlit.identify({
      email: user.email,
      userId: user.id,
      traits: {
        name: user.name,
        plan: user.plan
      }
    })

    router.push('/dashboard')
  }

  return (
    <form onSubmit={handleLogin}>
      <input
        type="email"
        value={email}
        onChange={(e) => setEmail(e.target.value)}
        placeholder="Email"
      />
      <input
        type="password"
        value={password}
        onChange={(e) => setPassword(e.target.value)}
        placeholder="Password"
      />
      <button type="submit">Login</button>
    </form>
  )
}

Server-side auth integration

With NextAuth

// app/providers.tsx
'use client'

import { OutlitProvider } from '@outlit/browser/react'
import { useSession } from 'next-auth/react'

export function Providers({ children }: { children: React.ReactNode }) {
  const { data: session, status } = useSession()

  const user = status === 'authenticated' && session?.user ? {
    email: session.user.email!,
    userId: session.user.id,
    traits: {
      name: session.user.name
    }
  } : null

  return (
    <OutlitProvider
      publicKey={process.env.NEXT_PUBLIC_OUTLIT_KEY!}
      user={user}
      trackPageviews
    >
      {children}
    </OutlitProvider>
  )
}

With Clerk

// app/providers.tsx
'use client'

import { OutlitProvider } from '@outlit/browser/react'
import { useUser } from '@clerk/nextjs'

export function Providers({ children }: { children: React.ReactNode }) {
  const { user, isLoaded } = useUser()

  const outlitUser = isLoaded && user ? {
    email: user.primaryEmailAddress?.emailAddress,
    userId: user.id,
    traits: {
      name: user.fullName
    }
  } : null

  return (
    <OutlitProvider
      publicKey={process.env.NEXT_PUBLIC_OUTLIT_KEY!}
      user={outlitUser}
      trackPageviews
    >
      {children}
    </OutlitProvider>
  )
}

With Supabase

// app/providers.tsx
'use client'

import { OutlitProvider } from '@outlit/browser/react'
import { createClientComponentClient } from '@supabase/auth-helpers-nextjs'
import { useEffect, useState } from 'react'

export function Providers({ children }: { children: React.ReactNode }) {
  const supabase = createClientComponentClient()
  const [user, setUser] = useState<any>(null)

  useEffect(() => {
    supabase.auth.getSession().then(({ data: { session } }) => {
      setUser(session?.user ?? null)
    })

    const { data: { subscription } } = supabase.auth.onAuthStateChange((_event, session) => {
      setUser(session?.user ?? null)
    })

    return () => subscription.unsubscribe()
  }, [supabase])

  const outlitUser = user ? {
    email: user.email,
    userId: user.id,
    traits: {
      name: user.user_metadata?.name
    }
  } : null

  return (
    <OutlitProvider
      publicKey={process.env.NEXT_PUBLIC_OUTLIT_KEY!}
      user={outlitUser}
      trackPageviews
    >
      {children}
    </OutlitProvider>
  )
}

Server actions

Track events from server actions:

// app/actions.ts
'use server'

import { Outlit } from '@outlit/node'

const outlit = new Outlit({
  publicKey: process.env.OUTLIT_KEY!
})

export async function trackServerEvent(userId: string) {
  outlit.track({
    userId,
    eventName: 'server_action_completed',
    timestamp: Date.now(),
    properties: {
      action: 'data_export'
    }
  })

  await outlit.flush()
}

For server-side tracking, see the Node.js integration guide.

API routes

Track events from API routes:

// app/api/checkout/route.ts
import { NextResponse } from 'next/server'
import { Outlit } from '@outlit/node'

const outlit = new Outlit({
  publicKey: process.env.OUTLIT_KEY!
})

export async function POST(request: Request) {
  const { userId, amount } = await request.json()

  outlit.track({
    userId,
    eventName: 'checkout_completed',
    properties: { amount }
  })

  await outlit.flush()

  return NextResponse.json({ success: true })
}

Middleware

Don’t track in middleware: it cannot reliably respect the visitor’s consent choice or guarantee delivery, and it can double-count pageviews the Outlit Browser SDK already sends. Use browser pageview tracking for page activity and @outlit/node in Server Actions or Route Handlers for server events, where you can await outlit.flush() (see the Outlit Node.js SDK guide).

Environment variables

Set up your environment variables:

# .env.local

# Public key (used in browser)
NEXT_PUBLIC_OUTLIT_KEY=pk_your_public_key_here

# Server key (used in server actions/API routes)
OUTLIT_KEY=pk_your_public_key_here

Keep server environment variables out of client-side code. Only use OUTLIT_KEY in server components, API routes, or server actions.

TypeScript support

Full TypeScript support is included:

import outlit, { type OutlitOptions } from '@outlit/browser'

const options: OutlitOptions = {
  publicKey: process.env.NEXT_PUBLIC_OUTLIT_KEY!,
  trackPageviews: true,
  flushInterval: 5000
}

outlit.init(options)

Next steps

React provider

Full React integration guide

Server-side tracking

Track events from your backend

Identity resolution

Learn how visits and events link to people

npm package

Full API reference

Agents

CLI

Concepts

Outlit SDKs

Examples

Installation

Quick start

Using the React provider (recommended)

Tracking events

With React provider

Activation event

Identifying users

Server-side auth integration

With NextAuth

With Clerk

With Supabase

Server actions

API routes

Middleware

Environment variables

TypeScript support

Next steps

React provider

Server-side tracking

Identity resolution

npm package

​Installation

​Quick start

​Using the React provider (recommended)

​Tracking events

​With React provider

​Activation event

​Identifying users

​Server-side auth integration

​With NextAuth

​With Clerk

​With Supabase

​Server actions

​API routes

​Middleware

​Environment variables

​TypeScript support

​Next steps

React provider

Server-side tracking

Identity resolution

npm package

Installation

Quick start

Using the React provider (recommended)

Tracking events

With React provider

Activation event

Identifying users

Server-side auth integration

With NextAuth

With Clerk

With Supabase

Server actions

API routes

Middleware

Environment variables

TypeScript support

Next steps