Subchapter 82.45

Next Js

references/next-js.mdMarkdown17 KBView on GitHub

AI agents: this is one page from PostHog’s docs. Full index of Markdown docs for LLMs: https://posthog.com/llms.txt (opens in a new tab)

Next.js

Next Js · Instrument Product Analytics · PostHog/skills · Skills Docs

If your site sets a Content-Security-Policy, it needs to allow PostHog. This applies to the snippet and to package installs alike: the SDK lazy-loads extra bundles (session replay, surveys) from PostHog’s CDN, and sends events to the ingestion host. PostHog serves from subdomains of posthog.com that change over time, so allow the wildcard:
script-src 'self' https://*.posthog.com;
connect-src 'self' https://*.posthog.com;
worker-src 'self' blob: data:;
script-src covers the snippet and the lazy-loaded bundles, connect-src covers event ingestion and feature flags, and worker-src covers session replay. The toolbar needs a few more (opens in a new tab), or use a reverse proxy (opens in a new tab) so everything is first-party. Failing to do so causes silent failures where capture and identify calls never send, so the integration looks complete while zero events arrive. Remember connect-src falls back to default-src, so default-src 'self' blocks event delivery even when the script itself is bundled.

"use client";
import posthog from "posthog-js";

export default function Home() {
  return (
    <div>
      <button onClick={() => posthog.capture("test_event")}>Click me for an event</button>
    </div>
  );
}

"use client";
import { useFeatureFlagEnabled } from "@posthog/react";

export default function FeatureComponent() {
  const showNewFeature = useFeatureFlagEnabled("new-feature");

  return showNewFeature ? <NewFeature /> : <OldFeature />;
}

// app/posthog.js
import { PostHog } from 'posthog-node'

export default function PostHogClient() {
  const posthogClient = new PostHog(process.env.NEXT_PUBLIC_POSTHOG_PROJECT_TOKEN, {
    host: process.env.NEXT_PUBLIC_POSTHOG_HOST,
    flushAt: 1,
    flushInterval: 0
  })
  return posthogClient
}

import Link from 'next/link'
import PostHogClient from '../posthog'

export default async function About() {

  const posthog = PostHogClient()
  const flags = await posthog.getAllFlags(
    'user_distinct_id' // replace with a user's distinct ID
  );
  await posthog.shutdown()

  return (
    <main>
      <h1>About</h1>
      <Link href="/">Go home</Link>
      { flags['main-cta'] &&
        <Link href="http://posthog.com/">Go to PostHog</Link>
      }
    </main>
  )
}

// pages/posts/[id].js
import { useContext, useEffect, useState } from 'react'
import { getServerSession } from "next-auth/next"
import { authOptions } from '@/lib/auth'
import { PostHog } from 'posthog-node'

export default function Post({ post, flags }) {
  const [ctaState, setCtaState] = useState()

  useEffect(() => {
    if (flags) {
      setCtaState(flags['blog-cta'])
    }
  })

  return (
    <div>
      <h1>{post.title}</h1>
      <p>By: {post.author}</p>
      <p>{post.content}</p>
      {ctaState &&
        <p><a href="/">Go to PostHog</a></p>
      }
      <button onClick={likePost}>Like</button>
    </div>
  )
}

export async function getServerSideProps(ctx) {

  // Pass authOptions, or your session callbacks don't run.
  const session = await getServerSession(ctx.req, ctx.res, authOptions)
  let flags = null

  if (session) {
    const client = new PostHog(
      process.env.NEXT_PUBLIC_POSTHOG_PROJECT_TOKEN,
      {
        host: process.env.NEXT_PUBLIC_POSTHOG_HOST,
      }
    )

    // A stable ID from your auth system, not an email. See the note below.
    const distinctId = session.user.id

    flags = await client.getAllFlags(distinctId);
    client.capture({
      distinctId,
      event: 'loaded blog article',
      properties: {
        $current_url: ctx.req.url,
      },
    });

    await client.shutdown()
  }

  const { posts } = await import('../../blog.json')
  const post = posts.find((post) => post.id.toString() === ctx.params.id)
  return {
    props: {
      post,
      flags
    },
  }
}

Note: next-auth doesn’t put a user ID on the session by default. Its session is { name, email, image }, so session.user.id is undefined until you add it yourself with a session callback in your authOptions:

JavaScript
// lib/auth.js
export const authOptions = {
  callbacks: {
    session({ session, token, user }) {
      // JWT sessions (the default) carry the user ID in token.sub.
      // Database sessions get it from user.id instead.
      session.user.id = token?.sub ?? user.id
      return session
    },
  },
}
Capturing with an undefined distinct ID creates events that belong to nobody, so check that the ID arrives before relying on it.

posthog.init(process.env.NEXT_PUBLIC_POSTHOG_PROJECT_TOKEN, {
  // ... your configuration
  fetch_options: {
    cache: 'force-cache', // Use Next.js cache
    next_options: {       // Passed to the `next` option for `fetch`
      revalidate: 60,     // Cache for 60 seconds
      tags: ['posthog'],  // Can be used with Next.js `revalidateTag` function
    },
  }
})

Next Js

Next.js

Next Js

Next.js

Prerequisites

Beta: integration via LLM

Client-side setup

npm

Yarn

pnpm

Bun

Integration

instrumentation-client.js

instrumentation-client.ts

Identifying users

Linking client and server events

Accessing PostHog

Using React hooks

Usage

Server-side analytics

npm

Yarn

pnpm

Bun

Router-specific instructions

App router

Pages router

Server-side configuration

Configuring a reverse proxy to PostHog

Further reading

Still have questions?

Was this page useful?