Reading Your Framework’s Source Code? Yes, You Can Do It
Dive Into React. Dive Into Angular. Don’t Be Scared. It Can Be Fascinating and Rewarding
Funnily enough, Form Validation is still a big thing, but unlike 18 years ago we have frameworks that help us with this. They also help us to break down our applications to smaller, reusable components, update the screen to reflect changes in the data model, and basically solve a set of problems that are common to many Web applications.
Angular, Vue.js, React — you have probably used at least one. But ever you ever stopped to look behind the scenes? Have you ever checked the source code of the framework that you use?
Use the Source, Luke!
Web Frameworks expose an API which help you structure your code and abstract away some of the Web APIs. When was the last time you called the
setAttribute() method directly on a DOM node? The framework does this for you.
Abstraction is usually great, as it help us focus on the problem we want to solve, and not on the implementation details, and it also allows changing the underlying implementation while reusing existing code. Think react-native.
However, abstraction also comes at a price: we can no longer be certain what is going on behind the scenes. For instance, when Alex Castillo and I prepared our VR Hero talk, we tried to integrate Angular with A-Frame. It worked pretty well, until we wanted to pass an object from Angular to an A-Frame element. Angular has some assumptions about how
setAttribute() works, and thus it was converting the value into a string. We had to dig into Angular’s source code in order to figure this out (and work around it).
Digging into your Framework’s Source Code is not only helpful when something goes wrong and you want to debug it. You can also learn a lot by looking at the implementation details and by reading the comments in the source code. In fact, this is how Max, Wizard of the Web started AngularInDepth, by looking at the source code of Angular, seeing how it behaves, and documenting his observations. You can check out his article about Reverse Engineering Web Frameworks for some great tips.
How To Approach The Source Code?
You will start with finding the source code for your framework. Quick googling will probably point you are the correct GitHub repository, but I will list them below to save you some time:
The next step would be to clone the source code. Sure, you can browse it on GitHub, but cloning, installing the dependencies (using npm or yarn), and opening it in your familiar code editor (Visual Studio Code, WebStorm, etc.) will make your life much easier navigating and searching the source code.
If we go with Angular for example, we can clone it by typing:
git clone https://github.com/angular/angular
After you obtained a local copy of the code, install the dependencies with npm (or yarn), and take a few minutes to familiarize yourself with the structure of the project. All of the frameworks comprise several different modules, and both React and Angular use a mono-repo structure.
The best way to find your way around is to look at the documentation. For instance, the CONTRIBUTING file in the Vue repository has a specific section explaining the project structure. React has a great guide explaining some important concepts and how to code is organized.
What Are You Looking For?
Once you have a good idea of how the project is organized, it is time to ask yourself what you want to find. Perhaps you want to know how Angular implements
ngIf, because you want to implement your own conditional directive?
By looking at the docs, we can tell that
ngIf is defined in
@angular/common module. This would map to
packages/common/src inside the Angular repo. We can look at the files there and try to determine which one is likely to be the definition of
ngIf. We know it is a directive, so looking inside the
directives folder makes sense, and then, inside, we see a file called
ng_if.ts — Voila!
Alternatively, we could also try to locate the source code for
ngIf by searching for the text
[ngIf] inside the repo, as it might appear in the selector string inside the directive definition.
Another example would be finding the implementation of
setState() in React. This is part of the core react package, so we will look inside
packages/react/src. Running a quick search for the method name reveals its location, inside a file called
ReactBaseClasses.js where the
Component class is defined. By looking at the source code for the function, we can see it delegates the actual work to another method, called
If you look for
enqueueSetState, you will find there are several different implementations. You are invited to keep exploring and share your findings!
How To Get Help?
All these frameworks are pretty large projects. They sometimes do crazy optimizations, such as Angular’s Compiler (and now also Ivy), or React’s Virtual DOM and Fiber. Reading the documentation, the comments in the source code, and sometimes also blog posts can be a great starting point. Then, you can look for the unit tests for the code you are trying to understand.
Here is a nice trick you can use to quickly figure out which unit-test cases are relevant to the piece of code you are trying to understand: simply modify the code to throw an exception. This will cause most of the unit tests that depend on this code to fail, and you will be able to spot them. For me, unit tests are another form of documentation: they explain how the code in question behaves, and sometimes also why it does what it does.
Finally, if you still have a piece of code you can’t figure out, I suggest to publish a short document describing what you discovered so far. Joshua Comeau did this a few years ago, when he explored react’s source coding — publishing his finding every single day.
I found out that when you share what you already know, people are willing to dive in and fill the gaps. You can then open an issue on Github, or ask on for help on StackOverflow, Reddit, Slack, etc.
It’s Time To Start Exploring!
I gave you some pointers how to get started, and now its your turn. Which framework do you use at work? I challenge you to schedule two hours in your calendar and just go through the source code, looking at how the features you use are implemented. You will learn something new, I promise!