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