PostHog integration for Astro (View Transitions)

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

  - Astro (View Transitions) example project code

• references/astro.md

  - Astro - 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

• Always use the is:inline directive on PostHog script tags to prevent Astro from processing them and causing TypeScript errors
• Use PUBLIC_ prefix for client-side environment variables in Astro (e.g., PUBLIC_POSTHOG_PROJECT_TOKEN)
• Create a posthog.astro component in src/components/ for reusable initialization across pages
• Import the PostHog component in a Layout and wrap all pages with that layout
• Wrap PostHog initialization with a window.__posthog_initialized guard to prevent stack overflow during soft navigation
• Set capture_pageview option to 'history_change' for automatic pageview tracking during soft navigation
• Use the astro page-load event instead of just DOMContentLoaded to re-run scripts after soft navigation

Identifying users

X-POSTHOG-DISTINCT-ID

X-POSTHOG-SESSION-ID

Error tracking