PostHog

PostHog is an open-source product analytics platform with session replay, feature flags, and experiments. Nuxt Scripts loads PostHog's official posthog-js browser SDK from npm.

Use useScriptPostHog() to load the SDK and access the PostHog client.

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. PostHog recommends a reverse proxy for more reliable event capture because ad blockers can reject requests to known analytics domains. Nuxt anonymizes the client IP address to subnet level; other data passes through so features such as session replay and feature flags continue to work.

The module sets apiHost to 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 API requests and static assets, including the session recording SDK.

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')
})

Consent Mode

PostHog exposes opt_in_capturing / opt_out_capturing. Set the boot-time default with defaultConsent and call consent.optIn() / consent.optOut() at runtime.

defaultConsent

Example

<script setup lang="ts">
const { consent } = useScriptPostHog({
  apiKey: 'YOUR_API_KEY',
  defaultConsent: 'opt-out',
})

function onAccept() {
  consent.optIn()
}
function onRevoke() {
  consent.optOut()
}
</script>

Configuring PostHog globally in nuxt.config:

export default defineNuxtConfig({
  scripts: {
    registry: {
      posthog: {
        apiKey: 'YOUR_API_KEY',
        defaultConsent: 'opt-out',
      }
    }
  }
})

Disabling Session Recording

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