Next.js: @posthog/next

Add these to your .env.local file and to your hosting provider (e.g. Vercel, Netlify, AWS). You can find your project token in your project settings.

NEXT_PUBLIC_POSTHOG_KEY=<ph_project_api_key>
NEXT_PUBLIC_POSTHOG_HOST=https://us.i.posthog.com

NEXT_PUBLIC_POSTHOG_HOST is optional and defaults to https://us.i.posthog.com.

The middleware seeds an identity cookie on first visit so client and server share the same user, and optionally proxies API requests through your domain.

import { postHogMiddleware } from '@posthog/next'

export default postHogMiddleware({ proxy: true })

export const config = {
    matcher: ['/((?!_next/static|_next/image|favicon.ico).*)'],
}

Setting proxy: true routes PostHog API calls through your domain at /ingest, which helps avoid ad blockers. You can customize the path prefix by passing proxy: { pathPrefix: '/analytics' } instead.

Note: Middleware requires a server runtime and is not available with output: 'export' (fully static sites). If you can't use middleware, you can set up a reverse proxy separately to route traffic through your domain.

Visit your app and click around. Within a minute or two, you should see $pageview and autocaptured events (like clicks) appear in the activity tab.

All hooks must be used in client components ('use client').

Capture events:

'use client'
import { usePostHog } from '@posthog/next'

export function TrackButton() {
    const posthog = usePostHog()
    return <button onClick={() => posthog.capture('button_clicked')}>Track</button>
}

Feature Flags:

'use client'
import { useFeatureFlag } from '@posthog/next'

export function MyComponent() {
    const flag = useFeatureFlag('new-feature')
    return flag?.enabled ? <NewFeature /> : <OldFeature />
}

Conditional rendering with PostHogFeature:

'use client'
import { PostHogFeature } from '@posthog/next'

export function NewBanner() {
    return (
        <PostHogFeature flag="show-banner" match={true}>
            <div>New feature available!</div>
        </PostHogFeature>
    )
}

You can also read the full posthog-js documentation for all the usable functions.

Call posthog.identify() on the client after login to link events to a known user. This connects event captures, session replays, LLM traces, and Error Tracking to the same person across client and server.

'use client'
import { usePostHog } from '@posthog/next'

export function LoginButton() {
    const posthog = usePostHog()

    const handleLogin = async () => {
        const user = await signIn()
        posthog.identify(user.id, {
            email: user.email,
            name: user.name,
        })
    }

    return <button onClick={handleLogin}>Log in</button>
}

See our guide on identifying users for more details.

For server-side events and feature flag evaluations, PostHog can use the client-provided identity cookie and tracing headers to link analytics across the request. These values come from the client. When you need a strict guarantee that analytics uses the identity from your authenticated session, provide an authoritative distinct ID directly when capturing an event or evaluating feature flags, or configure getDistinctId in createPostHog() to resolve it from your server session by default.

import 'server-only'
import { createPostHog } from '@posthog/next'
import { auth } from '@/auth'

export const { getPostHog } = createPostHog({
    // Optional: resolve a trusted distinct ID from your auth session.
    // Return null or undefined to fall back to the client identity.
    getDistinctId: async () => (await auth())?.user?.id,
})

import { getPostHog } from '@/lib/posthog'

export default async function DashboardPage() {
    const posthog = await getPostHog()

    const flags = await posthog.getAllFlags()

    return (
        <div>{flags['new-dashboard'] ? <NewDashboard /> : <OldDashboard />}</div>
    )
}

import { createPostHog } from '@posthog/next/pages'
import { getServerSession } from 'next-auth'
import { authOptions } from '@/lib/auth'

export const { getPostHog } = createPostHog({
    // Optional: resolve a trusted distinct ID from your auth session.
    // The resolver receives the GetServerSidePropsContext.
    getDistinctId: async (ctx) =>
        (await getServerSession(ctx.req, ctx.res, authOptions))?.user?.id,
})

import type { GetServerSideProps } from 'next'
import { getPostHog } from '@/lib/posthog'

export const getServerSideProps: GetServerSideProps = async (ctx) => {
    const posthog = await getPostHog(ctx)

    const flags = await posthog.evaluateFlags({ flagKeys: ['new-dashboard'] })
    const showNewDashboard = flags.isEnabled('new-dashboard')

    return { props: { showNewDashboard } }
}

