Analyze, plan, and execute PostHog SDK upgrades with breaking change detection.
Use when upgrading PostHog SDK versions, detecting deprecations,
or migrating to new API versions.
Trigger with phrases like "upgrade posthog", "posthog migration",
"posthog breaking changes", "update posthog SDK", "analyze posthog version".
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
});
// After (v5.5.0+, explicit required)
posthog.capture({
distinctId: 'user-1',
event: 'page_viewed',
sendFeatureFlags: true, // Must be explicit now
});
posthog-js Recent Changes:
// Autocapture configuration moved to object format
// Before:
posthog.init('phc_...', { autocapture: true });
// Current: Fine-grained autocapture control
posthog.init('phc_...', {
autocapture: {
dom_event_allowlist: ['click', 'submit'],
element_allowlist: ['a', 'button', 'form', 'input'],
css_selector_allowlist: ['.track-click'],
url_ignorelist: ['/health', '/api/internal'],
},
});
// before_send replaces older event filtering approaches
posthog.init('phc_...', {
before_send: (event) => {
// Return null to drop event, or modified event
if (event.event === '$pageview' && event.properties?.$current_url?.includes('/admin')) {
return null; // Don't track admin pages
}
return event;
},
});
Step 3: Upgrade Procedure
set -euo pipefail
# Create upgrade branch
git checkout -b upgrade/posthog-sdks
# Upgrade posthog-node
npm install posthog-node@latest
# Check for type errors
npx tsc --noEmit 2>&1 | grep -i posthog || echo "No PostHog type errors"
# Upgrade posthog-js
npm install posthog-js@latest
# Check for type errors
npx tsc --noEmit 2>&1 | grep -i posthog || echo "No PostHog type errors"
# Run tests
npm test
# If Python
pip install --upgrade posthog
Step 4: Search for Deprecated Patterns
set -euo pipefail
# Find files using PostHog
grep -rn "posthog\|PostHog" --include="*.ts" --include="*.tsx" --include="*.js" src/ | \
grep -v node_modules | grep -v ".d.ts"
# Check for patterns that may need updating
echo "=== Checking for deprecated patterns ==="
# Old import style (posthog-node v3 and earlier)
grep -rn "from 'posthog-node'" --include="*.ts" src/ && echo "Import style: current" || true
# Direct API key in code (should be env var)
grep -rn "phc_\|phx_" --include="*.ts" --include="*.tsx" src/ && \
echo "WARNING: Hardcoded API key found" || echo "No hardcoded keys"
# Check for sendFeatureFlags usage
grep -rn "sendFeatureFlags" --include="*.ts" src/ || \
echo "NOTE: No explicit sendFeatureFlags — verify if needed after v5.5.0 upgrade"
