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.

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 */ })
  ]
}

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

Setting appVersion

There are a variety of ways to manage or inject version numbers in your build, so the following advice applies to whichever strategy you use.

  • Set appVersion in your notifier so that sessions and error reports are correctly associated with your reported builds
  • Keep the notifier appVersion in sync with the build reporter
  • appVersion should change any time your source code, or any of its dependencies changes

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

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

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)
releaseStage string 'production', 'staging' etc. (leave blank if this build can be released to different releaseStages)
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)
builderName string the name of the person/machine that created this build (defaults to the result of the whoami command)
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.

opts

An object that can alter the behaviour of the plugin.

Property Type Description
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()
endpoint string post the build payload to a URL other than the default (https://build.bugsnag.com)

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]
publicPath string the path to your bundled assets (as the browser will see them). This option must either be provided here, or as output.publicPath in your Webpack config. This plugin will use Webpack’s output.publicPath setting if available. Note that this can include wildcards in case your JS is served at multiple URLs.
appVersion string the version of the application you are building (this should match the appVersion configured in your notifier)
overwrite boolean whether you want to overwrite previously uploaded source maps
endpoint string post the source map to a URL other than the default (https://upload.bugsnag.com)

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