iTechGuides is reader-supported. When you buy through links on our site, we may earn an affiliate commission. As an Amazon Associate I earn from qualifying purchases. Learn more
Angular CLI builders are task handlers that Architect runs to perform work such as building, testing, or serving an Angular project. To create a custom builder, package its handler with an option schema and builder manifest, register it as a target in angular.json, and run that target with ng run.
What Angular CLI builders do
Angular CLI uses Architect to schedule and run complex workspace tasks. Architect delegates a task to a builder: a handler function that receives an options object and a BuilderContext. The context provides runtime information and APIs, including the ability to schedule other targets.
A builder handler can return a result synchronously, as a Promise, or as an Observable when it needs to emit repeated results. The result is a BuilderOutput, which includes a success flag and may include an error. Angular describes the API as a way to change CLI behavior by using builders to execute custom logic (Angular CLI builders).
Recommended Free Tools
How to create a custom builder package
A custom builder package brings together the handler implementation, a schema that defines accepted options, a manifest that connects the builder name to those files, and package metadata that exposes the manifest. Angular’s guide demonstrates this with TypeScript and createBuilder() from @angular-devkit/architect.
#1 Best Overall
1. Implement the handler
Create a TypeScript file for the task, for example src/my-builder.ts. The handler receives its options and context, performs the task, and returns a BuilderOutput. It may return a Promise for a one-time result or an Observable for ongoing results. The guide’s example uses a Promise.
2. Define and validate options
Add a JSON schema, such as src/schema.json, to describe the options the handler accepts. The schema is more than documentation: Architect validates resolved builder inputs against it before execution. Keep the schema aligned with the handler’s expected option names and types.
3. Map the builder name to its files
Add a builders.json manifest entry that gives the builder a name and points to its implementation and schema. The package name and builder name together form the identifier used in a workspace target: package-name:builder-name.
Outdated Drivers Are Slowing You Down
One free scan finds every outdated or missing driver and matches the right update for your exact hardware.Free scan · exact hardware matchWindows Errors? Fix Them Before They Spread
Repair common Windows errors and clear accumulated junk for a smoother, more stable PC - no reinstall needed.Free scan · no reinstall4. Expose the manifest from the package
In package.json, set the builders field to the manifest path and include the package dependencies needed by the implementation. The official example also includes TypeScript configuration and a test file. A builder can be published as an npm package so a workspace can install and use it.
Register a builder as a workspace target
Angular workspace configuration lives in angular.json. Each project can define targets in its architect section. A target specifies its builder identifier, default options, and optional named configurations. For example, a target named copy-package might use @example/copy-file:copy and set source and destination defaults. This identifier is illustrative, not a claim about a specific published package.
Workspace configuration uses camelCase option names, while command-line flags use dash-case. For example, an option stored as outputPath in the workspace file is typically passed as --output-path on the command line. See Angular’s workspace configuration reference for the structure and naming rules.
Rank #3
How Architect resolves target options
When Architect schedules a target, it combines the target’s default options, the selected named configuration, and any scheduling overrides, in that order. CLI arguments act as overrides. Architect validates the final option set against the builder’s schema before running the handler.
Free tools Windows power users keep installed
One-click scans. No signup required.
There are two scheduling patterns to distinguish. scheduleTarget() resolves a workspace target and its configuration before applying overrides. scheduleBuilder() takes an options object directly and validates it, without resolving target configurations. Choose the first when one builder needs to invoke a configured workspace target; use the second when the builder should be given an explicit options object.
Run a builder target
Use Angular CLI’s ng run command with a project and target, optionally followed by a named configuration:
ng run project:target[:configuration]For the illustrative target above, run ng run builder-test:copy-package. To override the configured destination, pass a CLI option such as --destination=package-other.json. Consult the Angular CLI reference for command syntax and available options.
Choose and verify built-in build builders
Do not assume that every Angular project uses the same build builder. Angular’s current build guide lists these common choices; generated applications and libraries use the defaults shown, but an existing project’s actual target is the reliable source for what it runs.
| Builder identifier | Role and bundler | Generated-project default |
|---|---|---|
@angular/build:application |
Builds an application bundle and server, and supports build-time prerendered routes; uses esbuild. | Generated applications. |
@angular-devkit/build-angular:browser-esbuild |
Creates an esbuild browser bundle. | Not stated in the build guide. |
@angular-devkit/build-angular:browser |
Creates a webpack browser bundle. | Not stated in the build guide. |
@angular/build:ng-packagr |
Builds libraries in Angular Package Format. | Generated libraries. |
These roles and defaults are documented in Angular’s guide to building Angular apps. Before changing a build target, inspect the project’s build entry under architect in angular.json, then compare the output needed, application-versus-library use, bundler, supported options, and compatibility with the Angular release in use.
Migrate carefully when replacing a builder
There is no single migration recipe that applies to every builder. Compatibility depends on the Angular version, the builder package and its supported options, and the project’s existing configuration. Angular’s build-system migration guide specifically directs users of custom builders to the builder’s own documentation for migration options. Check those notes before swapping builders, and verify that the replacement supports the target’s required behavior and configuration.
Test the builder and clean up ongoing work
Angular recommends integration tests that execute the builder through Architect’s scheduler, so the test exercises it in an Architect context. Unit tests can separately check the task logic. If the handler returns an Observable, put resource cleanup in its teardown logic so subscriptions can end cleanly (Angular CLI builders guide).
Quick Recap
Product prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on Amazon at the time of purchase will apply.
