feat(posthog): support proxy mode

Fixes #591

Author: harlan-zw

docs/content/scripts/analytics/posthog.md

@@ -104,6 +104,7 @@ export interface PostHogApi {
 export const PostHogOptions = object({
   apiKey: string(),
   region: optional(union([literal('us'), literal('eu')])),
+  apiHost: optional(string()), // Custom API host URL (e.g. '/ph' for reverse proxy)
   autocapture: optional(boolean()),
   capturePageview: optional(boolean()),
   capturePageleave: optional(boolean()),
@@ -158,6 +159,47 @@ export default defineNuxtConfig({
 })
 ```
 
+## First-Party Proxy
+
+When [first-party mode](/docs/guides/first-party) is enabled, PostHog requests are automatically proxied through your own server. This improves event capture reliability by avoiding ad blockers.
+
+No additional configuration is needed — the module automatically sets `apiHost` to route through your server's proxy endpoint:
+
+```ts
+export default defineNuxtConfig({
+  scripts: {
+    firstParty: true, // enabled by default
+    registry: {
+      posthog: {
+        apiKey: 'YOUR_API_KEY',
+        // apiHost is auto-set to '/_proxy/ph' (or '/_proxy/ph-eu' for EU region)
+      }
+    }
+  }
+})
+```
+
+The proxy handles both API requests and static assets (e.g. session recording SDK), routing them to the correct PostHog endpoints.
+
+## Custom API Host
+
+To use a custom reverse proxy or self-hosted PostHog instance, set `apiHost` directly:
+
+```ts
+export default defineNuxtConfig({
+  scripts: {
+    registry: {
+      posthog: {
+        apiKey: 'YOUR_API_KEY',
+        apiHost: '/my-proxy'
+      }
+    }
+  }
+})
+```
+
+The `apiHost` option accepts any URL or relative path, overriding both the `region` default and the first-party proxy auto-configuration. For additional PostHog SDK options like `ui_host`, use the `config` passthrough.
+
 ## Feature Flags
 
 Feature flag methods return values, so you need to wait for PostHog to load first:

src/module.ts

@@ -569,6 +569,18 @@ export default defineNuxtPlugin({
           }
         }
 
+        // Auto-inject apiHost for PostHog when first-party proxy is enabled
+        // PostHog uses NPM mode so URL rewrites don't apply - we set api_host via config instead
+        if (config.registry?.posthog && typeof config.registry.posthog === 'object') {
+          const phConfig = config.registry.posthog as Record<string, any>
+          if (!phConfig.apiHost) {
+            const region = phConfig.region || 'us'
+            phConfig.apiHost = region === 'eu'
+              ? `${firstPartyCollectPrefix}/ph-eu`
+              : `${firstPartyCollectPrefix}/ph`
+          }
+        }
+
         // Warn about scripts that don't support first-party mode
         if (unsupportedScripts.length && nuxt.options.dev) {
           logger.warn(

src/proxy-configs.ts

@@ -145,6 +145,18 @@ function buildProxyConfig(collectPrefix: string) {
       },
     },
 
+    posthog: {
+      // No rewrites needed - PostHog uses NPM mode, SDK URLs are set via api_host config
+      routes: {
+        // US region
+        [`${collectPrefix}/ph/static/**`]: { proxy: 'https://us-assets.i.posthog.com/static/**' },
+        [`${collectPrefix}/ph/**`]: { proxy: 'https://us.i.posthog.com/**' },
+        // EU region
+        [`${collectPrefix}/ph-eu/static/**`]: { proxy: 'https://eu-assets.i.posthog.com/static/**' },
+        [`${collectPrefix}/ph-eu/**`]: { proxy: 'https://eu.i.posthog.com/**' },
+      },
+    },
+
     hotjar: {
       rewrite: [
         // Static assets

src/registry.ts

@@ -43,6 +43,7 @@ export async function registry(resolve?: (path: string, opts?: ResolvePathOption
     {
       label: 'PostHog',
       src: false,
+      proxy: 'posthog',
       scriptBundling: false,
       category: 'analytics',
       logo: `<svg xmlns="http://www.w3.org/2000/svg" width="32" height="32" viewBox="0 0 128 128"><path fill="#1d4aff" d="M0 .52v32.15l31.79 31.78V32.3L0 .52zm32.3 32.15v32.15l31.78 31.78V64.45L32.3 32.67zM0 64.97v32.15l31.79 31.78V96.75L0 64.97zm64.6-32.3v32.15l31.78 31.78V64.45L64.6 32.67zm31.78 31.78v32.15l31.78 31.78V96.23l-31.78-31.78zm-64.08.52v32.15l31.78 31.78V96.75L32.3 64.97zM64.6 .52v32.15l31.78 31.78V32.3L64.6 .52zm0 64.45v32.15l31.78 31.78V96.75L64.6 64.97z"/></svg>`,

src/runtime/registry/posthog.ts

@@ -7,6 +7,7 @@ import { logger } from '../logger'
 export const PostHogOptions = object({
   apiKey: string(),
   region: optional(union([literal('us'), literal('eu')])),
+  apiHost: optional(string()),
   autocapture: optional(boolean()),
   capturePageview: optional(boolean()),
   capturePageleave: optional(boolean()),
@@ -74,17 +75,12 @@ export function useScriptPostHog<T extends PostHogApi>(_options?: PostHogInput)
           }
 
           const region = options?.region || 'us'
-          const apiHost = region === 'eu'
+          const apiHost = options?.apiHost || (region === 'eu'
             ? 'https://eu.i.posthog.com'
-            : 'https://us.i.posthog.com'
-
-          // eslint-disable-next-line no-console
-          console.log('[PostHog] Starting dynamic import of posthog-js...')
+            : 'https://us.i.posthog.com')
 
           window.__posthogInitPromise = import('posthog-js')
             .then(({ default: posthog }) => {
-              // eslint-disable-next-line no-console
-              console.log('[PostHog] posthog-js imported successfully')
               const config: Partial<PostHogConfig> = {
                 api_host: apiHost,
                 ...options?.config as Partial<PostHogConfig>,
@@ -98,35 +94,23 @@ export function useScriptPostHog<T extends PostHogApi>(_options?: PostHogInput)
               if (typeof options?.disableSessionRecording === 'boolean')
                 config.disable_session_recording = options.disableSessionRecording
 
-              // eslint-disable-next-line no-console
-              console.log('[PostHog] Calling posthog.init with apiKey:', options.apiKey, 'config:', config)
               const instance = posthog.init(options.apiKey, config)
               if (!instance) {
                 logger.error('PostHog init returned undefined - initialization failed')
-                // Clear queue on init failure to prevent memory leak
                 delete window._posthogQueue
                 return undefined
               }
 
-              // eslint-disable-next-line no-console
-              console.log('[PostHog] posthog.init succeeded, instance:', instance)
               window.posthog = instance
               // Flush queued calls now that PostHog is ready
               if (window._posthogQueue && window._posthogQueue.length > 0) {
-                // eslint-disable-next-line no-console
-                console.log('[PostHog] Flushing', window._posthogQueue.length, 'queued calls')
                 window._posthogQueue.forEach(q => (window.posthog as any)[q.prop]?.(...q.args))
                 delete window._posthogQueue
               }
-              // eslint-disable-next-line no-console
-              console.log('[PostHog] Initialization complete!')
               return window.posthog
             })
             .catch((e) => {
               logger.error('Failed to load posthog-js:', e)
-
-              console.error('[PostHog] Import/init error:', e)
-              // Clear queue on error to prevent memory leak
               delete window._posthogQueue
               return undefined
             })