Nuxt error tracking installation

Installing PostHog Nuxt SDK

Required

Your goal in this step: Install the PostHog Nuxt.js SDK.

Install posthog-js using your package manager:

npm install --save posthog-js

Add your PostHog API key and host to your nuxt.config.js file. You can find these in your project settings.

nuxt.config.js

export default defineNuxtConfig({
  runtimeConfig: {
    public: {
      posthogPublicKey: process.env.NUXT_PUBLIC_POSTHOG_KEY || '<ph_project_api_key>',
      posthogHost: process.env.NUXT_PUBLIC_POSTHOG_HOST || 'https://us.i.posthog.com',
      posthogDefaults: '2025-05-24',
    },
  }
})

Create a new plugin by creating a new file posthog.client.js in your plugins directory.

plugins/posthog.client.js

import { defineNuxtPlugin, useRuntimeConfig } from '#imports'

import posthog from 'posthog-js'

export default defineNuxtPlugin(() => {
  const runtimeConfig = useRuntimeConfig()
  const posthogClient = posthog.init(runtimeConfig.public.posthogPublicKey, {
    api_host: runtimeConfig.public.posthogHost,
    defaults: runtimeConfig.public.posthogDefaults,
    loaded: (posthog) => {
      if (import.meta.env.MODE === 'development') posthog.debug()
    },
  })

  return {
    provide: {
      posthog: () => posthogClient,
    },
  }
})

Verify PostHog is initialized
Checkpoint
Confirm you can capture events with PostHog
Before proceeding, confirm that you can capture events using posthog.capture('test_event').

Manually capturing exceptions

Required

Your goal in this step: Manually capture exceptions in your Nuxt application.

To send errors directly using the PostHog client, import it and use the captureException method like this:

Vue

<script>
  const { $posthog } = useNuxtApp()

  if ($posthog) {
    const posthog = $posthog()
    posthog.captureException(new Error("Important error message"))
  }
</script>

On the server side, you can use the posthog object directly.

server/api/example.js


  const runtimeConfig = useRuntimeConfig()

  const posthog = new PostHog(
    runtimeConfig.public.posthogPublicKey,
    { 
      host: runtimeConfig.public.posthogHost, 
    }
  );

  try {
    const results = await DB.query.users.findMany()
    return results
  } catch (error) {
    posthog.captureException(error)
  }
})

Configuring exception autocapture

Required

Your goal in this step: Enable automatic exception tracking for your Nuxt application.

Update your posthog.client.js to add an error hook

JavaScript

export default defineNuxtPlugin((nuxtApp) => {
    ...
    nuxtApp.hook('vue:error', (error) => {
        posthogClient.captureException(error)
    })
    ...
})

Verify error tracking
Checkpoint
Confirm events are being sent to PostHog
Before proceeding, let's make sure exception events are being captured and sent to PostHog. You should see events appear in the activity feed.

Check for exceptions in PostHog
5
Upload source maps
Required
Great, you're capturing exceptions! If you serve minified bundles, the next step is to upload source maps to generate accurate stack traces.
Let's continue to the next section.
Upload source maps for Nuxt

Nuxt error tracking installation

Installing PostHog Nuxt SDK

Verify PostHog is initialized

Manually capturing exceptions

Configuring exception autocapture

Verify error tracking

Upload source maps

Community questions

Was this page useful?