posthog-upgrade-migration

name	posthog-upgrade-migration
description	Upgrade posthog-js and posthog-node SDKs with breaking change detection. Covers v4 to v5 posthog-node migration (sendFeatureFlags change), posthog-js autocapture API changes, and version-specific gotchas. Trigger: "upgrade posthog", "posthog breaking changes", "update posthog SDK", "posthog version", "posthog migration".
allowed-tools	Read, Write, Edit, Bash(npm:*), Bash(git:*)
version	1.12.0
license	MIT
author	Jeremy Longshore <[e-mail]>
tags	["saas","posthog","api","migration"]
compatibility	Designed for Claude Code, also compatible with Codex and OpenClaw

PostHog Upgrade & Migration

Current State

!npm list posthog-js posthog-node 2>/dev/null | grep posthog || echo 'No PostHog SDK found'

Overview

Upgrade posthog-js and posthog-node SDKs safely. Covers version compatibility, breaking changes between major versions (notably the v5 sendFeatureFlags change in posthog-node), and a systematic upgrade procedure.

Prerequisites

• PostHog SDK currently installed
• Git for branching
• Test suite covering PostHog integration
• Staging environment for validation

Instructions

Step 1: Audit Current Versions

set -euo pipefail
# Check installed versions
echo "=== posthog-js ==="
npm list posthog-js 2>/dev/null || echo "Not installed"
echo "=== posthog-node ==="
npm list posthog-node 2>/dev/null || echo "Not installed"
echo "=== Python posthog ==="
pip3 show posthog 2>/dev/null | grep Version || echo "Not installed"

# Check latest available versions
echo "=== Latest available ==="
npm view posthog-js version 2>/dev/null
npm view posthog-node version 2>/dev/null

Step 2: Review Breaking Changes

posthog-node v5.x Breaking Changes:

// BREAKING: sendFeatureFlags no longer automatic with local evaluation
// Before v5.5.0: feature flags auto-sent with events when using local evaluation
// After v5.5.0: must explicitly set sendFeatureFlags: true

// Before (implicit, worked in v4.x)
posthog.capture({
  distinctId: 'user-1',
  event: 'page_viewed',
  // Feature flags were automatically included
});


posthog.({
  : ,
  : ,
  : , 
});