Debugging React Source Code with Webpack Alias and Custom CRA Configuration

When you need to debug the React source code, the usual approach of editing the compiled react-dom.development.js is cumbersome because changes require rebuilding. This article shows a workflow that lets you modify the original React source and see changes instantly.

1. Create a React project

npx create-react-app react-app

2. Download the React source

// download source
git clone [email protected]:facebook/react.git

// enter source directory
cd react

// install dependencies
yarn

3. Build the source files

// build files
yarn build react/index,react/jsx,react-dom/index,scheduler --type=NODE

// link react
cd build/node_modules/react
yarn link

// link react-dom
cd ../react-dom
yarn link

If the build fails, install JDK as the error indicates.

4. Link the built packages to the app

// after entering the react-app directory
yarn link react react-dom
// start the app
yarn start

Now the app uses the built react and react-dom packages.

5. Use webpack alias to point to the source

Modify config/webpack.config.js to replace the default alias configuration:

// before
alias: {
  'react-native': 'react-native-web',
  ...(isEnvProductionProfile && {
    'react-dom$': 'react-dom/profiling',
    'scheduler/tracing': 'scheduler/tracing-profiling',
  }),
  ...(modules.webpackAliases || {}),
},

// after
alias: {
  react: path.join(paths.appSrc, 'react/packages/react'),
  'react-dom': path.join(paths.appSrc, 'react/packages/react-dom'),
  shared: path.join(paths.appSrc, 'react/packages/shared'),
  'react-reconciler': path.join(paths.appSrc, 'react/packages/react-reconciler'),
},

Running npm start now shows many compilation errors, which we resolve step by step.

6. Fix import statements

In react-app/src/index.js change the imports to wildcard imports so that the aliased source files are used:

// before
import React from 'react';
import ReactDOM from 'react-dom/client';

// after
import * as React from 'react';
import * as ReactDOM from 'react-dom/client';

7. Adjust Scheduler constants

Replace references to Scheduler with SchedulerMock in react/packages/react-reconciler/src/Scheduler.js after importing it:

import * as SchedulerMock from 'scheduler/src/forks/SchedulerMock';
export const unstable_yieldValue = SchedulerMock.unstable_yieldValue;
export const unstable_setDisableYieldValue = SchedulerMock.unstable_setDisableYieldValue;

8. Disable ESLint

// react-app/config/webpack.config.js
// before
const disableESLintPlugin = process.env.DISABLE_ESLINT_PLUGIN === 'true';
// after
const disableESLintPlugin = true;

9. Replace environment variables

In config/env.js add explicit definitions for __DEV__ , __EXPERIMENTAL__ , and __PROFILE__ so the source can run without the build-time replacements:

const stringified = {
  'process.env': Object.keys(raw).reduce((env, key) => {
    env[key] = JSON.stringify(raw[key]);
    return env;
  }, {}),
  __DEV__: true,
  __EXPERIMENTAL__: true,
  __PROFILE__: true,
};

10. Fix the internal secret import

Replace the direct use of React.__SECRET_INTERNALS_DO_NOT_USE_OR_YOU_WILL_BE_FIRED with a proper import from the source file:

// before
const ReactSharedInternals = React.__SECRET_INTERNALS_DO_NOT_USE_OR_YOU_WILL_BE_FIRED;
// after
import ReactSharedInternals from 'react/src/ReactSharedInternals';

11. Shim the host config

In react-packages/react-reconciler/src/ReactFiberHostConfig.js replace the error‑throwing placeholder with an export that points to the DOM host config:

// before
throw new Error('This module must be shimmed by a specific renderer.');
// after
export * from "./forks/ReactFiberHostConfig.dom";

After applying all these changes, run npm start again. The remaining errors should be minimal, and the application will load correctly.

12. Live debugging

Now you can edit any React source file, such as react/packages/scheduler/src/SchedulerMinHeap.js , and the browser will automatically refresh, showing console output like the heap state. This setup provides a fast feedback loop for exploring and debugging the React codebase.