Debugging React Source Code with a React Client App

#react #javascript

If you are looking to contribute to react or for that matter any large open source project, it can be a daunting task to understand such huge code bases, making sense of how to build it and run it locally and develop against it and fix bugs.

Today in this article we will tackle how to run the source code of react locally, and then create a create-react-app client and create a symlink between them, so that changing the source code of our local react package, can then be directly tested from the client app.

This is not specific to react, but in general really useful to learn if you are building libraries and packages and you would like to test it with a real world client app.

Before we start I would like to point you to the How to Contribute official documentation from the react team.

Setting up repos and symlink

Step 1: Clone/Fork the react repository to your local file system - git clone https://github.com/facebook/react.git
Step 2: Once you have cloned the repo, run npm install to install all its dependencies.
Step 3:
React repository uses yarn workspaces, which basically means, that they have divided the library into smaller re-usable packages, if you look at the package.json, you can see that there is a workspaces property which is an array, where they include everything inside packages folder, where they have the actual packages like react and react-dom etc.

We will take a closer look at the react codebase later.
Step 4: Build the react library - yarn build react/index,react/jsx,react-dom/index,scheduler --type=NODE, this command is going to build the react, react-dom and schedular package, you can simply run the build script to build all packages, but for our purposes we need only react and react-dom.
Step 5 : Once the build command successfully runs, you will see a build folder inside the root of the project, you will see that inside the build folder the packages we built are created inside the node_modules folder, and you will see react and react dom.

Step 6 : Create the symlinks, cd into the build/node_modules/react package and then from there run the command - yarn link
Step 7 : follow the same step for react-dom, cd into the react-dom folder and run yarn link.

Setting up the client app

Step 1 : Use create-react-app or any other scaffolding tool, I am using cra because its quite popular and scaffold a client app - npx create-react-app react-client. Do so in a different folder than where you cloned your react code.
Step 2: CRA runs yarn install for you, so if you run the app now, it will use the packages installed in your node modules, which has the react dependency from the online officially released version mentioned in your package json, but what we want is to use the built package we are currently working with. So here in the root directory of your client app run - yarn link react react-dom

That's it you have now successfully created a symlink from you client app to the locally cloned library.

Step 3 - Start the client app using yarn start, once the app runs open the debug window and checkout the path of the react library, it should point to your local build folder path and not the node_modules of your clients, and changes to your local library should reflect in the code your client app runs.

To give you some more details on how yarn/npm symlinks work refer to the image below -

With this you are now ready to make changes to the react code, build it and directly use it with hot reload and other goodness in your cra client app.

Hopefully this was helpful, feedback on the article would be appreciated.