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.

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

Uploading source maps

#CLI

bugsnag-sourcemaps provides a CLI that can be used to upload your project’s source maps.

You can install it globally on your system:

npm install --global bugsnag-sourcemaps

Or locally inside your project:

npm install --save-dev bugsnag-sourcemaps

Examples

For a typical browser bundle, where your build generates a single minified file and accompanying source map:

bugsnag-sourcemaps upload --api-key YOUR_API_KEY_HERE \
    --app-version 1.2.3 \
    --minified-url 'http://example.com/assets/example.min.js' \
    --source-map path/to/example.js.map \
    --minified-file path/to/example.min.js

For a Node.js project where your build doesn’t combine the output into a single bundle, but creates a generated file and source map for every input file (for instance, the Babel or TypeScript compiler when not used in conjunction with a bundler) use directory mode:

bugsnag-sourcemaps upload --api-key YOUR_API_KEY_HERE \
    --app-version 1.2.3 \
    --directory

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

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

#JS API

Add bugsnag-sourcemaps to your project’s dependencies.

npm install --save-dev bugsnag-sourcemaps

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

upload({
  apiKey: 'YOUR_API_KEY_HERE',
  // if appVersion is omitted it will
  // be taken from package.json#version
  appVersion: '1.2.3',
  minifiedUrl: 'http://your.doma.in/static/js/bundle.js',
  sourceMap: resolve(__dirname, '/static/js/bundle.js.map'),
  minifiedFile: resolve(__dirname, '/static/js/bundle.js')
}, cb)

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

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 Defaults to https://build.bugsnag.com. If you are using Bugsnag On-premise use your Bugsnag Build API endpoint

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]
appVersion string The version of the application you are building (this should match the appVersion configured in your notifier). If appVersion is not supplied, the version property from the nearest package.json will be used.
directory boolean or string Whether to scan projectRoot for source maps, uploading them all. If a string is provided, it searches that path instead. This option makes minifiedFile, minifiedUrl and sourceMap redundant. This option is only for Node projects where one source map is created per source file.
endpoint string Defaults to https://upload.bugsnag.com. If you are using Bugsnag On-premise use your Bugsnag Upload API endpoint
minifiedFile string File path of the minified file on the current machine
minifiedUrl string The URL of your bundled assets (as the browser will see them). Note that this can include wildcards in case your JS is served at multiple URLs.
overwrite boolean Whether you want to overwrite previously uploaded source maps
projectRoot string The root path to remove from absolute paths
sourceMap string File path of the source map 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.
uploadSources boolean If the source content was not included in the source map, this option will retrieve the sources and attach them

Note that when using the CLI, all of the same options are available but are formatted differently. See the output of bugsnag-sourcemaps --help for reference.


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