Analytics

Pageview tracking

Once initialized, a separate component, PostHogPageView, watches the current route with usePathname() and useSearchParams(). Every time the URL changes, it fires a $pageview event, deduplicated against the last URL it already tracked so the same page is never counted twice in a row.

This entire behavior is controlled by a single config flag: capturePageActivity. PostHog’s own automatic pageview tracking is always disabled at the library level (capture_pageview: false), so this flag is the only thing turning pageview and pageleave tracking on or off.

Setting capturePageActivity to false stops both pageview and pageleave events from being sent, while leaving identification and any manually captured custom events untouched. This is useful in a few real scenarios, not just to reduce noise. Pageviews and pageleaves are typically the highest volume event type PostHog receives, since they fire on every navigation for every visitor, so turning them off conserves your event quota for the custom events you actually care about. It also helps if page level traffic is not meaningful for your product, for example a single page dashboard where the URL barely changes, or if you are intentionally minimizing what you collect beyond what consent alone requires.

Identifying users

PostHog treats anonymous visitors and known users differently. By default, every event is attributed to an anonymous, randomly generated ID. PostHogIdentify is what connects that anonymous activity to an actual signed-in user.

Rather than living once in the root layout, where no user session exists yet, PostHogIdentify is rendered inside the layout of each authenticated route group, after the session has already been resolved server-side. Here is what that looks like in the admin section:

PostHogIdentify calls identify() exactly once per mount, tracked with a ref, so re-renders of the surrounding layout do not re-send the identify call. If you add a new authenticated section to the app, for instance a separate layout for a teams area, drop PostHogIdentify into that layout the same way, with whatever user fields are available in that session.

Why there is no /api/ingest route

If you go looking for a route handler that receives analytics calls, you will not find one. None exists, and none is needed.

next.config.ts defines a rewrites() rule that runs before any of the app’s own routes are matched:

When the browser calls PostHog with api_host: "/ingest", the request hits your own domain first, and Next.js silently forwards it server side to PostHog’s real ingestion host before your app code ever sees it. The browser only ever talks to your own domain, never to posthog.com directly.

This exists for the same reason tunnelRoute exists for Sentry elsewhere in the same file: posthog.com and i.posthog.com are commonly blocked by ad blockers and privacy extensions, while a same origin path like yourdomain.com/ingest is not.

proxy.ts is configured to never run on this path, since it carries outbound analytics traffic rather than a page a visitor is navigating to:

Content Security Policy entries

The rewrite above happens entirely on the server. From the browser’s perspective, it only ever calls /ingest on your own domain, and never initiates a request to PostHog directly. That is what keeps it invisible to ad blockers.

The Content Security Policy is a separate, browser enforced check, and it evaluates network requests against where they are actually forwarded to, not just the path the browser called. So even though the browser never directly addresses PostHog, the policy still needs PostHog’s real hosts allowed, or the browser will block the request once Next.js forwards it there. lib/csp.ts grants this using the same host values as next.config.ts:

These two values are added to two separate directives, for two separate reasons:

• connect-src includes both posthogHost and posthogAssetHost. This is what allows the browser’s network requests to actually reach PostHog once the /ingest rewrite forwards them there. The policy is checked against the real destination, not the original same origin path the browser called.
• img-src includes only posthogAssetHost, since that host serves PostHog’s static assets rather than event data.

If you change NEXT_PUBLIC_POSTHOG_HOST to a self-hosted or region-specific domain, both of these update automatically, since they are derived from the same environment variable rather than hardcoded.

Configuration

Whether analytics is active at all, and whether pageview tracking runs, are both controlled in config/site.ts.

enabled

Defaults to false. PostHog stays entirely inactive until you explicitly set this to true. While false, PostHogProvider renders its children directly and does nothing else: PostHog is never initialized, no script loads, and no network requests are made, regardless of whether credentials are present in .env.local.

capturePageActivity

Controls pageview and pageleave tracking specifically. Identification and any custom events you capture elsewhere in the app are unaffected by this flag. See Pageview tracking above.

Environment variables

Two environment variables are required to actually send data to PostHog. Both are optional in env.ts, since the application functions without them, just with enabled effectively doing nothing.

Both are prefixed NEXT_PUBLIC_ because they are read in the browser, not just on the server. This is safe. The value you put in NEXT_PUBLIC_POSTHOG_KEY is PostHog’s project API key, which is write only. It can send new events but cannot read anything back out of your PostHog project, so there is no meaningful risk in it being visible in client side code.

Setting up PostHog

Common issues

No events are showing up in PostHog

Check, in order: that analytics.postHog.enabled is true in config/site.ts, that NEXT_PUBLIC_POSTHOG_KEY is set and correct, that you have actually accepted the analytics consent option in the cookie banner, and that you are looking at the correct PostHog project and region.

Pageviews are missing but identification still works

This means capturePageActivity is set to false. This flag only controls pageview and pageleave events. Identification, triggered separately by PostHogIdentify, is unaffected by it.

Events are attributed to the wrong user, or to an anonymous ID after sign in

This usually means PostHogIdentify is not rendered in the layout for that section of the app. Check that the route group the user is on actually renders PostHogIdentify with the current session’s userId, the same way app/(protected)/admin/layout.tsx does.

Consent banner is dismissed, but analytics still is not capturing anything

Confirm the visitor explicitly accepted analytics consent, not just dismissed the banner. consent?.analytics must be true, not merely non-null, for PostHogProvider to call posthog.init() and begin capturing.

Events will not be sent until consent is granted, even with valid credentials in place. Visit a few pages, then check your PostHog project’s events page to confirm events are arriving.