feat(registry): add PostHog analytics script (#568)

Co-authored-by: Claude Opus 4.5 <[email protected]>

Author: harlan-zw

docs/content/scripts/analytics/posthog.md

@@ -0,0 +1,192 @@
+---
+title: PostHog
+description: Use PostHog in your Nuxt app.
+links:
+- label: Source
+  icon: i-simple-icons-github
+  to: https://github.com/nuxt/scripts/blob/main/src/runtime/registry/posthog.ts
+  size: xs
+---
+
+[PostHog](https://posthog.com) is an open-source product analytics platform that provides analytics, session replay, feature flags, A/B testing, and more.
+
+Nuxt Scripts provides a registry script composable `useScriptPostHog` to easily integrate PostHog in your Nuxt app.
+
+## Installation
+
+You must install the `posthog-js` dependency:
+
+```bash
+pnpm add posthog-js
+```
+
+### Nuxt Config Setup
+
+::code-group
+
+```ts [Always enabled]
+export default defineNuxtConfig({
+  scripts: {
+    registry: {
+      posthog: {
+        apiKey: 'YOUR_API_KEY'
+      }
+    }
+  }
+})
+```
+
+```ts [Production only]
+export default defineNuxtConfig({
+  $production: {
+    scripts: {
+      registry: {
+        posthog: {
+          apiKey: 'YOUR_API_KEY'
+        }
+      }
+    }
+  }
+})
+```
+
+::
+
+#### With Environment Variables
+
+```ts [nuxt.config.ts]
+export default defineNuxtConfig({
+  scripts: {
+    registry: {
+      posthog: true,
+    }
+  },
+  runtimeConfig: {
+    public: {
+      scripts: {
+        posthog: {
+          apiKey: '', // NUXT_PUBLIC_SCRIPTS_POSTHOG_API_KEY
+        },
+      },
+    },
+  },
+})
+```
+
+## useScriptPostHog
+
+```ts
+const { proxy } = useScriptPostHog({
+  apiKey: 'YOUR_API_KEY'
+})
+
+// Capture an event
+proxy.posthog.capture('button_clicked', {
+  button_name: 'signup'
+})
+```
+
+Please follow the [Registry Scripts](/docs/guides/registry-scripts) guide to learn more about advanced usage.
+
+### PostHogApi
+
+```ts
+import type { PostHog } from 'posthog-js'
+
+export interface PostHogApi {
+  posthog: PostHog
+}
+```
+
+### Config Schema
+
+```ts
+export const PostHogOptions = object({
+  apiKey: string(),
+  region: optional(union([literal('us'), literal('eu')])),
+  autocapture: optional(boolean()),
+  capturePageview: optional(boolean()),
+  capturePageleave: optional(boolean()),
+  disableSessionRecording: optional(boolean()),
+  config: optional(record(string(), any())), // Full PostHogConfig passthrough
+})
+```
+
+## Example
+
+Using PostHog to track a signup event.
+
+::code-group
+
+```vue [SignupForm.vue]
+<script setup lang="ts">
+const { proxy } = useScriptPostHog()
+
+function onSignup(email: string) {
+  proxy.posthog.identify(email, {
+    email,
+    signup_date: new Date().toISOString()
+  })
+  proxy.posthog.capture('user_signed_up')
+}
+</script>
+
+<template>
+  <form @submit.prevent="onSignup(email)">
+    <input v-model="email" type="email" />
+    <button type="submit">Sign Up</button>
+  </form>
+</template>
+```
+
+::
+
+## EU Hosting
+
+To use PostHog's EU cloud:
+
+```ts
+export default defineNuxtConfig({
+  scripts: {
+    registry: {
+      posthog: {
+        apiKey: 'YOUR_API_KEY',
+        region: 'eu'
+      }
+    }
+  }
+})
+```
+
+## Feature Flags
+
+Feature flag methods return values, so you need to wait for PostHog to load first:
+
+```ts
+const { onLoaded } = useScriptPostHog()
+
+onLoaded(({ posthog }) => {
+  // Check a feature flag
+  if (posthog.isFeatureEnabled('new-dashboard')) {
+    // Show new dashboard
+  }
+
+  // Get flag payload
+  const payload = posthog.getFeatureFlagPayload('experiment-config')
+})
+```
+
+## Disabling Session Recording
+
+```ts
+export default defineNuxtConfig({
+  scripts: {
+    registry: {
+      posthog: {
+        apiKey: 'YOUR_API_KEY',
+        disableSessionRecording: true
+      }
+    }
+  }
+})
+```

package.json

@@ -68,7 +68,8 @@
       "esbuild",
       "unimport",
       "#nuxt-scripts/types",
-      "#nuxt-scripts-validator"
+      "#nuxt-scripts-validator",
+      "posthog-js"
     ]
   },
   "peerDependencies": {
@@ -78,7 +79,8 @@
     "@types/google.maps": "^3.58.1",
     "@types/vimeo__player": "^2.18.3",
     "@types/youtube": "^0.1.0",
-    "@unhead/vue": "^2.0.3"
+    "@unhead/vue": "^2.0.3",
+    "posthog-js": "^1.0.0"
   },
   "peerDependenciesMeta": {
     "@googlemaps/markerclusterer": {
@@ -98,6 +100,9 @@
     },
     "@types/youtube": {
       "optional": true
+    },
+    "posthog-js": {
+      "optional": true
     }
   },
   "dependencies": {
@@ -126,6 +131,7 @@
     "@nuxt/scripts": "workspace:*",
     "@nuxt/test-utils": "3.19.2",
     "@paypal/paypal-js": "^9.1.0",
+    "posthog-js": "^1.222.0",
     "@types/semver": "^7.7.1",
     "@typescript-eslint/typescript-estree": "^8.53.0",
     "@vue/test-utils": "^2.4.6",

playground/pages/index.vue

@@ -20,6 +20,7 @@ function getPlaygroundPath(script: any): string | null {
     'cloudflare-web-analytics': '/third-parties/cloudflare-web-analytics/nuxt-scripts',
     'fathom-analytics': '/third-parties/fathom-analytics',
     'plausible-analytics': '/third-parties/plausible-analytics',
+    'posthog': '/third-parties/posthog/nuxt-scripts',
     'matomo-analytics': '/third-parties/matomo-analytics/nuxt-scripts',
     'rybbit-analytics': '/third-parties/rybbit-analytics',
     'databuddy-analytics': '/third-parties/databuddy-analytics',

playground/pages/third-parties/posthog/nuxt-scripts.vue

@@ -0,0 +1,42 @@
+<script lang="ts" setup>
+import { useHead, useScriptPostHog } from '#imports'
+
+useHead({
+  title: 'PostHog',
+})
+
+const { status, proxy } = useScriptPostHog({
+  apiKey: 'phc_YOUR_API_KEY',
+})
+
+function captureEvent() {
+  proxy.posthog.capture('button_clicked', {
+    button_name: 'test',
+  })
+}
+
+function identifyUser() {
+  proxy.posthog.identify('[email protected]', {
+    email: '[email protected]',
+    name: 'Test User',
+  })
+}
+</script>
+
+<template>
+  <div>
+    <ClientOnly>
+      <div>
+        status: {{ status }}
+      </div>
+      <div class="flex gap-2 mt-4">
+        <UButton @click="captureEvent">
+          Capture Event
+        </UButton>
+        <UButton @click="identifyUser">
+          Identify User
+        </UButton>
+      </div>
+    </ClientOnly>
+  </div>
+</template>