White Labeling in Angular: One Codebase, Multiple Clients

.
├── public/             ← default assets
│   ├── favicon.ico
│   └── main.png
├── src/            

← core application

└── targets/ ← defines all the brands └── angular/ ← contains the angular build specific files

### 2. Target Definition
Define the white-label target in `angular.json`. This registers the configuration without altering the default build behavior:

{ ... "projects": { "architect": { "build": { "builder": "@angular/build:application", "options": { ... }, "configurations": { "production": { ... },
"development": { ... }, "angular": { } } } } } } }

### 3. Asset Override Strategy
Angular's asset pipeline processes the `assets` array sequentially. When filenames collide, the last entry wins. This enables deterministic overriding without path mangling:

{ "angular": { "assets": [ { "glob": "/*", "input": "public" }, { "glob": "/*", "input": "targets/angular/assets" } ] } }

Apply this within the build configuration to activate during the target build:

{ "build": { "configuration": { "angular": { "assets": [ { "glob": "/*", "input": "public" }, { "glob": "/*", "input": "targets/angular/assets" } ] } } } }

### 4. Style & CSS Variable Injection
Leverage CSS custom properties for theme isolation. Define defaults in the core app, then override them in target-specific stylesheets:

/* 📂 theme.css */ :root { --brand-primary: black; }

/* 📂 styles.css */ html { color: var(--brand-primary); }

Reference base styles in the default options:

{ "build": { "configuration": { "options": { ... "styles": ["src/styles.css", "src/theme.css"] } } } }

For the angular configuration, append or replace the theme file in the `styles` array to inject brand-specific variables without modifying core CSS. Angular's build optimizer will tree-shake unused selectors and inline variables, ensuring zero runtime cost.

### 5. Build Execution
Trigger the isolated target build:

pnpm build --configuration angular

This produces a production-ready bundle containing the core application logic, with all assets, styles, and configuration keys strictly resolved from `targets/angular/`.

## Pitfall Guide
1. **Asset Override Order Dependency**: Angular resolves assets sequentially. If the target assets array is placed before the default `public/` array, defaults will overwrite brand-specific files. Always place target overrides last in the configuration array.
2. **CSS Specificity & Cascade Bleed**: Global styles in `src/styles.css` can unintentionally override target variables if specificity isn't managed. Scope brand variables to `:root` or component-level selectors, and avoid `!important` in core styles.
3. **Environment Key Leakage**: Using `environment.ts` for brand configs causes cross-target pollution. Use `fileReplacements` in `angular.json` configurations or inject configs via `APP_INITIALIZER` with build-time environment variables to guarantee isolation.
4. **Configuration Drift Across Targets**: Manually duplicating `angular.json` blocks for 10+ targets creates maintenance debt. Extract shared configuration into a base JSON and use Angular's `extends` or npm scripts to merge target-specific overrides.
5. **Overriding Core Business Logic**: White-labeling should only affect presentation, assets, and configuration. Injecting brand-specific services or routing logic into `src/` breaks the single-codebase principle. Keep overrides strictly in `targets/` and use Angular's DI tokens for conditional injection.
6. **CI/CD Pipeline Fragmentation**: Hardcoding `--configuration` flags in deployment scripts leads to environment mismatches. Parameterize pipeline jobs using matrix builds or environment variables to dynamically map client IDs to Angular configurations.
7. **Bundle Size Bloat from Unused Assets**: Copying entire `targets/` directories without filtering can include development assets or unused images. Use precise `glob` patterns (e.g., `"glob": "*.{png,svg,ico}"`) and exclude source maps or config files from production targets.

## Deliverables
- **Blueprint**: Angular White-Label Architecture Matrix (`angular.json` configuration schema, `targets/` directory structure, asset/style override flow diagram)
- **Checklist**: Brand Onboarding & Build Validation (verify asset naming conventions, confirm CSS variable scoping, validate `fileReplacements` isolation, run `ng build --configuration <target>` dry-run, audit bundle for leaked assets)
- **Configuration Templates**: Ready-to-use `angular.json` configuration block, CSS variable setup for `:root` theming, `targets/` scaffold with `assets/` and `styles/` placeholders, CI/CD pipeline snippet for parameterized Angular builds