webpack-bugsnag-plugins/README.md

Webpack plugins for common Bugsnag actions

<div align="center">
  <a href="https://www.bugsnag.com/platforms/javascript">
    <picture>
      <source media="(prefers-color-scheme: dark)" srcset="https://assets.smartbear.com/m/3dab7e6cf880aa2b/original/BugSnag-Repository-Header-Dark.svg">
      <img alt="SmartBear BugSnag logo" src="https://assets.smartbear.com/m/3945e02cdc983893/original/BugSnag-Repository-Header-Light.svg">
    </picture>
  </a>
  <h1>Webpack plugins for BugSnag</h1>
</div>

[![Documentation](https://img.shields.io/badge/documentation-latest-blue.svg)](https://docs.bugsnag.com/build-integrations/webpack/)
[![Build status](https://badge.buildkite.com/c91be8981b0e64213b64276b8052a728c81aae3fc493ac5d93.svg)](https://buildkite.com/bugsnag/webpack-bugsnag-plugins)
[![NPM](https://img.shields.io/npm/v/webpack-bugsnag-plugins.svg)](https://npmjs.org/package/webpack-bugsnag-plugins)

Webpack plugins for reporting new builds to your dashboard and uploading source maps for deobfuscating stack traces.

## Installation

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

## Plugins

### `new BugsnagBuildReporterPlugin(build, opts):`[`WebpackPlugin`](https://webpack.js.org/concepts/plugins/)

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

Reports your application's build to BugSnag. It can auto detect source control from `.git`, `.hg` and `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.

- `build` describes the build you are reporting to Bugsnag
  - `apiKey: string` your Bugsnag API key __[required]__
  - `appVersion: string` the version of the application you are building __[required]__
  - `releaseStage: string` `'production'`, `'staging'` etc. (leave blank if this build can be released to different `releaseStage`s)
  - `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`)
    - `provider: string` can be one of: `'github'`, `'github-enterprise'`, `'gitlab'`, `'gitlab-onpremise'`, `'bitbucket'`, `'bitbucket-server'`
    - `repository: string` a URL (`git`/`ssh`/`https`) pointing to the repository, or webpage representing the repository
    - `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'`.
  - `metadata: object` an object describing key/value pairs containing any custom build information that provides useful metadata about the build. e.g. build configuration parameters, versions of dependencies, reason for the build etc.
- `opts`
  - `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`)

#### Usage

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

module.exports = {
  entry: './app.js',
  output: {
    path: __dirname,
    filename: './bundle.js'
  },
  plugins: [].concat(
    // 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
    isDistEnv
      ? new BugsnagBuildReporterPlugin({
          apiKey: 'YOUR_API_KEY',
          appVersion: '1.2.3'
        }, { /* opts */ })
      : []
  )
}
```

---

### `new BugsnagSourceMapUploaderPlugin(opts):`[`WebpackPlugin`](https://webpack.js.org/concepts/plugins/)

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

Upload your application's sourcemap(s) to Bugsnag. When Webpack is done producing output, this plugin detects sourcemaps for any output chunks and uploads them to Bugsnag.

- `opts` provide options to the sourcemap uploader
  - `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`](https://webpack.js.org/configuration/output/#output-publicpath) in your Webpack config.
  - `appVersion: string` the version of the application you are building (defaults to the `version` set in your project's package.json file, if one is specified there)
  - `codeBundleId: string` the codeBundleId (e.g. for NativeScript projects)
  - `overwrite: boolean` whether you want to overwrite previously uploaded sourcemaps
  - `endpoint: string` post the build payload to a URL other than the default (`https://upload.bugsnag.com`)
  - `ignoredBundleExtensions: string[]` a list of bundle file extensions which shouldn't be uploaded (default `[ '.css' ]`)

#### Usage

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

module.exports = {
  entry: './app.js',
  devtool: 'source-map',
  output: {
    path: __dirname,
    filename: './bundle.js',
    publicPath: 'https://your-app.xyz/assets/'
  },
  plugins: [].concat(
    // 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
    isDistEnv
      ? new BugsnagSourceMapUploaderPlugin({
          apiKey: 'YOUR_API_KEY',
          appVersion: '1.2.3'
        })
      : []
  )
}
```

## Supported Webpack versions

These plugins have been tested with webpack versions 3, 4 and 5.

## Support

- [Search open and closed issues](https://github.com/bugsnag/webpack-bugsnag-plugins/issues?q=is%3Aissue) issues for similar problems
- [Report a bug or request a feature](https://github.com/bugsnag/webpack-bugsnag-plugins/issues/new)
- Email [support@bugsnag.com](mailto:support@bugsnag.com)

## Contributing

All contributors are welcome! See our [contributing guide](CONTRIBUTING.md).

## License

This module is free software released under the MIT License. See [LICENSE.txt](LICENSE.txt) for details.