What are source maps in CSS and JavaScript?

With all the optimization techniques like bundling and minification etc getting important and popular it is good that we talk about Source Maps now. Think of this, once you bundle all the CSS files you have into one single file, how do you know which part of CSS was written in which file? To make the situation a little more tricky let us minify the bundled CSS file too. Well, here comes Source Maps to the rescue!

Source Maps, as the name suggests, is a map that contains the mapping between the source file and the final output file. It basically consists of JSON values that are used to map the compressed CSS/JavaScript code to the original file. So even after the source code is bundled or minified, the Source Map file would have information of what code was written on which line number in which file.

What are CSS Source Maps or CSS.map file?

CSS source maps are source map files for CSS. So a CSS source map file would contain the references of code that is within the minified or bundled CSS file. Usually CSS map files would be named after the CSS file names but with .map extension. For example, main.css might have its map file as main.css.map

What are Javascript Sourcemaps?

Similar to the CSS Source maps, even the JavaScript Source maps are source map files but for JavaScript. These would have reference to the JS code written in the original JavaScript file.

Why do I need a CSS / Javascript Source map?

We all want our sites to be fast and optimized and hence one of the most common optimization techniques we apply is to minify and bundle our CSS and JavaScript files. However, after these optimizations are done our multiple CSS or JavaScript files become one CSS or JavaScript file respectively. Hence, it becomes very difficult to know which CSS class was written in which file and on which line. Debugging becomes very difficult. There comes Source Maps to our rescue!

Using Source Map files, we can easily know which class was written in which file and on which line number. All the modern browsers support source maps for both CSS and JavaScript and we can utilize it through the inspect feature of the debugger console that ships with the browser. Let’s see how can we use the source maps.

How to use a source map?

Most of the modern browsers nowadays have inbuilt support for source map files. So if the source map files are available, on Inspecting an element using the developer tools shipped with the browser, it would show you the name of the file and line number where the code is written.

For example, let’s try an example using chrome :

Visit https://getbootstrap.com/getting-started/ (Bootstrap’s download page) and inspect the “Download” page heading. You can see that it has a class named “page-header” and under the “styles” tab on the right you can see that the class is defined in a file named “type.less” on line number 158 (at the time I wrote this) . Please see the screenshot below :

How to use Source Maps
Example of CSS Source map on Bootstrap v3.3.7 website

Now, if you notice there is no “type.less” file included on the page anywhere. This is coming from the maps file they have defined which is bootstrap.css.map located on the same path where bootstrap.css file is located. But how did the browser know this? Let check that out.

How to intimate browser that source map for a file is available?

There are different ways through which you can intimate the browser that the Source Map file for a file is available:

1. Through comment :
You can include a comment in a CSS or JS file which intimates the browser that the map file is also available and the path to it.
The Syntax for it is :

 /*# sourceMappingURL=/path/to/thefile.css.map */

For example in the case of Bootstrap.css you can find the comment referring to the SourceMaps file at the end as follows:

 /*# sourceMappingURL=bootstrap.css.map */ 

This way the browser recognizes that the source map file is located in the same folder as the CSS file but with the file name as bootstrap.css.map .

2. Through header information :
You can also send this information through the header information of the compiled CSS or JavaScript file. The header should have the following :

X-SourceMap: /path/to/thefile.css.map

This can help you avoid the comment at the end of the CSS/JavaScript files.

Please note that the Source map file would be downloaded by the browser only if the Source maps are enabled and the developer tool is open.

How to generate source maps ?

You can generate source maps through different ways. Ideally, you would like to do it using the same compiler that you used to compile your SASS/LESS files (if using any of those CSS Preprocessors). Else you can also use many other compilers that you might use to minify and bundle the CSS/JavaScript files. Some of the most common ones are :

NodeJs Modules like generate-source-map .

You can refer to their page for more details.

If you are using Webpack please refer https://webpack.js.org/configuration/output/#outputsourcemapfilename for more details on How to generate source map file using Webpack.

If you are using GulpJs you can refer https://www.npmjs.com/package/gulp-sourcemaps for more details on How to generate Source maps using GulpJs .

If you are using LESS / SASS, during the compile time itself you can pass parameters to the command to generate the source maps file.
So say if you are using LESSC compiler you can use the following command

 lessc --source-map=filename.map


lessc --source-map

# compile bootstrap.less to bootstrap.css with the map file as bootstrap.css.map

$ lessc bootstrap.less bootstrap.css --source-map

If you don’t provide a file name, it would use the output file’s name with a .map extension.

To conclude, I would say that source maps are playing a significant role in helping debug compressed or bundled files. With the trend being to optimize the websites, it becomes very important to minify and bundle the CSS and JS files, and once we do that we would definitely require source maps to debug it. You can use a compiler of your choice however, I would suggest to you the same ones that you use to compile, compress or bundle the CSS/ JS if they support it. Well, so go ahead try out generating source maps.