What are `*.js.map` files used for?

By opening your browser's developer tools, you may have already:

• Seen the download of a *.js.map file in your network tab
• Or on the contrary a warning in the console saying these files are missing

But what exactly are these files for, are they useful, or even essential? That's what we're going to find out today.

What is a "Source Map"?

When you minify source code, or transpile it from one language to another (Typescript for example), your deployed code is very different from the code you develop.

Several files are merged into one, variables are renamed, etc... The code is unreadable when debugging with the browser.

Mapping files are therefore files generated at the same time as the minified/transpiled code and contain the information needed to retrieve readable code.

In summary: Compiled code + Source Map = Source code

And it's thanks to this that your browser can show you the source code from the "sources" tab of your developer tools!

How does this work?

The first question that comes to mind is: "What's the point of minifying a file if we're serving a second file alongside it?"

In reality, *.js.map files are not downloaded automatically when the site loads, but only if your browser's developer tools are open!

So this doesn't add weight to your site during normal use!

Generating the Source Map

It's during the compilation of your code that your toolchain will (or won't) generate the source files, depending on the configuration provided.

For example, the Typescript compiler doesn't generate these files by default, and you'll need to add the compiler option "sourceMap: true" as indicated in the documentation.

Here's a minimal example of a generated .js.map file:

// index.js.map
{
  "version": 3,
  "file": "index.min.js",
  "sourceRoot": "",
  "sources": ["src/index.ts"],
  "names": [],
  "mappings": ";;AAAa,QAAA,UAAU,GAAG,IAAI,CAAA"
}

The purpose of this article is not to detail the complete anatomy of such a file, but if the subject interests you, here's a full article from bugsnag!

For your browser to know in advance that it's supposed to be able to download such a file to use it, it's necessary to add specific information to your generated file.

This information is a simple directive in the form of a comment in Javascript, containing the URL of the mapping file like this:

//index.min.js

...
//# sourceMappingURL=http://example.com/path/to/your/sourcemap.js.map

And if this directive is present but the corresponding mapping file is missing from the server, you'll get the following error in your console:

DevTools failed to load SourceMap: Could not load content for http://example.com/path/to/your/sourcemap.js.map: HTTP error: status code 404, net::ERR_HTTP_RESPONSE_CODE_FAILURE