@leahcimic/nuxt-sentry

v4.3.5

Published

3 years ago

Sentry module for Nuxt.js

Downloads

0High
0Medium
0Low

leahcimic

@nuxtjs/sentry

Sentry module for Nuxt.js

Features

The module enables error logging through Sentry.

Please note that version 2.2.0 of this package removed the older public_key and private_key options, since the updated Sentry packages don't support these anymore.
Please note that version 2.0.0 of this package introduces a breaking change. See #30 for more information.

Setup

Nuxt.js v2.4.0+ is required, earlier versions are not supported

Add @nuxtjs/sentry dependency using yarn or npm to your project
Add @nuxtjs/sentry to modules section of nuxt.config.js

{
  modules: [
    '@nuxtjs/sentry',
  ],

  sentry: {
    dsn: '', // Enter your project's DSN here
    config: {}, // Additional config
  }
}

Configure

See Options for a list of available options

Usage

Enter your DSN in the Nuxt.js config file. Additional config settings can be found here.

Usage in Vue components

In a Vue component, Sentry is available as this.$sentry, so we can call functions like

this.$sentry.captureException(new Error('example'))

where this is a Vue instance.

Usage in `asyncData`

While using Nuxt's asyncData method, there's $sentry object in the context:

async asyncData ({ params, $sentry }) {
  try {
    let { data } = await axios.get(`https://my-api/posts/${params.id}`)
    return { title: data.title }
  } catch (error) {
    $sentry.captureException(error)
  }
}

Usage in other lifecycle areas

For the other special Nuxt lifecycle areas like plugins, middleware, and nuxtServerInit, the $sentry object is also accessible through the context object like so:

async nuxtServerInit({ commit }, { $sentry }) {
  try {
    let { data } = await axios.get(`https://my-api/timestamp`)
    commit('setTimeStamp', data)
  } catch (error) {
    $sentry.captureException(error)
  }
}

Lazy Loading (on the client)

:warning: Please be aware that lazy loading could prevent some errors from being reported

Set lazy: true in your module options to load Sentry lazily on the client. This will prevent Sentry from being included in your main bundle but could result in some errors not being reported.

You can also pass a lazy config object in your module options (see options for more information).

Injected properties

`$sentry` (mocked)

Type: Object

Normally $sentry would always refer to the @sentry/browser API. But if we lazy load Sentry this API wont be available until Sentry has loaded. If you don't want to worry about whether Sentry is loaded or not, a mocked Sentry API is injected into the Nuxt.js context that will execute all Sentry API calls once Sentry is loaded

See: injectMock and mockApiMethods options below

`$sentryReady`

Type Function

This method returns a Promise which will be resolved once Sentry has been loaded. You could use this instead of mocking $sentry.

Example usage:

this.$sentryReady().then((sentry) => sentry.captureMessage('Erreur!'))
// or
(await this.$sentryReady()).captureMessage('Erreur!')

`$sentryLoad`

Type: Function

Only injected when injectLoadHook: true.

The callback you need to call to indicate that you are ready to load Sentry.

Example usage:

  // layouts/default.vue
  ...
  mounted() {
    // This will only load sentry once an error was thrown
    // To prevent a chicken & egg issue, make sure to also
    // set injectMock: true if you use this so the error
    // that triggered the load will also be captured
    this.errorListener = () => {
      this.$sentryLoad()
      window.removeEventListener('error', errorListener)
    }
    window.addEventListener('error', errorListener)
  },
  destroyed() {
    window.removeEventListener('error', this.errorListener)
  }

Options

Options can be passed using either environment variables or sentry section in nuxt.config.js. Normally, setting required DSN information would be enough.

dsn

Type: String
- Default: process.env.SENTRY_DSN || ''
- If no dsn is provided, Sentry will be initialised, but errors will not be logged. See #47 for more information about this.

lazy

Type: Boolean or Object
- Default: false
- Load Sentry lazily so it's not included in your main bundle
- If true then the default options will be used:
```
  {
    injectMock: true,
    injectLoadHook: false,
    mockApiMethods: true,
    chunkName: 'sentry',
    webpackPrefetch: false,
    webpackPreload: false
  }
```
- injectMock
  - Type: Boolean
    - Default: true
    - Whether a Sentry mock needs to be injected that captures any calls to $sentry API methods while Sentry has not yet loaded. Captured API method calls are executed once Sentry is loaded
  When injectMock: true this module will also add a window.onerror listener. If errors are captured before Sentry has loaded then these will be reported once Sentry has loaded using sentry.captureException
```
// pages/index.vue
beforeMount() {
  // onNuxtReady is called _after_ the Nuxt.js app is fully mounted,
  // so Sentry is not yet loaded when beforeMount is called
  // But when you set injectMock: true this call will be captured
  // and executed after Sentry has loaded
  this.$sentry.captureMessage('Hello!')
},
```
- injectLoadHook
  - Type: Boolean
    - Default: false
    - By default Sentry will be lazy loaded once window.onNuxtReady is called. If you want to explicitly control when Sentry will be loaded you can set injectLoadHook: true. The module will inject a $sentryLoad method into the Nuxt.js context which you need to call once you are ready to load Sentry
