nuxt-bugsnag

Bugsnag integration for nuxt.js. Makes it easy to add bugsnag to your Project. Supports uploading source maps.

21.3k downloads•49 stars•v9.0.1

JulianMar

nuxt-bugsnag

📖 Release Notes

Playground

Open Stackblitz and try it out.

Setup

Add nuxt-bugsnag dependency to your project

npx nuxi@latest module add bugsnag

Add nuxt-bugsnag to the modules section of nuxt.config.js.

{
  modules: [
    'nuxt-bugsnag'
  ]
}

You can pass every bugsnag options in the config object

{
  bugsnag: {
    config: {
      apiKey: 'your key',
      enabledReleaseStages: ['staging', 'production'],
    }
  }
}

Source Maps

Set publishRelease to upload source maps during a production build. The module uses the BugSnag Vite uploader for browser chunks and the BugSnag CLI for final Nitro server bundles.

Set baseUrl to the public URL that serves your Nuxt assets and ensure appVersion matches the Bugsnag notifier configuration:

{
  bugsnag: {
    publishRelease: true,
    baseUrl: 'https://example.com/',
    config: {
      apiKey: 'YOUR_API_KEY',
      appVersion: 'YOUR_VERSION'
    }
  }
}

Uploads are enabled only for non-development builds. Existing source maps for the same bundle path and app version are overwritten, so each deploy should use a unique appVersion.

Set disableLog to suppress uploader output:

{
  bugsnag: {
    publishRelease: true,
    disableLog: true,
    baseUrl: 'https://example.com/'
  }
}

Setting a different project root

If your Nuxt App runs in a different folder than /, you might want to set projectRoot to this directory, so that BugSnag can match the sourcemap.

{
  bugsnag: {
    publishRelease: true,
    projectRoot: '/someFolder/'
  }
}

Config Example

I would recommend to set these options

{
  modules: [
    'nuxt-bugsnag',
  ],

  bugsnag: {
    publishRelease: true,
    config: {
      apiKey: 'YOUR_API_KEY',
      enabledReleaseStages: ['staging', 'production'],
      releaseStage: process.env.NODE_ENV,
      appVersion: 'YOUR_VERSION',
    }
  }
}

Reporting custom errors

Use the useBugsnag() composable to report errors:

useBugsnag().notify(new Error('Some Error'))

Performance

Only available in 7.4.0 and above

The simplest Configuration for the bugsnag performance feature is like this

{
  bugsnag: {
    apiKey: 'YOUR API KEY',
    performance: true
  }
}

for custom options you can use the following config and get all the settings from here

{
  bugsnag: {
    apiKey
    config: {
      performanceConfig: {
        autoInstrumentFullPageLoads: true,
      }
    }
  }
}

Custom Performance Monitoring

For sending Custom Spans see this documentation. There is a little helper in the module to send custom spans.

This can only be used on the client side and should never be called on the server side. There is a mock included so you don't need to worry about that, but should be kept in mind.

useBugsnagPerformance().startSpan('my-span')

For GDPR compliance, you can defer Bugsnag initialization until user consent is obtained using the deferStart option.

Configuration

{
  bugsnag: {
    deferStart: true,
    config: {
      apiKey: 'YOUR_API_KEY',
    }
  }
}

Usage

When deferStart: true, Bugsnag will not initialize automatically. Instead:

useBugsnag() returns a mock client that logs errors to console
Call initBugsnag() after obtaining user consent to start the real Bugsnag client
After initialization, useBugsnag() returns the real client

<script setup>
const hasConsent = ref(false)

function onConsentGiven() {
  hasConsent.value = true
  initBugsnag()
}

// Safe to call anytime - logs to console before consent
function reportError() {
  useBugsnag().notify(new Error('Something went wrong'))
}
</script>

<template>
  <button v-if="!hasConsent" @click="onConsentGiven">
    Accept Cookies
  </button>
  <button @click="reportError">
    Report Error
  </button>
</template>

Note: Before consent is given, errors are logged to the browser console instead of being sent to Bugsnag.

Migration from v8.x

Breaking Changes in v9.0

$bugsnag removed - Use the useBugsnag() composable instead

// Before (v8.x)
this.$bugsnag.notify(new Error('Some Error'))

// After (v9.0)
useBugsnag().notify(new Error('Some Error'))

$bugsnagPerformance removed - Use useBugsnagPerformance() composable instead

// Before (v8.x)
this.$bugsnagPerformance.startSpan('my-span')

// After (v9.0)
useBugsnagPerformance().startSpan('my-span')

Mock behavior changed - The mock client now logs errors to console instead of throwing. This makes it safe to call useBugsnag() before initialization when using deferStart: true.

Development

Clone this repository
Install dependencies using npm install
Start development server using npm run dev

License

MIT License