AgentSkillsCN

api-analytics-setup-posthog

PostHog 分析与功能标记的配置

SKILL.md
--- frontmatter
name: api-analytics-setup-posthog
description: PostHog analytics and feature flags setup

PostHog Analytics & Feature Flags Setup

Quick Guide: One-time setup for PostHog in Next.js App Router monorepo. Covers posthog-js client provider, posthog-node server client, environment variables, and Vercel deployment. PostHog handles both analytics AND feature flags with a generous free tier (1M events + 1M flag requests/month).

<critical_requirements>

CRITICAL: Before Using This Skill

All code must follow project conventions in CLAUDE.md (kebab-case, named exports, import ordering, import type, named constants)

(You MUST use NEXT_PUBLIC_ prefix for client-side PostHog environment variables)

(You MUST create PostHogProvider as a 'use client' component - posthog-js requires browser APIs)

(You MUST call posthog.shutdown() or posthog.flush() after server-side event capture to prevent lost events)

(You MUST use defaults: '2025-11-30' or capture_pageview: 'history_change' for automatic SPA page tracking)

(You MUST use a single PostHog organization for all monorepo apps - projects are usage-based, not per-project pricing)

</critical_requirements>

Auto-detection: PostHog setup, posthog-js, posthog-node, PostHogProvider, analytics setup, feature flags setup, event tracking setup, NEXT_PUBLIC_POSTHOG_KEY

When to use:

  • •Initial PostHog setup in a Next.js App Router project
  • •Configuring PostHogProvider for client-side analytics
  • •Setting up posthog-node for server-side/API route event capture
  • •Deploying to Vercel with PostHog environment variables

When NOT to use:

  • •Event tracking patterns (use backend/analytics.md for that)
  • •Feature flag usage patterns (use backend/feature-flags.md for that)
  • •Complex multi-environment setups with separate staging/production projects

Key patterns covered:

  • •PostHog project creation (single org for monorepo)
  • •Client-side setup with PostHogProvider
  • •Server-side setup with posthog-node
  • •Environment variables configuration
  • •Vercel deployment integration
  • •Initial dashboard recommendations

Detailed Resources:

  • •For code examples, see examples/:
    • •core.md - Provider setup, layout integration, user identification
    • •server.md - Server client singleton, API routes, Hono middleware
    • •deployment.md - Environment variables, Vercel deployment
  • •For decision frameworks and anti-patterns, see reference.md
<philosophy>

Philosophy

PostHog is a product analytics + feature flags platform that consolidates multiple tools into one. It's open-source, can be self-hosted, and has a generous free tier. For solo developers and small teams, PostHog eliminates the need for separate analytics (Mixpanel/Amplitude) and feature flag (LaunchDarkly) services.

Core principles:

  1. •One platform for analytics + feature flags - Reduces tool sprawl and cost
  2. •Usage-based pricing - Pay for what you use, not per-project
  3. •Autocapture by default - Automatic event tracking reduces manual instrumentation
  4. •Server and client SDKs - Full coverage for SSR and client-side apps

When to use PostHog:

  • •Need both analytics and feature flags in one platform
  • •Want generous free tier (1M events + 1M flag requests/month)
  • •Prefer open-source with self-host option
  • •Building product analytics (funnels, retention, sessions)

When NOT to use PostHog:

  • •Need advanced A/B testing with statistical rigor (use Statsig)
  • •Require real-time event streaming (use Segment)
  • •Need complex user journey mapping (use Amplitude)
  • •Already have established analytics + flag tools
</philosophy>
<patterns>

Core Patterns

Pattern 1: PostHog Project Setup

Create a single PostHog organization for your monorepo. You can either use one project for all apps or create separate projects per app.

Organization Structure

code
PostHog Organization: "Your Company"
├── Project: "Main App" (or separate per app)
│   ├── API Key: phc_xxx
│   └── Host: https://us.i.posthog.com (or eu.i.posthog.com)

Getting API Keys

  1. •Sign up at posthog.com
  2. •Create a new organization (or use existing)
  3. •Create a project for your app(s)
  4. •Copy the Project API Key from Settings > Project > API Keys
bash
# Example API key format
phc_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Why good: Single organization pools billing across all projects, 6 projects included on paid tier, usage-based pricing means you're not penalized for multiple apps

Pattern 2: Client-Side Setup

Install dependencies and configure for Next.js App Router.

Installation

bash
# Install client-side SDK
bun add posthog-js

Environment Variables

bash
# apps/client-next/.env.local

# PostHog Configuration
NEXT_PUBLIC_POSTHOG_KEY=phc_your_project_api_key_here
NEXT_PUBLIC_POSTHOG_HOST=https://us.i.posthog.com

Setup Options

Next.js 15.3+: Use instrumentation-client.js (simpler, recommended) Next.js < 15.3: Use PostHogProvider component (traditional approach)

See examples/core.md for both approaches with full implementation examples.

Why good: defaults: "2025-11-30" enables automatic SPA page/leave tracking, person_profiles: "identified_only" reduces event costs, debug mode in development aids troubleshooting

Pattern 3: Server-Side Setup with posthog-node

Install and configure the Node.js SDK for server-side event capture in API routes and Hono middleware.

Installation

bash
# Install server-side SDK
bun add posthog-node

Environment Variables

bash
# apps/client-next/.env.local (or apps/server/.env.local)

# Server-side PostHog (no NEXT_PUBLIC_ prefix needed)
POSTHOG_API_KEY=phc_your_project_api_key_here
POSTHOG_HOST=https://us.i.posthog.com

Create a server client singleton for reuse across API routes. See examples/server.md for the full implementation including API route and Hono middleware examples.

Serverless Options

Option 1: Use captureImmediate() - simplest, awaits HTTP request directly Option 2: Use capture() + await flush() - batched, requires explicit flush

Why good: Singleton prevents multiple client instances, flushInterval/flushAt configure batching, shutdown function for graceful cleanup, captureImmediate for simple serverless usage

</patterns>

<critical_reminders>

CRITICAL REMINDERS

All code must follow project conventions in CLAUDE.md (kebab-case, named exports, import ordering, import type, named constants)

(You MUST use NEXT_PUBLIC_ prefix for client-side PostHog environment variables)

(You MUST create PostHogProvider as a 'use client' component - posthog-js requires browser APIs)

(You MUST call posthog.shutdown() or posthog.flush() after server-side event capture to prevent lost events)

(You MUST use defaults: '2025-11-30' or capture_pageview: 'history_change' for automatic SPA page tracking)

(You MUST use a single PostHog organization for all monorepo apps - projects are usage-based, not per-project pricing)

Failure to follow these rules will cause lost analytics events, broken tracking, or security vulnerabilities.

</critical_reminders>

Sources