JavaScript source code minification is a beneficial tool for reducing download file sizes. However, the resulting obfuscation makes the code difficult to read, and reduces trust and transparency. Public source maps will help restore code readability and transparency. As a bonus, it enables others to learn from your code.
The Web Almanac 2020 found that 99,5 % of JavaScript is minified. It’s a more popular data-reduction strategy than using transport layer compression, which is at only 85 %. However, the 2019 Web Almanac found that only 18 % deployed source maps. This last number should be much higher.
A JavaScript minifier is a tool that will process your JavaScript sources to strip out comments, shorten variables and function names, and even rewrite the code to reduce its file size. Computers can still read minified code, but human-readability and niceties like white-space and formatting are lost in the process. Minified code is more difficult to debug and obscures what your code is trying to achieve. Computers are the primary audience for your JavaScript, so it makes sense to optimize for them. However, there’s no reason why you can’t minify your sources and still maintain human-readability.
The obfuscation is just a by-product of the minification process. The minifier can also generate a source map file. The source map file, together with the minified file, lets you restore the original human-readable source file. Browser developer tools will automatically download and apply source maps when they’re available. They also handle the mapping between the two on the fly when tracing or debugging the running code.
Source maps can be included inline in your JavaScript files. An inlined source map eliminates the file-size gains achieved through the minification process. The preferred delivery method is to ship source maps in a separate .js.map file referenced from the minified .js file. Referencing an external source map file only adds around 30–50 bytes to the uncompressed file size.
Many in the web developer community learned — or was at least introduced to — their craft by studying how other websites work. Your website probably could have been incredibly educational to a less experienced you. Don’t kick down the ladder behind you! Deploy your source map and let others study and learn from your code.
There are 12,4 million JavaScript developers in the world, according to Developer Economics/SlashData. Some of them may be running your JavaScript code, and they know how to work with their browser’s developer tools. If something goes wrong with some component on your website, they might just pull up their developer console to see what went wrong. A source map could help land you a detailed and actionable bug report from such a valuable user.
I recently analyzed Cloudflare’s Analytics script to try and evaluate their privacy claims. Their code was minified and it took extra time to understand it, and I had to make educated guesses about the purpose of some parts of it. A source map could have made that job a lot easier.
There are some common arguments against deploying source maps that come up again and again, and I want to address these directly.
You might not want to share your source maps because you’re worried about leaking information related to security or internal systems. Sensitive information doesn’t belong in source code, or in any other plain text files, in any project. Minification, or even deliberate code obfuscation, can’t be used to secure sensitive information. Are there any passwords and other secret information laying around in your code or comments? Then that is your problem.
There are other ways to reduce the risks of your comments leaking something sensitive. You can remove the comments from your source code before minification (as a first-pass minification step), and then generate the source map from the commentless code. This is still a big improvement over not making available a source map.
You might be worried about getting judged for your coding style. You can clean up your code with a code beautifier before running it through a minifier. This will at least enforce a visual style guide on your code. Neither a minified or beautifier can make up for nor hide poorly written code. If you’re lucky, someone might send you a bug report or an idea to enhance your code. The code is already public even without a source map. A source map will, hopefully, make the code’s intended purpose clearer to others.
You might want to hide what your code is doing. Minification doesn’t achieve this. Its execution is entirely transparent to the browser, even though the minified function names makes it hard to tell what it’s supposed to do. If you run shady code client-side, motivated people will still be able to find out how the sausage is made. Stop doing sketchy and unethical things and you won’t have a reason to hide it.
You might worry that people can steal your hard work. Minification isn’t digital rights management (DRM). People can steal your minified code too. Client-side code in an interpreted language is open-source by its very nature. That doesn’t mean an open-source or copyleft license is automatically applied. Your legal rights, including distribution and licensing, are already protected by copyright law.
Maybe you’re using some open-source libraries or frameworks. Their license may require that you make parts or the entire source code available in its human-readable format. For example, the current version of the GNU General Public License (GPLv3) and its variants requires that the source is published in “the preferred form of the work for making modifications to it.” In English, that means the unminified version – or at least a version with the human-readable function names, comments, and intact formatting. A source map will help you comply with such license terms.
Your source maps can even be used as a recruitment tool. You can include a comment encouraging interested developers — who’re already poking around in your project’s workings — to apply to your company. Or maybe include information on how to report bugs. The minifier will strip out the comments, so you don’t waste your JavaScript byte budget. Your source map will make sure the message is only downloaded and seen by developers.
You could even attach a Set-Cookie HTTP header when your source maps are downloaded. The cookie could unlock a fake developer mode, a fun Easter egg, or modify your page layout to emphasize resources that are of interest to developers.
I’ve written over a thousand words already, and I haven’t even mentioned how beneficial it can be to you to have source maps available in production. It greatly simplifies debugging on your real product in the environment your users experience it. You can also debug anytime from just about any computer anywhere in the world.
There are clear benefits to deploying your source maps in production. So, what do you say? Will you begin to deploy your source maps in your production environment?