export const getServerSideProps: GetServerSideProps = async (ctx) => {
    const posthog = await getPostHog(ctx)
    const posthogBootstrap = await posthog.getAllFlagsAndPayloads()
    return { props: { posthogBootstrap } }
}

import type { AppProps } from 'next/app'
import { PostHogProvider, PostHogPageView } from '@posthog/next/pages'

export default function App({ Component, pageProps }: AppProps) {
    return (
        <PostHogProvider
            apiKey={process.env.NEXT_PUBLIC_POSTHOG_KEY!}
            clientOptions={{
                api_host: '/ingest',
                bootstrap: pageProps.posthogBootstrap,
            }}
        >
            <PostHogPageView />
            <Component {...pageProps} />
        </PostHogProvider>
    )
}

Note: Avoid capturing page views or other navigation events while rendering a Server Component or running getServerSideProps. Rendering doesn't prove that a navigation completed. The App Router can execute render code while prefetching, and Next.js can retry renders. Use PostHogPageView for page views, and capture server-side events from handlers invoked for the action you want to measure.

Dynamic rendering keeps personalized flag decisions out of Next.js's shared Full Route Cache. The App Router can still reuse a React Server Component payload from its client Router Cache. After an authentication or identity change, use router.refresh() when the current route's server-rendered flag decisions must be evaluated again.

@posthog/next enables automatic browser exception capture by default. On Next.js 15 and later, capture server-side request errors by exporting onRequestError from your root instrumentation.ts file:

export { onRequestError } from '@posthog/next'

Next.js calls this hook when a Server Component, Route Handler, or Server Action throws during a request. When available, the PostHog identity cookie links the exception to the same user and session. Import this hook from @posthog/next for both App Router and Pages Router applications.

Use createOnRequestError() when you need to add properties, filter errors, or customize the server client. You can disable automatic browser exception capture with clientOptions={{ capture_exceptions: false }}.

Bootstrap feature flags

In the App Router, set bootstrapFlags to evaluate feature flags on the server and pass the results to the client, which avoids flag flicker on first render:

<PostHogProvider bootstrapFlags>{children}</PostHogProvider>

You can also limit the flags evaluated and provide properties used for evaluation:

<PostHogProvider
    bootstrapFlags={{
        flags: ['new-ui', 'pricing-v2'],
        groups: { company: 'posthog' },
        personProperties: { plan: 'enterprise' },
        groupProperties: {
            company: { industry: 'tech' },
        },
    }}
>
    {children}
</PostHogProvider>

Enabling bootstrapFlags calls cookies() internally, which opts every page route rendered through that provider into dynamic rendering. If the provider is in your root layout, this includes every page in your app. To preserve static rendering elsewhere, enable bootstrapFlags in the narrowest layout that needs server-evaluated flags. In the Pages Router, evaluate feature flags inside getServerSideProps and pass the result through clientOptions.bootstrap as shown in the server setup above.

Tracing headers

@posthog/next adds X-POSTHOG-DISTINCT-ID and X-POSTHOG-SESSION-ID headers to same-origin browser requests by default. This connects server events and feature flag evaluations to the browser user and session.

Pass clientOptions.tracing_headers to customize the hostnames that receive these headers, or use an empty array to disable them:

<PostHogProvider clientOptions={{ tracing_headers: [] }}>{children}</PostHogProvider>

Consent-aware setup

If your app requires consent before setting cookies, disable anonymous cookie seeding in middleware:

export default postHogMiddleware({
    proxy: true,
    seedAnonymousCookie: false,
})

Then initialize the client with capture disabled until you opt in:

<PostHogProvider clientOptions={{ opt_out_capturing_by_default: true }}>{children}</PostHogProvider>

API proxy options

Pass an object to proxy to customize the ingest path or host:

export default postHogMiddleware({
    proxy: {
        pathPrefix: '/analytics',
        host: 'https://eu.i.posthog.com',
    },
})

When you change the proxy path, use the same path in clientOptions.api_host:

<PostHogProvider clientOptions={{ api_host: '/analytics' }}>{children}</PostHogProvider>

• How to set up Next.js analytics, Feature Flags, and more
• How to set up Next.js A/B tests
• Upload source maps for Next.js Error Tracking