Generating a Source Map
The first thing that we’ll need is a tool to minify the code. I’m going to use
UglifyJS, but most tools should support the ability to generate a production source map as part of the minification process. You can install
UglifyJS with npm if you have that installed on your workstation.
$ npm install uglify-js -g
You can then validate installation by executing the following:
$ uglifyjs --version
In some cases, you may have to add the installation folder to your path.
Now that we have
uglifyjs installed and we’ve verified that it works, let’s minify our code. If you’re using the example project, this command will overwrite the existing minified file and source map.
From the JS folder of the demo project, enter the following command.
$ uglifyjs calculator.js --compress --mangle --source-map --output calculator.min.js
calculator.js and converts it to a minified version
calculator.min.js, along with a source map
calculator.min.js.map. Even with this small file, the minification process reduces the size of the file from 4KB to 1KB.
How do Source Maps Work?
Source maps describe how the compiled code is related to your original source code. The debugger can then show the original code you wrote, while actually running the compiled code.
Let’s open up the source map file to see what it has in it. I used a JSON parser to format it for easy reading, and shortened some of the lines with ellipses as well.
"version" : 3,
"sources" : [calculator.js],
"names" : [resultNum,operator,el,element,charAt,document,querySelector,...],
"mappings" : CAAC,WACC,aAyGA,IAAK,IAvFHA,EACAC,EAhBEC,EAAK,SAASC,GAChB,MAA0B,MAAtBA,...
The file specifies the mapping version used and identifies the source files and names of parameters. The useful part is the mappings, although unfortunately since they are in Base 64 VLQ, they’re not very useful for the human brain.
If you’d like to understand more about how the mappings work, and how they translate the minified code back to the source, I’d recommend reading How do source maps work. For now, let’s look at how to leverage the source map in production to make debugging easier.
If you open the
Working with Source Maps in Production
rollbar,js supports source maps, you can see the line of exact code where each error originated along with the stack trace. Let’s dive into an example of how it works.
Once you have created an account and your first project, you’ll be given a client-side access tokens. Add the script included under the Quick start browser section inside the
<HEAD> tag in
You can upload your source maps via the API. Usually, we would use a script do this automatically at deployment time, but we will do it manually for this tutorial. From the root folder of the web application project, execute the following curl command after updating the access token and the minified_url to your token and URL:
$ curl https://api.rollbar.com/api/1/sourcemap \
-F access_token=8888888888888888888888888 \
-F version=0.0.1 \
-F source_map=@js/calculator.min.js.map \
Once that is done, clicking on an error should take you to a page with the stack trace. Here we can see the proper source code with files, line numbers from the source map.
When you click the source file link, it will open to the file and line number in GitHub, BitBucket, or GitLab. There, you can use the tools to see what changes were made and when. To learn more, check out the source maps documentation for additional details and config options.
Tips for using source maps in production and debugging with Rollbar
- The value of
minified_urlmust be the full URL of the minified file. This should start with
https:, which we'll strip off.
- If you're using the upload method, check to be sure that the
code_versionused in the on-page snippet matches the version provided in the upload call.
guess_uncaught_frames, we won't be able to apply the source map. We need column numbers to be able to apply the source map without guessing.
- If your source map file combines multiple sub-maps into "sections" within the top level map, we, unfortunately, don't yet support this source map format (but we are planning to soon).
In conclusion, source maps help you debug production code right in your browser's developer console. They tell you the exact file and line number when there is an error, and make it natural to use the debugging feature within your browser to step through the code. This makes it much easier to find the root cause of problems and fix them quickly. When monitoring production systems, make sure to choose solutions like Rollbar that support source maps and make debugging production super easy.