PostHog

PostHog 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.

export default defineNuxtConfig({
  scripts: {
    registry: {
      posthog: {
        apiKey: 'phc_xxxxxxxxxxxxxxxxx',
        trigger: 'onNuxtReady',
      }
    }
  }
})

const { proxy } = useScriptPostHog()

proxy.posthog.capture('conversion', { value: 1 })

export default defineNuxtConfig({
  scripts: {
    // ✅ First-party mode: proxied
    registry: {
      posthog: {
        apiKey: 'phc_xxxxxxxxxxxxxxxxx',
        trigger: 'onNuxtReady',
      },
    },
  },
})

<script setup lang="ts">
const { proxy } = useScriptPostHog()

// noop in development, ssr
// just works in production, client
function handleAction() {
  proxy.posthog.capture('conversion', { value: 1 })
}
</script>

<template>
  <div>
    <button @click="handleAction">
      Send Event
    </button>
  </div>
</template>

Installation

You must install the posthog-js dependency:

pnpm add posthog-js

EU Hosting

To use PostHog's EU cloud:

export default defineNuxtConfig({
  scripts: {
    registry: {
      posthog: {
        apiKey: 'YOUR_API_KEY',
        region: 'eu'
      }
    }
  }
})

First-Party Proxy

When first-party mode is active (auto-enabled for scripts that support it), your server automatically proxies PostHog requests. This improves event capture reliability by avoiding ad blockers. Nuxt applies no privacy anonymization; PostHog is a trusted, open-source tool that requires full-fidelity data for GeoIP enrichment, feature flags, and session replay.

No additional configuration required. The module automatically sets apiHost to route through your server's proxy endpoint:

export default defineNuxtConfig({
  scripts: {
    registry: {
      posthog: {
        apiKey: 'YOUR_API_KEY',
        // apiHost is auto-set to '/_scripts/p/ph' (or '/_scripts/p/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:

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:

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

export default defineNuxtConfig({
  scripts: {
    registry: {
      posthog: {
        apiKey: 'YOUR_API_KEY',
        disableSessionRecording: true
      }
    }
  }
})