Angular CLI custom builder

Question

Angular CLI 6 introduced a new concept of builders (aka Architect Targets).
There are a couple of prebuilt builders that come with @angular-devkit/build_angular, but unfortunately there is no documentation that explains how to create your own builder.

How do I create my own builder (for example to modify the underlying webpack configuration)?

Answer 1

Update:

For Angular 8+ read this AngularInDepth article.

For Angular 6 and 7:

The full article can be found here.

For the sake of simplicity I assume that the new builder is implemented in Typescript, but it can be implemented in pure JavaScript as well.

Implementation:

1. Create a directory for your custom builders (for example custom-builders) in the root of your project (or alternatively install it as a local npm module)
2. Inside the directory create a file called builders.json, index.ts and package.json that contains builders entry pointing to builders.json
3. Inside custom-builders create a directory for the builder you want to implement (say, custom-builders/my-cool-builder
4. Add index.ts, schema.json and schema.d.ts to my-cool-builder directory
5. Populate schema.json with the schema of your builder options. See an example here.
6. Define your schema.d.ts according to the schema.json you defined. See an example here.

7. Implement your builder in my-cool-builder/index.ts. The builder has to implement the following interface:

   export interface Builder<OptionsT> {
     run(builderConfig: BuilderConfiguration<Partial<OptionsT>>):  Observable<BuildEvent>;
   }
   

   While BuildEvent is this:

   export interface BuildEvent {
     success: boolean;
   }
   

   BuilderConfiguration is this:

   export interface BuilderConfiguration<OptionsT = {}> {
     root: Path;
     sourceRoot?: Path;
     projectType: string;
     builder: string;
     options: OptionsT;
   }
   

   And OptionsT is the interface you defined for your builder options in schema.d.ts

   You can use browser architect target as a reference.

8. Once implemented, add your builder to builders.json:

   {
     "$schema": "@angular-devkit/architect/src/builders-schema.json",
     "builders": {
       "cool-builder": {
         "class": "./my-cool-builder",
         "schema": "./my-cool-builder/schema.json",
         "description": "My cool builder that builds things up"
       }
     }
   }
   

Usage:

In your angular.json:

    "architect": {
        ...
        "build": {
                  "builder": "./custom-builders:cool-builder"
                  "options": {
                         your options here
                  }

Example

For the full example check out this library: https://github.com/meltedspark/angular-builders

Answer 2

For those who use Angular 8 and higher, builders API is now officially supported and documented: https://angular.io/guide/cli-builder

It has a lot of changes compared to the previous version, so migration from Angular 7 to 8 might become complicated if you are using undocumented Architect API.

Here's a nice article to get started: https://blog.angular.io/introducing-cli-builders-d012d4489f1b