Source map support

The Bugsnag JavaScript library supports using source maps to reverse JavaScript minification. In order for this to work, Bugsnag needs access to the source map. You can either do this by hosting the source maps or by uploading them to Bugsnag.

Generating source maps

Most modern minification tools support the generation of source maps, so it is easy to add this to your build process:

When generating source maps you normally have the option to include the source content within the source map or leave it in the external source files. If you leave it external Bugsnag will need access to those source files to display the context of the error (without it we will just display the source file and line number in the stacktrace).

Source maps can also be encoded directly into the javascript file rather than linking to a external file, known as inline source maps. This is sometimes used for development purposes or in certain bundling frameworks like Browserify. Bugsnag also supports source maps of this type.

Hosting source maps

If you host the source map Bugsnag can fetch it when an error is received. To achieve this you can include the special sourceMappingURL comment at the end of the JavaScript file or set the X-SourceMap property in the header.

Most minification tools, including UglifyJS 2, will automatically add the sourceMappingURL to your minified JavaScript files.

When generating source maps you’ll usually have the option to include the source content within the source map or leave it in the external source files. If you have not included the source content in the source map we will also attempt to fetch the source files based on the path specified in the source map.

Access through firewall

If your server policy denies access to external IP addresses and websites, you will need to whitelist the IP addresses below. A whitelist provides access to designated IP addresses and sites that would otherwise be prevented by your security policy.


Source map upload

If you don’t want to host your source maps, you can upload them to Bugsnag using one of the following options:

Upload tool

bugsnag-sourcemaps is a Node.js module with both a JavaScript interface and and command-line interface (CLI).

Build tool integration

If you use Node.js to bundle your client JavaScript (including any Node.js-based tools such as Grunt, Gulp, Brocolli, etc.), you can upload your source maps to Bugsnag from within the same process that creates them.

For example, from your task runner of choice you could call the upload(opts, cb) function when you build a new release:

npm install --save-dev bugsnag-sourcemaps
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')

  apiKey: 'YOUR_API_KEY_HERE',
  appVersion: version,
  minifiedUrl: '',
  sourceMap: resolve(__dirname, '/static/js/'),
  minifiedFile: resolve(__dirname, '/static/js/bundle.js'),
  overwrite: true
}, cb)

Command line

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 '' \
    --source-map static/js/ \
    --minified-file static/js/bundle.js \
    --overwrite \

Upload API

Alternatively, you can interact with our upload API directly.