Anatomy of Angular Builders

Essentially, Angular builders are NodeJS scripts executed by Angular CLI and perform different tasks like application build, running unit tests, and many other useful things. Even if you hear first time about them, in fact, you use them every day without even knowing that.

In this article, I wanted to demystify this topic and explain to you how Angular CLI resolves and executes builders, so you will get a better understanding of what is going on under the hood when we run commands like ng build , ng serve, etc. So let’s move on!

When you run a command ng build, Angular CLI goes first into the angular.json file that is available in the root folder of every Angular application. Here it tries to resolve a corresponding architect target with the name build.

Like each architect target, the build target has another option called builder. This property points to the script that has to be executed when the corresponding architect target is executed 👇

If we have a closer look at it, you may notice that the builder string consists of 2 parts separated by :(column), namely, we have a line @angular-devkit/build-angular and browser. The first string points to the NPM package where the actual builder is located and the second one is the name of the builder which needs to be executed.

But how does Angular CLI resolve the proper builder script from it? Good question!

Well, currently Angular CLI knows 2 important things – where the builder is located and what is the builder’s name. So it goes to the NPM package and looks into its package.json file. Then it looks for a specific field that needs to be defined and its name builders.

As you can see, this property points to a JSON file named builders.json (but it can be any name) and that JSON file describes all available builders that exist in this package. Angular CLI follows it and goes to that file and if you do it as well you will see something similar to it.

Here, each key under the builders property is actually the name of the builder and as you can see, the second one has the browser name – exactly what was defined in the angular.json file in the very beginning.

Ok, since the corresponding builder was found, let’s figure out what properties it has and what those properties are responsible for.

description – This field contains a message that describes what this builder does and it appears when you run e.g ng build --help command.

implementation – this field points to the NodeJS script that will be eventually executed and will build the application for us. This is exactly the script that Angular CLI will eventually execute.

schema – this field points to the JSON file that describes a list of options that can be provided for the builder function in the builder script (defined in the implementation). Besides that, it describes the option’s type (string, number, etc) as well as default values and many other things.

For instance, here you can see how the property assets is described for the browser builder:

And this is exactly the property that you define in your angular.json file in the options property of the corresponding build architect target.

And this is it! Now Angular CLI knows everything it needs to execute a proper NodeJS script with proper options and it just executes it! As easy as that! As you can see there is no magic behind this process and now it looks quite trivial.

I hope you enjoyed the article and learned something new today. If you want to know more information about this topic and are willing to learn how to build your custom builder, then please check out my new video about this topic.