PostHog integration for Next.js App Router

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

• EXAMPLE.md

  - Next.js App Router example project code

• next-js.md

  - Next.js - docs

• identify-users.md

  - Identify users - docs

• basic-integration-1.0-begin.md

  - PostHog setup - begin

• basic-integration-1.1-edit.md

  - PostHog setup - edit

• basic-integration-1.2-revise.md

  - PostHog setup - revise

• 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

• Never use useEffect() for analytics capture - it's brittle and causes errors
• Prefer event handlers or routing mechanisms to trigger analytics calls
• Add handlers where user actions occur rather than reacting to state changes
• Remember that source code is available in the node_modules directory

Identifying users

posthog.identify()

X-POSTHOG-DISTINCT-ID

X-POSTHOG-SESSION-ID

Error tracking