A Quick Guide To Reading Node.js Core Source

Rich Trott

·

Follow

2 min read

·

Mar 24, 2016

--

2

Listen

Share

Here’s how I’ve approached understanding the source code that makes up Node.js core. This is what has worked for me. Your mileage may vary. Warranty void if seal is broken.

The source code can be found at https://github.com/nodejs/node.

This assumes that you are a JavaScript developer approaching the project. If you are a C++ programmer, for example, your path will likely be different.

Here we go!

1. Make sure you understand Node.js a little bit. I mean, you know, do a few simple programs first before looking at core. Presumably, you’ve done that, so let’s move on.
2. Start with the docs for APIs. Pick one you are particularly interested in and read through it. Or read through all of them. At the time of this writing, these documents can be found at https://nodejs.org/dist/latest-v5.x/docs/api/. Or you can read the markdown directly in the source tree at https://github.com/nodejs/node/tree/master/doc/api. Or you can read them from the `doc/api` directory in your local copy of the source code.
3. There is an excellent chance that by now, you have found a small typo, omission, or other problem with the docs. Hey! This is an opportunity to get familiar with the Node.js contribution process. You can skip this step if you just want to understand the code only and not participate in the project. But otherwise: Read up on how to submit a change at https://github.com/nodejs/node/blob/master/CONTRIBUTING.md.
4. Remember step 2 where you read some docs for APIs? Now it’s time to read the source for the API that interests you. Let’s say you’re all about `http`. Look in `lib/http.js`. When you come across stuff you don’t understand — what is `process.binding`? — look it up in the docs. Or ask on the #node-dev channel on freenode.
5. Whatever you were looking at (let’s say `http`), now read all the tests for that in `test/parallel` and `test/sequential`.
6. Take a peek at some of the dependencies in the `deps` folder. Which ones may depend on what you are interested in and whether you love or loathe reading C++. The ones that offer the most insight into how everything works may be `npm` (package manager implemented in JavaScript), `uv` (short for `libuv` which is a C library that Node.js uses to interact with the underlying operating system), and `v8` (the JavaScript engine that Node.js uses which is written in C++).

At this point, there’s still a lot of stuff that hasn’t been covered. But hopefully you’ve got a good start. Or maybe this is a terrible script for you and you will try something else and write your own Medium post and it will make this one obsolete. Surely, it will have a better concluding paragraph than this one.