Builders

ng build  →  finds the "build" target in angular.json           →  loads the builder named in that target's "builder" field           →  passes validated options to the builder function           →  streams BuilderOutput events back to the CLI

// package.json — pre-Architect era{  "scripts": {    "build": "tsc && cp -r src/assets dist/assets",    "build:prod": "tsc -p tsconfig.prod.json && uglifyjs ...",    "test": "karma start karma.conf.js",    "lint": "tslint src/**/*.ts"  }}

ng build my-app --configuration=production         │         ▼Architect reads angular.json:  project "my-app"  → target "build"  → builder "@angular/build:application"  → options: { outputPath, index, browser, ... }  → configurations.production: { optimization: true, sourceMap: false, ... }         │         ▼Architect merges: base options + production config overridesValidates merged options against the builder's schema.json         │         ▼Architect loads the builder module, calls:  builderFn(mergedOptions, context)         │         ▼Builder runs (esbuild bundles, emits progress via context.reportProgress)Builder returns Promise<BuilderOutput> → { success: true }         │         ▼CLI reports success / failure

// angular.json{  "projects": {    "my-app": {      "architect": {        "build": {          "builder": "@angular/build:application",          "options": {            // Merged into every configuration — defaults            "outputPath": "dist/my-app",            "index": "src/index.html",            "browser": "src/main.ts",            "polyfills": ["zone.js"],            "tsConfig": "tsconfig.app.json",            "assets": [              { "glob": "**/*", "input": "public" }            ],            "styles": ["src/styles.scss"],            "scripts": []          },          "configurations": {            "production": {              // Only these keys override the base options above              "budgets": [                { "type": "initial", "maximumWarning": "500kB", "maximumError": "1MB" }              ],              "outputHashing": "all",              "optimization": true,              "sourceMap": false,              "namedChunks": false            },            "development": {              "optimization": false,              "extractLicenses": false,              "sourceMap": true,              "namedChunks": true            },            "staging": {              // Extend production, then override specific keys              "optimization": true,              "sourceMap": true    // source maps in staging but not production            }          },          "defaultConfiguration": "production"        },        "serve": {          "builder": "@angular/build:dev-server",          "options": {            "buildTarget": "my-app:build"          },          "configurations": {            "production": { "buildTarget": "my-app:build:production" },            "development": { "buildTarget": "my-app:build:development" }          },          "defaultConfiguration": "development"        },        "test": {          "builder": "@angular/build:unit-test",          "options": {            "buildTarget": "my-app:build:development",            "tsConfig": "tsconfig.spec.json"          }        },        "extract-i18n": {          "builder": "@angular/build:extract-i18n",          "options": {            "buildTarget": "my-app:build"          }        }      }    }  }}

ng run my-app:build                   # uses defaultConfigurationng run my-app:build:production        # explicit configurationng run my-app:build:staging           # custom configurationng build --configuration=staging     # shorthand for ng run my-app:build:staging

my-builders/├── src/│   └── deploy/│       ├── index.ts          ← builder implementation│       └── schema.json       ← options schema├── builders.json             ← builder registry├── package.json              ← includes "builders": "./builders.json"└── tsconfig.json

{  "$schema": "@angular-devkit/architect/src/builders-schema.json",  "builders": {    "deploy": {      "implementation": "./src/deploy",      "schema": "./src/deploy/schema.json",      "description": "Deploy the built app to S3"    }  }}

// package.json{  "name": "my-builders",  "builders": "./builders.json"}

{  "$schema": "http://json-schema.org/schema",  "type": "object",  "title": "Deploy Builder",  "properties": {    "bucket": {      "type": "string",      "description": "The S3 bucket name to deploy to"    },    "region": {      "type": "string",      "description": "AWS region",      "default": "us-east-1"    },    "distFolder": {      "type": "string",      "description": "Path to the built app (relative to workspace root)",      "default": "dist/my-app/browser"    }  },  "required": ["bucket"]}

