How to Debug the Original React Source Code Using VSCode and Sourcemaps

When a frontend engineer wants to dive into the internals of React, the usual approach of debugging react-dom.development.js feels distant from the original source because the logic is split across multiple packages and the compiled file lacks direct mappings.

The solution is to build React from its source with sourcemap support and configure VSCode to use those maps. First, create a React project with create-react-app and add a .vscode/launch.json configuration that launches Chrome in debug mode, pointing to the development server URL.

Understanding sourcemaps is essential: during compilation a # sourceMappingURL=… comment links the generated code to the original source lines, allowing debuggers to translate positions back to the original files.

To obtain a React bundle with sourcemaps, clone the repository ( git clone https://github.com/facebook/react ) and modify ./scripts/rollup/build.js . Enable sourcemap: true in the Rollup configuration and comment out four plugins that prevent sourcemap generation (the strict‑mode remover, the production minifier, the Prettier formatter, and the license header injector). Then run npm run build to produce react and react-dom packages that include proper sourcemap files.

Next, prevent CRA’s webpack from bundling these packages by ejecting ( npm run eject ) and adding react and react-dom to the externals section of the webpack config. Place the built react.development.js and react-dom.development.js files in the public folder and load them via <script src="react.development.js"></script> and <script src="react-dom.development.js"></script> in index.html .

Because debuggers only resolve a sourcemap once, the React packages must expose their original source directly. Adjust the sourcemap paths in the Rollup build script to use absolute paths (e.g., map ../../../packages to the actual workspace path). After rebuilding, replace the old sourcemap files with the new ones.

Finally, open the project in VSCode, start the debugger, and the call stack will now point to the original React source files. Clicking a stack frame opens the exact file in the cloned React repository, providing a seamless and elegant debugging experience.

This workflow, although a bit involved, needs to be set up only once and can be reused for any React project, offering a powerful way to explore and understand the framework’s internals.