PostHog integration for React with TanStack Router (file-based)

Workflow

1. basic-integration-1.0-begin.md

   - PostHog Setup - Begin ← Start here

2. basic-integration-1.1-edit.md

   - PostHog Setup - Edit

3. basic-integration-1.2-revise.md

   - PostHog Setup - Revise

4. basic-integration-1.3-conclude.md

   - PostHog Setup - Conclusion

Reference files

• references/EXAMPLE.md

  - React with TanStack Router (file-based) example project code

• references/tanstack-start.md

  - Tanstack start - docs

• references/identify-users.md

  - Identify users - docs

• references/basic-integration-1.0-begin.md

  - PostHog setup - begin

• references/basic-integration-1.1-edit.md

  - PostHog setup - edit

• references/basic-integration-1.2-revise.md

  - PostHog setup - revise

• references/basic-integration-1.3-conclude.md

  - PostHog setup - conclusion

Key principles

• Environment variables: Always use environment variables for PostHog keys. Never hardcode them.
• Minimal changes: Add PostHog code alongside existing integrations. Don't replace or restructure existing code.
• Match the example: Your implementation should follow the example project's patterns as closely as possible.

Framework guidelines

• For feature flags, use useFeatureFlagEnabled() or useFeatureFlagPayload() hooks - they handle loading states and external sync automatically
• Add analytics capture in event handlers where user actions occur, NOT in useEffect reacting to state changes
• Do NOT use useEffect for data transformation - calculate derived values during render instead
• Do NOT use useEffect to respond to user events - put that logic in the event handler itself
• Do NOT use useEffect to chain state updates - calculate all related updates together in the event handler
• Do NOT use useEffect to notify parent components - call the parent callback alongside setState in the event handler
• To reset component state when a prop changes, pass the prop as the component's key instead of using useEffect
• useEffect is ONLY for synchronizing with external systems (non-React widgets, browser APIs, network subscriptions)
• Use TanStack Router's built-in navigation events for pageview tracking instead of useEffect
• Use PostHogProvider in the root component defined in either the file-based convention (__root.tsx) or code-based convention (wherever createRootRoute() is called) so all child routes have access to the PostHog client

Identifying users

X-POSTHOG-DISTINCT-ID

X-POSTHOG-SESSION-ID

Error tracking