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
- A Backtrace account (log in or sign up for a free trial license).
- A symbol submission URL with a
symbol:post
token for thesourcemap
endpoint. <detailed instructions>
Creating and Uploading Source Maps
Follow these steps to create and upload source maps with every build of your application:
- Enable source maps
- Install the
backtrace-js
command line tool - 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.
- Typescript (tsc)
- UglifyJS
sourceMap
in compilerOptions
in your tsconfig.json
to true
. For example:{
"compilerOptions": {
// other options
"sourceMap": true
},
"include": ["./src"]
}
--source-map
as parameter to uglifyjs
:uglifyjs main.js -c -m --source-map -o main.min.js
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.
-
Install
@backtrace/javascript-cli
as a dev dependency:npm install --save-dev @backtrace/javascript-cli
-
Add the following script to
package.json
to process and upload source maps:"scripts": {
"backtrace:sourcemap": "backtrace-js run",
} -
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 asymbol:post
token for thesourcemap
endpoint.
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.
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.
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
- Webpack
- Rollup
- Vite
@backtrace/webpack-plugin
to automate working with sourcemaps.Step 1: Enable Source Maps for Your ApplicationSet devtool
to source-map
in your webpack.config.js
:module.exports = {
devtool: 'source-map',
// other configuration
}
@backtrace/webpack-plugin
-
Install
@backtrace/webpack-plugin
as a developer dependency:npm install --save-dev @backtrace/webpack-plugin
-
Add it to your
plugins
array inwebpack.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
})]
}
@backtrace/rollup-plugin
to automate working with sourcemaps.Step 1: Enable Source Maps for Your ApplicationSet sourcemap
in output
to true
in your rollup.config.js
:module.exports = {
output: {
sourcemap: true
}
}
@backtrace/rollup-plugin
-
Install
@backtrace/rollup-plugin
as a developer dependency:npm install --save-dev @backtrace/rollup-plugin
-
Add it to your
plugins
array inrollup.config.js
:import { BacktracePlugin } from '@backtrace/rollup-plugin';
// or
const { BacktracePlugin } = require('@backtrace/rollup-plugin');
module.exports = {
// other configuration
plugins: [BacktracePlugin({
// enable upload only on production builds
uploadUrl: process.env.NODE_ENV === "production" ? "<your upload URL>" : undefined
})]
}
@backtrace/vite-plugin
to automate working with sourcemaps.Step 1: Enable Source Maps for Your ApplicationSet sourcemap
in output
to true
in your vite.config.js
:module.exports = {
build: {
sourcemap: true
}
}
@backtrace/vite-plugin
-
Install
@backtrace/vite-plugin
as a developer dependency:npm install --save-dev @backtrace/vite-plugin
-
Add it to your
plugins
array invite.config.js
:import { BacktracePlugin } from '@backtrace/vite-plugin';
// or
const { BacktracePlugin } = require('@backtrace/vite-plugin');
module.exports = {
// other configuration
plugins: [BacktracePlugin({
// enable upload only on production builds
uploadUrl: process.env.NODE_ENV === "production" ? "<your upload URL>" : undefined
})]
}
We are adding support for the most popular tools regularly. You can always use @backtrace/javascript-cli
; it works with any output JS files.