How to Manually Add a Source Map in Chrome DevTools

To manually add a source map to a processed file you are debugging in Chrome DevTools, you need to follow a specific process involving both preparation outside DevTools and steps within the browser's developer tools. This is particularly useful when source maps aren't automatically linked to your deployed files.

The Manual Source Map Addition Process

Manually adding a source map in DevTools allows you to view and debug your original source code files (like .js, .css, or preprocessor files) even after they have been minified, bundled, or compiled. This greatly improves the debugging experience.

The process, as outlined, involves a few key steps:

1. Generate Source Maps: Ensure your build tools (like Webpack, Rollup, Parcel, or transpilers like Babel, Sass compilers) are configured to produce source map files (often .map files) alongside your compiled or minified code. This is the essential first step, as you cannot add a source map that doesn't exist.
2. Host the Source Maps: Make sure the generated source map files are accessible to your browser. Typically, you host them on your web server alongside your deployed code. While the browser can usually fetch them automatically if linked correctly (via a sourceMappingURL comment), manually adding them requires them to be available somewhere the browser can access, even if not linked automatically.
3. Open DevTools and Enable Source Maps:
   • Navigate to the web page containing the code you want to debug.
   • Open Chrome DevTools (usually by right-clicking on the page and selecting "Inspect" or pressing F12 / Cmd+Option+I).
   • Go to the Sources panel.
   • Ensure that source maps are enabled. This is usually a setting within DevTools (often found in DevTools Settings > Preferences > Sources > "Enable JavaScript source maps" and/or "Enable CSS source maps"). Make sure these are checked.
4. Locate the Deployed File: In the Sources panel, navigate the file tree to find the deployed, processed file you want to debug (e.g., a minified script.min.js or style.min.css).
5. Add the Source Map:
   • Right-click on the tab or name of the deployed file open in the Editor pane of the Sources panel.
   • From the context menu that appears, select the option Add source map....
   • A dialog box will appear asking for the URL or path to the source map file associated with the deployed file. Enter the correct URL or local path.
   • Click Apply or OK.

Once successfully added, DevTools should now be able to match the code in the processed file back to your original source code, allowing you to set breakpoints and step through the familiar, unminified code.

Summary Table

Step	Description	Prerequisites
Generate Source Maps	Configure build tools to create .map files.	Build tools configured for source map output.
Host Source Maps	Make .map files accessible via URL or local path.	Web server or local file access.
Open DevTools & Enable	Launch DevTools, go to Sources panel, and check source map settings.	Chrome DevTools open.
Locate Deployed File	Find the target processed file (e.g., bundle.js) in the Sources panel.	File loaded in the browser and visible in Sources.
Right-click & Add Map	Right-click the file in the Editor and select "Add source map...".	Source map URL/path ready.

Manually adding source maps is a useful fallback method when automatic detection via sourceMappingURL comments fails or is intentionally omitted in deployment for certain environments, but you still need to debug the deployed code effectively.