PostHog Implementation (Next.js 2025) Skill

PostHog Implementation (Next.js 2025)

What This Skill Covers

Analytics - Event tracking, user identification, group analytics
Feature Flags - Boolean flags, multivariate, A/B testing
Session Replay - Recording setup, privacy controls
Analytics Queries - HogQL, Query API, extracting insights
Reporting - Funnel analysis, retention, error reports, SEO

Reference Files

Load these files as needed based on the task:

| File | Load When | |------|-----------| | references/nextjs-implementation.md | Setting up PostHog from scratch, detailed code patterns | | references/event-taxonomy.md | Designing event naming conventions, property patterns | | references/feature-flags.md | Implementing feature flags, A/B tests, experiments |

Quick Setup

Environment Variables

# .env.local
NEXT_PUBLIC_POSTHOG_KEY=phc_your_project_key
NEXT_PUBLIC_POSTHOG_HOST=https://us.i.posthog.com

Reverse Proxy Setup (RECOMMENDED)

IMPORTANT: Ad blockers block direct PostHog requests. Use a reverse proxy to route through your own domain.

Add to next.config.ts:

const nextConfig: NextConfig = {
  async rewrites() {
    return [
      {
        source: "/ingest/static/:path*",
        destination: "https://us-assets.i.posthog.com/static/:path*",
      },
      {
        source: "/ingest/:path*",
        destination: "https://us.i.posthog.com/:path*",
      },
      {
        source: "/ingest/decide",
        destination: "https://us.i.posthog.com/decide",
      },
    ];
  },
  // ... rest of config
};

Also update CSP headers to allow PostHog connections:

"connect-src 'self' ... https://*.posthog.com https://us.i.posthog.com https://us-assets.i.posthog.com",

PostHog Provider (Client-Side)

Create app/providers.tsx:

'use client'

import posthog from 'posthog-js'
import { PostHogProvider as PHProvider } from 'posthog-js/react'
import { useEffect } from 'react'

export function PostHogProvider({ children }: { children: React.ReactNode }) {
  useEffect(() => {
    posthog.init(process.env.NEXT_PUBLIC_POSTHOG_KEY!, {
      // Use reverse proxy to bypass ad blockers
      api_host: '/ingest',
      ui_host: 'https://us.i.posthog.com',
      defaults: '2025-05-24',
      capture_pageview: false, // We handle manually for accurate funnels
      person_profiles: 'identified_only',
    })
  }, [])

  return <PHProvider client={posthog}>{children}</PHProvider>
}

PostHog Server Client

Create lib/posthog-server.ts:

import { PostHog } from 'posthog-node'

let posthogClient: PostHog | null = null

export function getPostHogServer(): PostHog {
  if (!posthogClient) {
    posthogClient = new PostHog(process.env.NEXT_PUBLIC_POSTHOG_KEY!, {
      host: process.env.NEXT_PUBLIC_POSTHOG_HOST || 'https://us.i.posthog.com',
      flushAt: 1,
      flushInterval: 0,
    })
  }
  return posthogClient
}

Event Naming Convention

| Pattern | Example | Use Case | |---------|---------|----------| | category:object_action | signup:form_submit | User actions | | feature:action | dashboard:project_create | Feature usage | | lifecycle:event | user:signup_complete | User journey |

Property Naming

| Pattern | Example | Type | |---------|---------|------| | object_adjective | user_id, item_price | Any | | is_ prefix | is_subscribed, is_first_time | Boolean | | has_ prefix | has_seen_onboarding | Boolean | | _count suffix | item_count, generation_count | Number | | _at suffix | created_at, upgraded_at | Timestamp |

Server vs Client Decision Tree

Where to track?
├── User action in browser → Client (posthog-js)
├── API route / webhook → Server (posthog-node)
├── Server Component render → Server (posthog-node)
├── Need 100% accuracy → Server (no ad blockers)
└── Real-time UI feedback → Client (posthog-js)

Common Pitfalls

| Pitfall | Solution | |---------|----------| | Ad blockers blocking PostHog | Use reverse proxy (/ingest → PostHog). See setup above | | Events not appearing | Check ad blockers, verify API key, use reverse proxy | | Duplicate pageviews | Use capture_pageview: false and handle manually | | Feature flag flicker | Bootstrap flags via middleware | | Missing user data | Call identify() BEFORE $pageview for accurate funnels | | Inconsistent naming | Use category:object_action pattern | | Failed to fetch errors | Browser extension blocking - use reverse proxy | | 503 from us-assets.i.posthog.com | Ad blocker injecting fake response - use reverse proxy |

Clarifying Questions

Before implementing PostHog, ask:

What events are most important to track? (signups, conversions, feature usage)
Do you need server-side tracking? (for accuracy, API routes)
Are you running A/B tests? (need experiment setup)
What's your auth provider? (for user identification pattern)
Do you need session replay? (privacy considerations)

Agent Skills: PostHog Implementation (Next.js 2025)

Install this agent skill to your local

Skill Files