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

The first web application I ever wrote was a Forum system. I wrote it back in December 2000 using a programming language called Tcl. Back at the time, Web applications consisted mainly of code that ran on the server side. In fact, looking back at the source code, I see it only contained only 50 lines of JavaScript code doing form validation. I didn’t even write this code — according to the comments, it was written by my friend Oshri Adler.

So 18 years ago, I didn’t even pay attention to JavaScript — it was just a toy language whose whole purpose was checking if the entered email address seemed valid and shouting at the user if not, or swapping button images when the mouse went over them. Fast forward 18 years and JavaScript is huge. We build enormous applications, consisting of millions of line of JavaScript code. And don’t even get me started on JavaScript and IoT.

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?

Once upon a time, source code was published in books

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.

And it is not only about the frameworks — nowadays, most of the tooling we use is written using JavaScript and is open source. For instance, when I engineered TypeWiz, I based my implelementation on what I learnt from looking inside the source code for tslint.

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 enqueueSetState.

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!

As a final note, I want to thank Netta Bondy for the idea to write this blog post. It popped into my mind during her talk at Reversim Summit last week, Deeper Than Abstractions. Thank you Netta!


This is the 18th post in my Postober Challenge — writing something new every single day throughout October.

I will tweet whenever I publish a new post, promise! ✍