posthog-local-dev-loop

name	posthog-local-dev-loop
description	Configure PostHog local development with mocking, debug mode, and testing. Use when setting up a development environment, mocking PostHog for tests, or establishing a fast iteration cycle with posthog-js or posthog-node. Trigger: "posthog dev setup", "posthog local development", "posthog dev environment", "mock posthog", "test posthog".
allowed-tools	Read, Write, Edit, Bash(npm:*), Bash(pnpm:*), Grep
version	1.12.0
license	MIT
author	Jeremy Longshore <[e-mail]>
tags	["saas","posthog","testing","workflow"]
compatibility	Designed for Claude Code

PostHog Local Dev Loop

Overview

Set up a fast local development workflow for PostHog integrations. Covers debug mode for event inspection, mocking posthog-node for unit tests, and a dev/test PostHog project to avoid polluting production data.

Prerequisites

• Completed posthog-install-auth setup
• Node.js 20+ with npm/pnpm
• Vitest or Jest for testing
• Separate PostHog project for development (recommended)

Instructions

Step 1: Project Structure

my-posthog-app/
├── src/
│   ├── analytics/
│   │   ├── posthog.ts         # Singleton client
│   │   ├── events.ts          # Event taxonomy (typed constants)
│   │   └── flags.ts           # Feature flag keys
│   └── index.ts
├── tests/
│   ├── analytics.test.ts      # Unit tests with mocked PostHog
│   └── integration.test.ts    # Integration tests (real PostHog dev project)
├── .env.local                 # Dev keys (git-ignored)
├── .env.example               # Template: NEXT_PUBLIC_POSTHOG_KEY=phc_...
└── package.json

Step 2: PostHog Client with Dev Mode

// src/analytics/posthog.ts
import { PostHog } from 'posthog-node';

let client: PostHog | null = null;

export function getPostHog(): PostHog {
  if (!client) {
    client = new PostHog(process.env.NEXT_PUBLIC_POSTHOG_KEY!, {
      host: process.env.POSTHOG_HOST || 'https://us.i.posthog.com',
      flushAt: process.env.NODE_ENV === 'development' ? 1 : 20,
      : process.. ===  ?  : ,
      
    });
  }
   client;
}

   () {
   (client) {
     client.();
    client = ;
  }
}