Anatomy of Angular Builders

The Inner Workings of Angular CLI Builders

At their core, Angular builders are just NodeJS scripts that the Angular CLI invokes to carry out a range of operations—compiling the application, executing unit tests, and handling various other chores. Even if you've never heard the term before, you interact with these builders constantly, often without realizing it.

This post aims to peel back the layers and show you exactly how the CLI locates and runs these builders. By the end, you'll have a clear picture of the machinery that hums along whenever you fire off commands such as ng build or ng serve. Let's dive in.

The journey begins the moment you type ng build. The CLI immediately checks the angular.json file sitting in your project's root directory, hunting for an architect target labeled build.

Much like any architect target, the build entry includes a builder property. This value designates the exact script to be invoked whenever that target is triggered, as shown below.

Breaking that builder string apart, you'll spot two distinct chunks separated by a colon — for instance, @angular-devkit/build-angular and browser. The initial segment tells the CLI which NPM package contains the builder implementation, while the latter names the specific builder to run.

So, how exactly does the CLI translate that string into an actual executable script? An excellent question.

Equipped with those two pieces of information — the package location and the builder name — the CLI navigates into the relevant NPM package and inspects its package.json. Within that manifest, it looks for a designated field named builders.

That property, as you'll observe, references a JSON file (named builders.json in this case, though the filename isn't fixed). This file serves as a registry, cataloging every builder that the package exports. The CLI follows that path, and peeking inside that JSON reveals something like this.

Within the builders object, each key represents a builder's name. The one you care about here is browser — matching the string you initially declared in your angular.json.

Now that the correct builder is identified, let's examine what its definition entails and what each field accomplishes.

description — This supplies a human-readable explanation of the builder's purpose, which surfaces when you run commands like ng build --help.

implementation — This points to the NodeJS script that ultimately runs. It's the file that performs the heavy lifting, actually compiling your application.

schema — A reference to a JSON document outlining the options you can feed to the builder function defined in the implementation. Beyond listing the options, it also specifies their types (such as string or number), default values, and additional constraints.

Take, for instance, how the browser builder declares its assets option:

That's the same assets property you're already familiar with from the options section of your project's build architect target in angular.json.

And with that, the puzzle is complete! The CLI now has all the necessary details to locate the right script, supply the correct options, and execute it. There's truly no wizardry involved — just a straightforward, logical resolution process. Once you see it laid out like this, it all seems remarkably simple.

I trust you found this walkthrough enlightening. If you're curious to dig even deeper and learn how to craft a custom builder of your own, be sure to check out my latest video covering just that.