Nuxt error tracking installation

Nuxt 3.7 and above

For Nuxt 3.7 and above, we recommend using the official @posthog/nuxt module which provides automatic error tracking with built-in sourcemap support.

  1. Install the PostHog Nuxt module

    Required
    Your goal in this step: Install and configure the PostHog Nuxt module.
    1. Install the PostHog Nuxt module using your package manager:
    npm install @posthog/nuxt
    1. Add the module to your nuxt.config.ts file:
    nuxt.config.ts
    export default defineNuxtConfig({
      modules: ['@posthog/nuxt'],
    

      // Enable sourcemaps generation in both vue and nitro
      sourcemap: { 
        client: 'hidden' 
      },
      nitro: {
        rollupConfig: {
          output: {
            sourcemapExcludeSources: false,
          },
        },
      },
    

      posthogConfig: {
        publicKey: '<ph_project_api_key>', // Find it in project settings https://app.posthog.com/settings/project
        host: 'https://us.i.posthog.com', // Optional: defaults to https://us.i.posthog.com. Use https://eu.i.posthog.com for EU region
        clientConfig: {
          capture_exceptions: true, // Enables automatic exception capture on the client-side (Vue)
        },
        serverConfig: {
          enableExceptionAutocapture: true, // Enables automatic exception capture on the server-side (Nitro)
        },
        sourcemaps: {
          enabled: true,
          envId: '<ph_environment_id>', // Your environment ID from PostHog settings https://app.posthog.com/settings/environment#variables
          personalApiKey: '<ph_personal_api_key>', // Your personal API key from PostHog settings https://app.posthog.com/settings/user-api-keys
          project: 'my-application', // Optional: defaults to git repository name
          version: '1.0.0', // Optional: defaults to current git commit
        },
      },
    })

    The module will automatically:

    • Initialize PostHog on both Vue (client-side) and Nitro (server-side)
    • Capture exceptions on both client and server
    • Generate and upload sourcemaps during build

  2. Manually capturing exceptions

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

    Our module if set up as shown above already captures both client and server side exceptions manually.

    To send errors manually on the client side, 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 instantiate PostHog using:

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

  3. Build your project for production

    Required

    Build your project for production by running the following command:

    Terminal
    nuxt build

    The PostHog module will automatically generate and upload sourcemaps to PostHog during the build process.

  4. Verify source map upload

    Checkpoint
    Confirm sourcemaps are being properly uploaded

    Before proceeding, confirm that sourcemaps are being properly uploaded.

    You can verify the injection is successful by checking your .mjs.map source map files for //# chunkId= comments. Make sure to serve these injected files in production, PostHog will check for the //# chunkId comments to display the correct stack traces.

    Check symbol sets in PostHog

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


    Activity feed with events
    Check for exceptions in PostHog

Nuxt 3.6 and below

For older versions of Nuxt, you'll need to manually set up error tracking and sourcemap uploads.

  1. Installing PostHog Nuxt SDK

    Required
    Your goal in this step: Install the PostHog Nuxt.js SDK.
    1. Install posthog-js using your package manager:
    npm install --save posthog-js
    1. 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',
        },
      }
    })
    1. 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,
        },
      }
    })

  2. 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').

  3. 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)
      }
    })

  4. 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)
        })
        ...
    })

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


    Activity feed with events
    Check for exceptions in PostHog

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

Community questions

Was this page useful?

Questions about this page? or post a community question.