```
// layouts/default.vue
...
mounted() {
  // Only load Sentry after initial page has fully loaded
  // (this example should behave similar to using window.onNuxtReady though)
  this.$nextTick(() => this.$sentryLoad())
}
```
- mockApiMethods
  - Type: Boolean or Array
    - Default true
    - Which API methods from @sentry/browser should be mocked. You can use this to only mock methods you really use.
    - This option is ignored when injectMock: false
    - If mockApiMethods: true then all available API methods will be mocked
    If injectMock: true then captureException will always be mocked for use with the window.onerror listener
```
// nuxt.config.js
sentry: {
  lazy: {
    mockApiMethods: ['captureMessage']
  }
}

// pages/index.vue
mounted() {
  this.$sentry.captureMessage('This works!')

  this.$sentry.captureEvent({
    message: `
      This will throw an error because
      captureEvent doesn't exists on the mock
    `
  })

  // To circumvent this problem you could use $sentryReady
  (await this.$sentryReady()).captureEvent({
    message: `
      This will not throw an error because
      captureEvent is only executed after
      Sentry has been loaded
    `
  })
}
```
- chunkName
  - Type: String
    - Default: 'sentry'
    - The webpackChunkName to use, see Webpack Magic Comments
- webpackPrefetch
  - Type: Boolean
    - Default: false
    - Whether the Sentry chunk should be prefetched
- webpackPreload
  - Type: Boolean
    - Default: false
    - Whether the Sentry chunk should be preloaded

disabled

Type: Boolean
- Default: process.env.SENTRY_DISABLED || false
- Sentry will not be initialised if set to true.

disableClientSide

Type: Boolean
- Default: process.env.SENTRY_DISABLE_CLIENT_SIDE || false

disableServerSide

Type: Boolean
- Default: process.env.SENTRY_DISABLE_SERVER_SIDE || false

initialize

Type: Boolean
- Default: process.env.SENTRY_INITIALIZE || true
- Can be used to add the $sentry object without initializing it, which will result in not reporting errors to Sentry when they happen but not crashing on calling the Sentry APIs.

logMockCalls

Type: Boolean
- Default: true
- Whether to log calls to the mocked $sentry object in the console
- Only applies when mocked instance is used (when disabled, disableClientSide or disableServerSide is true)

publishRelease

Type: Boolean
- Default: process.env.SENTRY_PUBLISH_RELEASE || false
- See https://docs.sentry.io/workflow/releases for more information

sourceMapStyle

Type: String
- Default: source-map
- Only has effect when publishRelease = true
- The type of source maps generated when publishing release to Sentry. See https://webpack.js.org/configuration/devtool for a list of available options
- Note: Consider using hidden-source-map instead. For most people, that should be a better option but due to it being a breaking change, it won't be set as the default until next major release

attachCommits

Type: Boolean
- Default: process.env.SENTRY_AUTO_ATTACH_COMMITS || false
- Only has effect when publishRelease = true

repo

Type: String
- Default: process.env.SENTRY_RELEASE_REPO || ''
- Only has effect when publishRelease = true && attachCommits = true

disableServerRelease

Type: Boolean
- Default: process.env.SENTRY_DISABLE_SERVER_RELEASE || false
- See https://docs.sentry.io/workflow/releases for more information

disableClientRelease

Type: Boolean
- Default: process.env.SENTRY_DISABLE_CLIENT_RELEASE || false
- See https://docs.sentry.io/workflow/releases for more information

clientIntegrations

Type: Dictionary
- Default:
```
 {
    Dedupe: {},
    ExtraErrorData: {},
    ReportingObserver: {},
    RewriteFrames: {},
    Vue: {attachProps: true, logErrors: this.options.dev}
 }
```
- See https://docs.sentry.io/platforms/javascript/vue/ and https://docs.sentry.io/platforms/node/pluggable-integrations/ for more information on configuring integrations

serverIntegrations

Type: Dictionary
- Default:
```
  {
    Dedupe: {},
    ExtraErrorData: {},
    RewriteFrames: {},
    Transaction: {}
  }
```
- See https://docs.sentry.io/platforms/node/pluggable-integrations/ for more information

config

Type: Object
- Default: { environment: this.options.dev ? 'development' : 'production' }
- Sentry options common to the server and client that are passed to Sentry.init(options). See Sentry documentation at https://docs.sentry.io/error-reporting/configuration/?platform=browsernpm
- Note that config.dsn is automatically set based on the root dsn option
- The value for config.release is automatically inferred from the local repo unless specified manually

serverConfig

Type: Object
- Default: { }
- Specified key will override common Sentry options for server sentry plugin

clientConfig

Type: Object
- Default: { }
- Specified keys will override common Sentry options for client sentry plugin

webpackConfig

Type: Object
- Default: Refer to module.js since defaults include various options that also change dynamically based on other options.
- Options passed to @sentry/webpack-plugin. See documentation at https://github.com/getsentry/sentry-webpack-plugin/blob/master/README.md

Submitting releases to Sentry

Support for the sentry-webpack-plugin was introduced #a6cd8d3. This can be used to send releases to Sentry. Use the publishRelease option to enable this feature.

Note that releases are only submitted to Sentry when (options.publishRelease && !isDev) is true.

License

MIT License