// src/deploy/index.tsimport {  BuilderContext,  BuilderOutput,  createBuilder,  targetFromTargetString,} from '@angular-devkit/architect';import { JsonObject } from '@angular-devkit/core';import { S3Client, PutObjectCommand } from '@aws-sdk/client-s3';import { readdir, readFile } from 'fs/promises';import { join } from 'path';
interface DeployOptions extends JsonObject {  bucket: string;  region: string;  distFolder: string;}
async function deployBuilder(  options: DeployOptions,  context: BuilderContext,): Promise<BuilderOutput> {  // 1 — log start  context.reportStatus(`Deploying to s3://${options.bucket}…`);  context.logger.info(`Region: ${options.region}`);
  // 2 — optionally invoke another builder first (e.g. build the app)  const buildTarget = { project: context.target!.project, target: 'build', configuration: 'production' };  const buildResult = await context.scheduleTarget(buildTarget);  const buildOutput = await buildResult.output.toPromise();  if (!buildOutput.success) {    return { success: false, error: 'Build failed before deploy' };  }
  // 3 — do the actual work  const distPath = join(context.workspaceRoot, options.distFolder);  const files = await readdir(distPath, { recursive: true });  const client = new S3Client({ region: options.region });
  let uploaded = 0;  for (const file of files) {    const content = await readFile(join(distPath, file));    await client.send(new PutObjectCommand({      Bucket: options.bucket,      Key: file,      Body: content,    }));    uploaded++;    context.reportProgress(uploaded, files.length, `Uploaded ${file}`);  }
  context.reportStatus('Done.');  return { success: true };}
export default createBuilder(deployBuilder);

// angular.json{  "projects": {    "my-app": {      "architect": {        "deploy": {          "builder": "my-builders:deploy",          "options": {            "bucket": "my-production-bucket",            "region": "eu-west-1",            "distFolder": "dist/my-app/browser"          },          "configurations": {            "staging": {              "bucket": "my-staging-bucket"            }          }        }      }    }  }}

ng run my-app:deploy               # production bucketng run my-app:deploy:staging       # staging bucket
# Before publishing — test locally by linkingnpm linkcd ../my-angular-projectnpm link my-builders

import { Observable } from 'rxjs';
function watchBuilder(  options: WatchOptions,  context: BuilderContext,): Observable<BuilderOutput> {  return new Observable(subscriber => {    context.logger.info('Watching for changes…');
    const watcher = startFileWatcher(options.glob, () => {      runTask(options, context)        .then(() => subscriber.next({ success: true }))        .catch(err => subscriber.next({ success: false, error: err.message }));    });
    // Teardown when the CLI user hits Ctrl+C    return () => {      watcher.close();      context.logger.info('Watcher stopped.');    };  });}
export default createBuilder(watchBuilder);

// ❌ Old — Webpack, slow cold builds"build": { "builder": "@angular-devkit/build-angular:browser" }"serve": { "builder": "@angular-devkit/build-angular:dev-server" }"test":  { "builder": "@angular-devkit/build-angular:karma" }
// ✅ New — esbuild/Vite/Vitest, 2–5x faster"build": { "builder": "@angular/build:application" }"serve": { "builder": "@angular/build:dev-server" }"test":  { "builder": "@angular/build:unit-test" }

// ❌ optimization in base — applies to ng serve as well"options": {  "optimization": true,   // dev builds are now minified and slow to debug  "outputPath": "dist"}
// ✅ optimization in production configuration only"options": {  "outputPath": "dist"},"configurations": {  "production": { "optimization": true }}

// ❌ Raw output — no formatting, ignores --verbose flagconsole.log('Building...');
// ✅ Structured logger outputcontext.logger.info('Building...');context.logger.warn('This option is deprecated');context.logger.error('Build failed');

// ❌ Error swallowed — CLI reports success even when the deploy failedtry {  await deploy(options);} catch (err) {  context.logger.error(err.message);}return { success: true };   // always returns success
// ✅ Return failure on errortry {  await deploy(options);  return { success: true };} catch (err) {  context.logger.error(err.message);  return { success: false, error: err.message };}