What are Source Maps?

In today’s world of modern web development, we don’t generally run the JavaScript or CSS code we write directly in the browser.

Because modern web applications use many different technologies that aren’t directly supported in the web browser, we need to translate our source code with a build process.

This build process can include many different steps, such as:

• Transpiling TypeScript to JavaScript
• Minifying JavaScript
• Bundling JavaScript files together
• Compiling Sass or other style frameworks to CSS

The end result of these different processes is a single JavaScript file that the browser can download and run. Typically, the JavaScript file has a .min.js extension, indicating that it has been minified.

From an end user’s perspective, this works great - the files are smaller and the application loads faster.

But as a front-end developer, what happens when we need to debug the application? Go ahead and take a look at the JavaScript file in the browser - it’s minified, and not very readable.

Source Maps to the Rescue

The bridge between the minified JavaScript and the original source code is the source map.

Source maps are files that map the minified JavaScript back to the original source code. This allows the browser to show you the original source code when you are debugging, even though the browser is running the minified JavaScript.

From a developer’s perspective, it’s as if you were working with your source code directly in the browser, even though the browser is running the minified JavaScript.

Source maps are generated by the build process, and are generally not included in the final build of the application. This is because the source maps can be quite large, and the browser doesn’t need them to run the application. You also run the risk of exposing sensitive information about your source code if you include the source maps in the final build.

What is in a Source Map?

A source map is a JSON file that contains the mapping between the minified JavaScript or CSS and the original source code.

Here are the first few lines of an example source map from a Vite+TypeScript+React application, formatted for readability - in practice, source maps are a single line of JSON:

{
  "version": 3,
  "file": "index-DMBE2hB0.js",
  "sources": [
    "../../node_modules/react/cjs/react.production.min.js",
    "../../node_modules/react/index.js",
    "../../node_modules/react/cjs/react-jsx-runtime.production.min.js",
    "../../node_modules/react/jsx-runtime.js",
    "../../node_modules/scheduler/cjs/scheduler.production.min.js",
    "../../node_modules/scheduler/index.js",
    "../../node_modules/react-dom/cjs/react-dom.production.min.js",
    "../../node_modules/react-dom/index.js",
    "../../node_modules/react-dom/client.js",
    "../../src/assets/react.svg",
    "../../../../../../../../vite.svg",
    "../../src/App.tsx",
    "../../src/main.tsx"
  ],
  "sourcesContent": [
    "/**\n * @license React\n * react.production.min.js\n *\n * Copyright (c) Facebook, Inc. and its affiliates.\n *\n * This source code is licensed under the MIT license found in the\n * LICENSE file in the root directory of this source tree.\n */\n'use strict';var l=Symbol.for(\"react.element\"),n=Symbol.for(\"react.portal\"),p=Symbol.for(\"react.fragment\"),q=Symbol.for(\"react.strict_mode\"),r=Symbol.for(\"react.profiler\"),t=Symbol.for(\"react.provider\"),u=Symbol.for(\"react.context\")"
    ...
  ]
  ...
}

The source map contains the following information:

• version - The version of the source map specification.
• file - The name of the minified JavaScript file.
• sources - An array of the original source files.
• sourcesContent - An array of the original source code for each file.
• sourceRoot - The root URL for the original source files.
• names - An array of the variable names used in the original source code.
• mappings - A string that maps the minified JavaScript back to the original source code.

Using Source Maps for Debugging

When you debug a web application in the browser, the browser can use the source map to show you the original source code when you are debugging.

Go into the Sources tab for Developer Tools, and you can see the original source code, even though the browser is running the minified JavaScript.

Hiding Source Maps in Production

You don’t want to include the source maps in the final build of the application, because they can be quite large and contain sensitive information about your source code.

Instead, you want to generate the source maps during the build process, and keep them separate from the final build of the application.

Once you have those source maps, they are useful for error reporting in production applications.

Every build tool has its own way of generating source maps, but typically you can enable source maps by setting a configuration option.

Here is an example of how you might enable source maps for Vite with the build.sourcemap option:

import { defineConfig } from 'vite'
import react from '@vitejs/plugin-react'

export default defineConfig({
  plugins: [react()],
  build: {
    sourcemap: true,
  },
})

Other build tools have similar configuration options to either enable or disable source maps. Hidden source maps are another option in many tools.

Uploading Source Maps for Error Reporting

When an error occurs in a production application, you can capture the exception with a reporting tool and send it to a third-party service like Rollbar or Sentry.

The service can then use the source map to translate the minified JavaScript back to the original source code, and show the developer the original source code where the error occurred.

Typically, you would enable this feature as part of your automated build process. You will need to verify that your source maps upload successfully to the error reporting tool, typically by forcing an error in your application.

Conclusion

Source maps operate behind the scenes in modern web development, allowing you to debug your applications even though the browser is running minified JavaScript.

Without source maps, debugging modern web applications would be much more difficult.