@presencelearning/angular-builders

Angular CLI builders that wrap @angular/build (esbuild) with automatic process.env replacement from .env files and shell environment variables.

Why

Angular’s esbuild builder (@angular/build:application) supports a define option for compile-time replacements, but requires you to manually specify every process.env.KEY value. This builder automates that by:

1. Scanning your environment TypeScript file for process.env.KEY and process.env['KEY'] references
2. Resolving values from shell env vars → .env.local → .env (in priority order)
3. Merging with any static define entries in angular.json
4. Falling back to undefined for unset variables so runtime defaults work

Installation

npm install --save-dev @presencelearning/angular-builders

Usage

Replace the default Angular builder in angular.json:

{
  "projects": {
    "my-app": {
      "architect": {
        "build": {
          "builder": "@presencelearning/angular-builders:application",
          "options": {
            ...
          }
        },
        "serve": {
          "builder": "@presencelearning/angular-builders:dev-server",
          "options": {
            ...
          }
        }
      }
    }
  }
}

Environment file

The builder automatically detects which environment file is active via fileReplacements:

src/environments/environment.staging.ts

export const environment = {
  apiUrl: process.env['API_URL'] || 'https://default-api.example.com',
  featureFlag: process.env.FEATURE_FLAG === 'true',
};

Resolution order

Values are resolved with this precedence (highest first):

1. Shell environment variables — API_URL=https://api.example.com ng build
2. .env.local — Local overrides (git-ignored)
3. .env — Shared defaults
4. define in angular.json — Static build configuration
5. undefined — Fallback (allows || defaults in your environment file)

Static defines

You can still use the define option in angular.json for values that don’t come from env:

{
  "configurations": {
    "staging": {
      "define": {
        "process.env.FEATURE_FLAGS_STRATEGY": "\"local\""
      }
    }
  }
}

Shell/.env values always take precedence over static defines.

Builders

@presencelearning/angular-builders:application

Drop-in replacement for @angular/build:application. Accepts all the same options.

@presencelearning/angular-builders:dev-server

Drop-in replacement for @angular/build:dev-server. Injects env defines into the build target options before serving.

Compatibility

Supports Angular 18, 19, and 20.

Angular Version	@angular/build	@angular-devkit/architect
18.x	18.x	0.18xx.x
19.x	19.x	0.19xx.x
20.x	20.x	0.20xx.x

The consuming Angular application must have @angular/build and @angular-devkit/architect installed (they come with any standard Angular CLI project). The builders resolve these from the host app’s node_modules at runtime.

Note: These are not declared as peerDependencies because GitHub Packages’ registry API does not support peerDependenciesMeta, causing npm to install the latest major version and create conflicts with the host app’s Angular version.

---

Source: packages/angular-builders