feat(registry): add PostHog analytics script

[harlan-zw]

🔗 Linked issue

❓ Type of change

• 📖 Documentation (updates to the documentation or readme)
• 🐞 Bug fix (a non-breaking change that fixes an issue)
• 👌 Enhancement (improving an existing functionality)
• ✨ New feature (a non-breaking change that adds functionality)
• 🧹 Chore (updates to the build process or auxiliary tools and libraries)
• ⚠️ Breaking change (fix or feature that would cause existing functionality to change)

📚 Description

• Add useScriptPostHog composable using npm package pattern
• Add posthog-js as optional peer dependency
• Support US/EU region configuration
• Add common config options (autocapture, capturePageview, etc.)
• Add documentation with usage examples

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Review	Updated (UTC)
scripts-docs	Ready	Preview, Comment	Jan 14, 2026 3:10pm
scripts-playground	Ready	Preview, Comment	Jan 14, 2026 3:10pm

[pkg-pr-new]

Open in StackBlitz

npm i https://pkg.pr.new/nuxt/scripts/@nuxt/scripts@568

commit: c019cb7

[vercel]

The use() function checks if window.posthog exists synchronously, but the clientInit function starts an asynchronous import operation that completes later. If use() is called before the async initialization finishes, it will return undefined, causing proxy.posthog to be undefined.

View Details

📝 Patch Details

diff --git a/src/runtime/registry/posthog.ts b/src/runtime/registry/posthog.ts
index b7b5e87..bc738b6 100644
--- a/src/runtime/registry/posthog.ts
+++ b/src/runtime/registry/posthog.ts
@@ -27,6 +27,7 @@ declare global {
 }
 
 export function useScriptPostHog<T extends PostHogApi>(_options?: PostHogInput) {
+  let readyPromise: Promise<PostHog | undefined> = Promise.resolve(undefined)
   return useRegistryScript<T, typeof PostHogOptions>('posthog', options => ({
     scriptInput: {
       src: '', // No external script - using npm package
@@ -34,7 +35,7 @@ export function useScriptPostHog<T extends PostHogApi>(_options?: PostHogInput)
     schema: import.meta.dev ? PostHogOptions : undefined,
     scriptOptions: {
       use() {
-        return window.posthog ? { posthog: window.posthog } : undefined
+        return { posthog: window.posthog! }
       },
     },
     clientInit: import.meta.server
@@ -44,6 +45,30 @@ export function useScriptPostHog<T extends PostHogApi>(_options?: PostHogInput)
           if (window.__posthogInitPromise || window.posthog)
             return
 
+          // Initialize a queue/stub synchronously to avoid race conditions
+          // This ensures use() always returns a valid object
+          const queue: Array<{ method: string, args: any[] }> = []
+          const stub: any = new Proxy({}, {
+            get: (target, method: string | symbol) => {
+              if (typeof method !== 'string')
+                return undefined
+              return (...args: any[]) => {
+                // Queue the call if the real posthog hasn't loaded yet
+                if (!window.posthog || window.posthog === stub) {
+                  queue.push({ method, args })
+                  return
+                }
+                // Once loaded, call the real method
+                const fn = (window.posthog as any)[method]
+                if (typeof fn === 'function') {
+                  return fn.apply(window.posthog, args)
+                }
+              }
+            },
+          })
+
+          window.posthog = stub as any as PostHog
+
           const region = options?.region || 'us'
           const apiHost = region === 'eu'
             ? 'https://eu.i.posthog.com'
@@ -64,8 +89,22 @@ export function useScriptPostHog<T extends PostHogApi>(_options?: PostHogInput)
               config.disable_session_recording = options.disableSessionRecording
 
             window.posthog = posthog.init(options?.apiKey || '', config)
+
+            // Replay queued calls
+            for (const { method, args } of queue) {
+              const fn = (window.posthog as any)[method]
+              if (typeof fn === 'function') {
+                fn.apply(window.posthog, args)
+              }
+            }
+
             return window.posthog
+          }).then((result) => {
+            readyPromise = Promise.resolve(result)
+            return result
           })
+
+          readyPromise = window.__posthogInitPromise
         },
   }), _options)
 }

Analysis

Race condition between async initialization and synchronous use() in PostHog integration

What fails: The useScriptPostHog() composable's use() function returns undefined if called before the asynchronous import('posthog-js') completes, preventing the proxy mechanism from functioning correctly.

How to reproduce:

// In a Vue component:
const { proxy } = useScriptPostHog({ apiKey: 'test-key' })

// Immediately call PostHog method
proxy.posthog.capture('event') // Fails with "Cannot read properties of undefined"

The issue occurs because:

1. clientInit() starts an async import('posthog-js') operation that sets window.posthog later
2. use() is called synchronously by the proxy mechanism to get the API reference
3. If use() is called before the import completes, window.posthog doesn't exist yet
4. use() returns undefined, breaking the proxy system which relies on a valid object reference

Result: Calls to proxy methods fail if made before async initialization completes. The proxy system from @unhead/vue relies on the use() function returning a valid object reference to queue calls.

Expected behavior: The use() function should always return a valid object, similar to other analytics scripts like Crisp (see src/runtime/registry/crisp.ts) which initialize a stub synchronously.

Fix: Initialize window.posthog as a queuing stub synchronously in clientInit(), then replace it with the real PostHog instance once the async import completes. Calls made before initialization are queued and replayed after the library loads.

[vercel]

Suggested change

	import { watch, onMounted } from 'vue'
	import { watch, onMounted, ref } from 'vue'
	import { useScriptPostHog } from '#imports'

The file uses useScriptPostHog without explicitly importing it, which is inconsistent with the codebase pattern used in other test fixtures.

View Details

Analysis

Missing imports in test/fixtures/basic/pages/tpc/posthog.vue

What fails: The component uses useScriptPostHog and ref without explicitly importing them, which is inconsistent with established patterns in other test fixtures in the same directory

How to reproduce:

# Check other test fixtures in the same directory
cat test/fixtures/basic/pages/tpc/ga.vue         # Imports from '#imports'
cat test/fixtures/basic/pages/tpc/recaptcha.vue  # Imports from '#imports'
cat test/fixtures/basic/pages/tpc/posthog.vue    # Missing imports (before fix)

Result: While Nuxt's auto-imports feature allows the code to compile and run, the pattern is inconsistent with:

• ga.vue which imports useScriptGoogleAnalytics from '#imports'
• recaptcha.vue which imports useScriptGoogleRecaptcha from '#imports'

The file also uses ref without importing it, though other files that use ref explicitly import it either from 'vue' or '#imports'.

Expected: Imports should be explicit and consistent with the established pattern across the test fixtures, as documented in the Nuxt style guide

Fix applied: Added explicit imports:

• ref from 'vue' (to match Vue's composition API pattern)
• useScriptPostHog from '#imports' (to match other test fixtures in the same directory)