nuxt-bugsnag

📖 Release Notes

Playground

Open Stackblitz and try it out.

Setup

1. Add nuxt-bugsnag dependency to your project

npx nuxi@latest module add bugsnag

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

You can upload sourcemaps by adding the option publishRelease. It's important to set the baseUrl as well, it will allow bugsnag to map your errors to the sourcemap:

{
  bugsnag: {
    publishRelease: true,
    baseUrl: 'http://localhost:3000'
  }
}

The output for a medium Nuxt App can get quite big. So we added an option to disable the logs for that case.

{
  bugsnag: {
    publishRelease: true,
    disableLog: true,
    baseUrl: 'http://localhost:3000'
  }
}

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

GDPR Compliance (Deferred Initialization)

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:

1. useBugsnag() returns a mock client that logs errors to console
2. Call initBugsnag() after obtaining user consent to start the real Bugsnag client
3. 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

1. $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'))
   

2. $bugsnagPerformance removed - Use useBugsnagPerformance() composable instead

   // Before (v8.x)
   this.$bugsnagPerformance.startSpan('my-span')
   
   // After (v9.0)
   useBugsnagPerformance().startSpan('my-span')
   

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

1. Clone this repository
2. Install dependencies using npm install
3. Start development server using npm run dev

License

MIT License

Copyright (c) Julian Martin julian.martin@russmedia.com