PostHog integration for JavaScript Web

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/js.md

  - JavaScript web - docs

• references/posthog-js.md

  - PostHog JavaScript web SDK

• 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

• Remember that source code is available in the node_modules directory
• Check package.json for type checking or build scripts to validate changes
• posthog-js is the JavaScript SDK package name
• posthog.init() MUST be called before any other PostHog methods (capture, identify, etc.)
• posthog-js is browser-only — do NOT import it in Node.js or server-side contexts (use posthog-node instead)
• Autocapture is ON by default with posthog-js (tracks clicks, form submissions, pageviews). Do NOT disable autocapture unless the user explicitly requests it.
• NEVER send PII in posthog.capture() event properties — no emails, full names, phone numbers, physical addresses, IP addresses, or user-generated content
• PII belongs in posthog.identify() person properties (email, name, role), NOT in capture() event properties
• Call posthog.identify(userId, { email, name, role }) on login AND on page refresh if the user is already logged in
• Call posthog.reset() on logout to unlink future events from the current user
• For SPAs without a framework router, capture pageviews with posthog.capture($pageview) or use the capture_pageview history_change option in init for History API routing

Identifying users

X-POSTHOG-DISTINCT-ID

X-POSTHOG-SESSION-ID

Error tracking