Node.js/npm scripts

Report builds and upload source maps to Bugsnag using a JS API or Node-based CLI

Use our tools 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.

If you are using any of the following tools in your build, you may find the following guides more convenient: Webpack, Grunt or Gulp.

Reporting builds

#Installation

Install the bugsnag-build-reporter tool.

npm install --save-dev bugsnag-build-reporter

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

#JS API

If your application builds in a Node environment, you can import the JS API and use it like so:

const reportBuild = require('bugsnag-build-reporter')
reportBuild({ apiKey: 'YOUR_API_KEY', appVersion: '1.2.3' }, { /* opts */ })
  .then(() => console.log('success!'))
  .catch(err => console.log('fail', err.messsage))

#CLI

npm scripts

scripts: {
  "report-build": "bugsnag-build-reporter -k YOUR_API_KEY -v '1.2.3' -n 'Katherine Johnson'"
}

make

PATH := node_modules/.bin:$(PATH)
SHELL := /bin/bash

report-build:
    bugsnag-build-reporter -k YOUR_API_KEY -v "1.2.3" -n "Katherine Johnson"

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

#Installation

Install the bugsnag-sourcemaps tool.

npm install --save-dev bugsnag-sourcemaps

#JS API

If your application builds in a Node environment, you can import the JS API and use it like so:

const { upload } = require('bugsnag-sourcemaps')
const { resolve } = require('path')

// using the version property in package.json as the canonical
// application version is a nice way to keep things in sync
const { version } = require('./package.json')

upload({
  apiKey: 'YOUR_API_KEY_HERE',
  appVersion: version,
  minifiedUrl: 'http://your.doma.in/static/js/bundle.js',
  sourceMap: resolve(__dirname, '/static/js/bundle.js.map'),
  minifiedFile: resolve(__dirname, '/static/js/bundle.js'),
  overwrite: true
}, cb)

#CLI

The module also includes a CLI which provides input validation, automatic upload of sources, and the ability to configure via a .bugsnagrc file.

npm install -g bugsnag-sourcemaps
bugsnag-sourcemaps upload --api-key YOUR_API_KEY_HERE \
    --app-version 1.2.3 \
    --minified-url 'http://your.doma.in/static/js/bundle.js' \
    --source-map static/js/bundle.js.map \
    --minified-file static/js/bundle.js \
    --overwrite \
    --upload-sources

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

Configuration

Build Reporter

const reportBuild = require('bugsnag-build-reporter')
const promise = reportBuild(build, opts)
  .then(() => {})
  .catch(err => {})

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.
appVersionCode string if you’re using this module to report Android app builds, set this option
appBundleVersion string if you’re using this module to report iOS/macOS/AppleTV app builds, set this option

opts

An object that can alter the behaviour of the module.

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 { upload } = require('bugsnag-sourcemaps')
const promise = new upload(opts)
  .then(() => {})
  .catch(err => {})

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). 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)
sourceMap string file path of the source map on the current machine
minifiedFile string file path of the minified file on the current machine
sources object object paths to original source file locations on the current machine. This option is useful when the sources are not included in the source map.
projectRoot string The root path to remove from absolute paths
uploadSources boolean If the source content was not included in the source map, this option will retrieve the sources and attach them
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.