Skip to main content

Setting up Source Maps for Backtrace

The Backtrace debugger can highlight specific lines in your source code associated with frames in the callstack. This powerful capability can be enabled by uploading source and source maps. The following steps guide you through configuring your JavaScript application to automatically upload sourcemap files during the project build.

What You'll Need​

Creating and Uploading Source Maps​

Follow these steps to create and upload source maps with every build of your application:

  1. Enable source maps
  2. Install the backtrace-js command line tool
  3. Create a configuration file for backtrace-js

Step 1: Enable Source Maps for Your Application​

Source maps are automatically generated with most JavaScript frameworks. Please follow these instructions if you are using a framework that does not automatically generate source maps.

Set sourceMap in compilerOptions in your tsconfig.json to true. For example:

{
    "compilerOptions": {
        // other options
        "sourceMap": true
    },
    "include": ["./src"]
}

Step 2: Install backtrace-js​

Install the backtrace-js command line tool and update your build scripts to run it. backtrace-js can be run from the command line, but it is most efficient to use a configuration file which we will create in the next step.

  1. Install @backtrace/javascript-cli as a dev dependency:

    npm install --save-dev @backtrace/javascript-cli

  2. Add the following script to package.json to process and upload source maps:

    "scripts": {
      "backtrace:sourcemap": "backtrace-js run",
    }

  3. Update the build step in package.json to process and upload source maps with every build:

    "scripts": {
      "build": "<current build commands> && npm run backtrace:sourcemap"
    }

Step 3: Create a .backtracejsrc configuration file​

Create a .backtracejsrc configuration file in the root of your project with these settings to process source maps, add source and upload to Backtrace.

{
    "path": "<build output>",
    "run": {
        "process": true,
        "add-sources": true,
        "upload": true
    },
    "upload": {
        "url": "<symbol submission url>",
        "include-sources": true
    }
}
  • Replace <build output> with the path to the directory where your transpiled scripts are stored.
  • Follow <these instructions> to create the <symbol submission URL> with a symbol:post token for the sourcemap endpoint.
Source Code Upload

Source files can be embedded in source maps and included in the upload to Backtrace. The configuration above is constructed to do this.

Alternatively, if you do not wish to upload source files directly to Backtrace, you can integrate your source repository. To do so, omit add-sources and include-sources and follow the steps in the Source Code document.

Processing node_modules

node_modules are not processed by default. You may include specific modules by including a reference to each in .backtracejsrc path.

{
  "path": [
    "<build output>",
    "./node_modules/bser",
    "./node_modules/chalk"
    ],
    ...
}

See backtrace-js --help or go to @backtrace/javascript-cli for additional command line and configuration options.

Troubleshooting

Source map processing will halt on error with a description. Use a --verbose command line switch to output extended information for troubleshooting.

File processing errors

File processing may halt on a specific file for valid reasons. For instance, a source map may not produced for a script file. Processing for such a file can be skipped with an exclude object in .backtracejsrc

{
  "path": "<build output>",
  "exclude": [
    "./app1/build/static/js/file.chunk.js"
  ]
  "run": {
  ...
}

Alternatively, all processing errors can be treated as warnings or other errors levels.

{
  "path": "<build output>",
  "asset-error-behavior": "warn",
  "run": {
  ...
}

Project Bundlers​

If you're using Webpack as your project bundler, you can use @backtrace/webpack-plugin to automate working with sourcemaps.

Step 1: Enable Source Maps for Your Application

Set devtool to source-map in your webpack.config.js:

module.exports = {
  devtool: 'source-map',
  // other configuration
}

If you're using code transpiler plugins (such as Typescript), be sure to enable source maps there as well.

Step 2: Set up @backtrace/webpack-plugin

  1. Install @backtrace/webpack-plugin as a developer dependency:

    npm install --save-dev @backtrace/webpack-plugin

  2. Add it to your plugins array in webpack.config.js:

    import { BacktracePlugin } from '@backtrace/webpack-plugin';
    // or
    const { BacktracePlugin } = require('@backtrace/webpack-plugin');

    module.exports = {
      // other configuration
      plugins: [new BacktracePlugin({
        // enable upload only on production builds
        uploadUrl: process.env.NODE_ENV === "production" ? "<your upload URL>" : undefined
      })]
    }
Don't See Your Tool Described Here?

We are adding support for the most popular tools regularly. You can always use @backtrace/javascript-cli; it works with any output JS files.