Webpack

Report builds and upload source maps to BugSnag using Webpack

Use our Webpack plugin to:

Report information when you build your app to enable linking to code in your source control provider from the releases dashboard, timeline annotations, and stack traces.
Upload source maps to unminify stack traces and get human-readable method names, files, and line numbers.

Applications using Create React App don’t support custom Webpack configuration, so the integration below cannot be used. Instead, use the @bugsnag/source-maps CLI to upload the source maps which are generated after a build.

Installation

Install the webpack-bugsnag-plugins module.

npm install --save-dev webpack-bugsnag-plugins

Reporting builds

BugsnagBuildReporterPlugin reports your application’s build to BugSnag. It can auto detect source control from Git/Mercurial repos and from projects with a package.json.

This plugin hooks into the 'after-emit' event once all output files have been generated by the Webpack compiler. If anything causes the compilation to fail before this step, the build report will not get sent.

Here’s an example:

/* webpack.config.js */

const { BugsnagBuildReporterPlugin } = require('webpack-bugsnag-plugins')

module.exports = {
  entry: './app.js',
  output: {
    path: __dirname,
    filename: './bundle.js'
  },
  plugins: [
    // It's a good idea to only run this plugin when you're building a bundle
    // that will be released, rather than for every development build
    new BugsnagBuildReporterPlugin({
      apiKey: 'YOUR_API_KEY',
      appVersion: '1.2.3'
    }, { /* opts */ })
  ]
}

The appVersion must match the app version in your notifier configuration.

See the configuration section for detailed instructions on how to configure build reporting in your application.

Uploading source maps

BugsnagSourceMapUploaderPlugin uploads your application’s sourcemaps to BugSnag. When Webpack is done producing output, this plugin detects source maps for any output chunks and uploads them to BugSnag.

Here’s an example:

/* webpack.config.js */

const { BugsnagSourceMapUploaderPlugin } = require('webpack-bugsnag-plugins')

module.exports = {
  entry: './app.js',
  devtool: 'source-map', // Ensure your webpack build is creating source maps!
  output: {
    path: __dirname,
    filename: './bundle.js',
    publicPath: 'https://your-app.xyz/assets/'
  },
  plugins: [
    // It's a good idea to only run this plugin when you're building a bundle
    // that will be released, rather than for every development build
    new BugsnagSourceMapUploaderPlugin({
      apiKey: 'YOUR_API_KEY',
      appVersion: '1.2.3',
      metadata: {
        "buildServer": "build1",
        "buildReason": "Releasing JIRA-1234"
      }
    })

  ]
}

The appVersion must match the app version in your notifier configuration.

The default behavior is to reject uploads if a source map has already been uploaded for the same path and app version. In this case HTTP status 409 received from upload API will be shown in the plugin output. Set the overwrite option to true to allow new uploads to replace existing uploads. This means that events subsequently received from the previous build may not be mapped correctly.

See the configuration section for detailed instructions on how to configure source map uploading in your application.

Electron example

If you’re using the Webpack plugin on an Electron app, for instance with Electron Forge’s Webpack plugin, you’ll need to configure the source map upload plugin separately for the main and renderer config bundles:

/* webpack.main.config.js */

plugins: [
  new BugsnagSourceMapUploaderPlugin({
    apiKey: 'YOUR_API_KEY',
    appVersion: '1.2.3',
    publicPath: '*/main'
  })
]

/* webpack.renderer.config.js */

plugins: [
  new BugsnagSourceMapUploaderPlugin({
    apiKey: 'YOUR_API_KEY',
    appVersion: '1.2.3',
    publicPath: '*/renderer',
    codeBundleId: 'r1000-abc' /* optional */
  })
]

The appVersion must match the app version in your package.json or specified in notifier configuration. If you publish renderer JS updates without releasing a new version of your app, use codeBundleId to identify the bundle to BugSnag for matching source maps. This should also be set to a matching value in notifier configuration.

Configuration

Build Reporter

const { BugsnagBuildReporterPlugin } = require('webpack-bugsnag-plugins')
const plugin = new BugsnagBuildReporterPlugin(build, opts)

`build`

An object describing the build payload to be reported to BugSnag.

Property	Type	Description
`apiKey`	`string`	your BugSnag API key [required]
`appVersion`	`string`	the version of the application you are building [required] (this should match the `appVersion` configured in your notifier)
`autoAssignRelease`	`boolean`	automatically associate this build with any new error events and sessions that are received for the `releaseStage` until a subsequent build notification is received. If this is set to `true` and no `releaseStage` is provided the build will be applied to `'production'`. You should only use this option if you aren’t able to set an `appVersion` in your notifier.
`builderName`	`string`	the name of the person/machine that created this build (defaults to the result of the `whoami` command)
`metadata`	`object`	key-value pairs containing any custom information about the build (e.g. configuration parameters, dependency versions, etc). The keys and values must be strings. Nested objects aren’t supported.
`releaseStage`	`string`	`'production'`, `'staging'`, etc. (Leave blank if this build applies to multiple `releaseStage`s. New releases will be created when events are received with their respective `releaseStage`)
`sourceControl`	`object`	an object describing the source control of the build (if not specified, the module will attempt to detect source control information from `.git`, `.hg` and the nearest `package.json`)
`sourceControl.provider`	`string`	can be one of: `'github'`, `'github-enterprise'`, `'gitlab'`, `'gitlab-onpremise'`, `'bitbucket'`, `'bitbucket-server'`
`sourceControl.repository`	`string`	a URL (`git`/`ssh`/`https`) pointing to the repository, or webpage representing the repository
`sourceControl.revision`	`string`	the unique identifier for the commit (e.g. git SHA)

`opts`

An object that can alter the behaviour of the plugin.

Property	Type	Description
`endpoint`	`string`	Defaults to `https://build.bugsnag.com`. If you are using BugSnag On-premise use your BugSnag Build API endpoint
`logLevel`	`string`	the minimum severity of log to output (`'debug'`, `'info'`, `'warn'`, `'error'`), default `'warn'`
`logger`	`object`	provide a different logger object `{ debug, info, warn, error }`
`path`	`string`	the path to search for source control info, defaults to `process.cwd()`

Source map uploader

const { BugsnagSourceMapUploaderPlugin } = require('webpack-bugsnag-plugins')
const plugin = new BugsnagSourceMapUploaderPlugin(opts)

`opts`

Provide options to the source map uploader.

Property	Type	Description
`apiKey`	`string`	Your BugSnag API key [required]
`appVersion`	`string`	The version of the application you are building (this should match the `appVersion` configured in your notifier). Defaults to the `version` set in your project’s `package.json` file, if one is specified there.
`endpoint`	`string`	Defaults to `https://upload.bugsnag.com/sourcemap`. If you are using BugSnag On-premise use your BugSnag Upload API endpoint
`ignoredBundleExtensions`	`string[]`	A list of bundle file extensions which shouldn’t be uploaded (default `['.css']`). If your Webpack build creates bundled assets of any kind other than `.js` or `.css`, you should override this setting.
`overwrite`	`boolean`	Whether you want to overwrite previously uploaded source maps for the same path and `appVersion`. Defaults to `false`.
`publicPath`	`string`	The path to your bundled assets as it appears in a stack trace. For an app running in a browser this is typically a URL. This option must be provided but defaults to `output.publicPath` in your Webpack config. Note that this can include wildcards in case your JS is served at multiple URLs.

For more information relating to source maps, see source map support and source map upload FAQs.