ngx-build-plus

Common errors

• NG8002: Unknown builder 'ngx-build-plus:browser'.

  cause The `angular.json` file is not correctly configured to use `ngx-build-plus` builders, likely due to a failed or incomplete installation.
  fix Run `ng add ngx-build-plus` in your project root to automatically update `angular.json` and install the package. Ensure the `--project` flag is used if targeting a sub-project.

• Error: Cannot find module 'webpack' when running ng build/serve with --extra-webpack-config.

  cause Your `webpack.partial.js` or custom config hook tries to `require('webpack')` but `webpack` is not installed as a direct dependency in your project.
  fix Install `webpack` as a development dependency: `npm install webpack --save-dev` or `yarn add webpack --dev`.

• Schema validation failed for the 'extra-webpack-config' option. Value "path/to/non-existent-config.js" is not a valid path.

  cause The path provided to the `--extra-webpack-config` flag is incorrect, the file does not exist, or the file is malformed (e.g., not exporting a valid webpack configuration object).
  fix Verify the path to your `webpack.partial.js` (or similar) file is correct and that the file exports a standard webpack configuration object. Check for typos in the file path or name.

• The `single-bundle` option (or `keepPolyfills`, `keepStyles`) is not producing the expected output after upgrade.

  cause The default behavior of these options changed in major versions (e.g., `single-bundle` in v7, `keepPolyfills`/`keepStyles` in v9).
  fix Explicitly set the affected option in your `angular.json` builder options or via the CLI flag (e.g., `--single-bundle=true`, `--keepPolyfills=false`) to enforce the desired behavior, overriding the new defaults.

Warnings

• breaking The `single-bundle` switch default behavior changed from `true` to `false` in version 7. This aligns `ngx-build-plus` with the Angular CLI's default multi-bundle behavior.
  Fix: Explicitly set `--single-bundle=true` or `--single-bundle=false` when running `ng build` to maintain desired bundling behavior after upgrading.
• breaking The `--keepPolyfills` and `--keepStyles` options now default to `true` since version 9. This change was introduced to avoid confusion and ensure polyfills and styles are retained by default.
  Fix: If you relied on polyfills or styles being removed by default, you must now explicitly set `--keepPolyfills=false` or `--keepStyles=false`.
• gotcha ngx-build-plus is tightly coupled to Angular CLI and Angular versions. Always ensure you install the `ngx-build-plus` version that matches your project's Angular/CLI major version (e.g., ngx-build-plus@^20 for Angular 20).
  Fix: Refer to the `ngx-build-plus` README or `npm` registry for the correct version mapping. Use `ng update ngx-build-plus` to upgrade gracefully.
• gotcha The recommended way to install and configure ngx-build-plus is by using `ng add ngx-build-plus`. This command automatically updates your `angular.json` to use the custom builders.
  Fix: Avoid manual `npm install ngx-build-plus` followed by manual `angular.json` edits, as this can lead to misconfigurations. If manual installation was done, ensure `angular.json` builder entries are correctly updated.
• gotcha Custom webpack configurations specified via `--extra-webpack-config` are only applied if the flag is explicitly provided during `ng build` or `ng serve`.
  Fix: Always include `--extra-webpack-config path/to/webpack.partial.js` in your `ng build` or `ng serve` commands, or define it in a `package.json` script, to ensure your custom webpack logic is applied.

Install

• npm install ngx-build-plus npm
• yarn add ngx-build-plus yarn
• pnpm add ngx-build-plus pnpm

Imports

• Builder Configuration
  wrong:

  In angular.json: "builder": "@angular-devkit/build-angular:browser"

  correct:

  In angular.json: "builder": "ngx-build-plus:browser"

  ngx-build-plus replaces the default Angular CLI builders (e.g., 'browser', 'dev-server', 'karma') in `angular.json` to inject its custom capabilities.
• webpack module

  const webpack = require('webpack');

  Used within custom `webpack.partial.js` or similar configuration files to access the webpack API for plugins or configuration. These files are typically CommonJS modules.
• Config Hook Function

  In angular.json options: "configHook": "path/to/my-webpack-hook.js"

  References a JavaScript file that exports a function, specified in the `angular.json` builder options, allowing programmatic modification of the webpack configuration.

Quickstart

Demonstrates how to add ngx-build-plus, create a partial webpack configuration (`webpack.partial.js`) to define a global `VERSION` constant, integrate it into an `app.component.ts`, and apply it to an Angular project via `ng serve --extra-webpack-config webpack.partial.js -o` after running `ng add ngx-build-plus`.

const webpack = require('webpack');

module.exports = {
    plugins: [
        new webpack.DefinePlugin({
            "VERSION": JSON.stringify("4711")
        })
    ]
};

// src/app/app.component.ts
import { Component } from '@angular/core';

declare const VERSION: string; // Declare global variable defined by webpack

@Component({
    selector: 'app-root',
    template: `<h1>{{ title }}</h1>`,
    styles: ['h1 { color: blue; }']
})
export class AppComponent {
    title = 'Version: ' + VERSION;
}