This executor is a drop-in replacement for the @angular-devkit/build-angular:browser-esbuild builder provided by the Angular CLI. It builds an Angular application using esbuild.

In addition to the features provided by the Angular CLI builder, the @nx/angular:browser-esbuild executor also supports the following:

  • Providing esbuild plugins
  • Incremental builds
Dev Server

The @nx/angular:dev-server executor is required to serve your application when using the @nx/angular:browser-esbuild to build it. It is a drop-in replacement for the Angular CLI's @angular-devkit/build-angular:dev-server builder and ensures the application is correctly served with Vite when using the @nx/angular:browser-esbuild executor.

Examples

The executor accepts a plugins option that allows you to provide esbuild plugins that will be used when building your application. It allows providing a path to a plugin file or an object with a path and options property to provide options to the plugin.

apps/my-app/project.json
1{ 2 ... 3 "targets": { 4 "build": { 5 "executor": "@nx/angular:browser-esbuild", 6 "options": { 7 ... 8 "plugins": [ 9 "apps/my-app/plugins/plugin1.js", 10 { 11 "path": "apps/my-app/plugins/plugin2.js", 12 "options": { 13 "someOption": "some value" 14 } 15 } 16 ] 17 } 18 } 19 ... 20 } 21} 22
apps/my-app/plugins/plugin1.js
1const plugin1 = { 2 name: 'plugin1', 3 setup(build) { 4 const options = build.initialOptions; 5 options.define.PLUGIN1_TEXT = '"Value was provided at build time"'; 6 }, 7}; 8 9module.exports = plugin1; 10
apps/my-app/plugins/plugin2.js
1function plugin2({ someOption }) { 2 return { 3 name: 'plugin2', 4 setup(build) { 5 const options = build.initialOptions; 6 options.define.PLUGIN2_TEXT = JSON.stringify(someOption); 7 }, 8 }; 9} 10 11module.exports = plugin2; 12

Additionally, we need to inform TypeScript of the defined variables to prevent type-checking errors during the build. We can achieve this by creating or updating a type definition file included in the TypeScript build process (e.g. src/types.d.ts) with the following content:

apps/my-app/src/types.d.ts
1declare const PLUGIN1_TEXT: number; 2declare const PLUGIN2_TEXT: string; 3

Options

index

Required
oneOf [string, object , boolean]

Configures the generation of the application's HTML index.

main

Required
string

The full path for the main entry point to the app, relative to the current workspace.

outputPath

Required
string

The full path for the new output directory, relative to the current workspace.

tsConfig

Required
string

The full path for the TypeScript configuration file, relative to the current workspace.

assets

Array<oneOf [object , string]>
Default: []

List of static application assets.

aot

boolean
Default: true

Build using Ahead of Time compilation.

allowedCommonJsDependencies

Array<string>
Default: []

A list of CommonJS or AMD packages that are allowed to be used without a build time warning. Use '*' to allow all.

baseHref

string

Base url for the application being built.

buildOptimizer

boolean
Default: true

Enables advanced build optimizations when using the 'aot' option.

budgets

Default: []

Budget thresholds to ensure parts of your application stay within boundaries which you set.

buildLibsFromSource

boolean
Default: true

Read buildable libraries from source instead of building them separately.

commonChunk

boolean
Default: true

Generate a separate bundle containing code used across multiple bundles.

crossOrigin

string
Default: none
Accepted values: none, anonymous, use-credentials

Define the crossorigin attribute setting of elements that provide CORS support.

deployUrl

string

Customize the base path for the URLs of resources in 'index.html' and component stylesheets. This option is only necessary for specific deployment scenarios, such as with Angular Elements or when utilizing different CDN locations.

deleteOutputPath

boolean
Default: true

Delete the output path before building.

externalDependencies

Array<string>
Default: []

Exclude the listed external dependencies from being bundled into the bundle. Instead, the created bundle relies on these dependencies to be available during runtime.

extractLicenses

boolean
Default: true

Extract all licenses in a separate file.

fileReplacements

Default: []

Replace compilation source files with other compilation source files in the build.

inlineStyleLanguage

string
Default: css
Accepted values: css, less, sass, scss

The stylesheet language to use for the application's inline component styles.

i18nMissingTranslation

string
Default: warning
Accepted values: warning, error, ignore

How to handle missing translations for i18n.

i18nDuplicateTranslation

string
Default: warning
Accepted values: warning, error, ignore

How to handle duplicate translations for i18n.

localize

oneOf [boolean, Array<string>]

Translate the bundles in one or more locales.

namedChunks

boolean
Default: false

Use file name for lazy loaded chunks.

ngswConfigPath

string

Path to ngsw-config.json.

optimization

oneOf [object , boolean]
Default: true

Enables optimization of the build output. Including minification of scripts and styles, tree-shaking, dead-code elimination, inlining of critical CSS and fonts inlining. For more information, see https://angular.dev/reference/configs/workspace-config#optimization-configuration.

outputHashing

string
Default: none
Accepted values: none, all, media, bundles

Define the output filename cache-busting hashing mode.

polyfills

oneOf [Array<string>, string]

Polyfills to be included in the build.

progress

boolean
Default: true

Log progress to the console while building.

poll

number

Enable and define the file watching poll time period in milliseconds.

boolean

Do not use the real path when resolving modules. If unset then will default to true if NodeJS option --preserve-symlinks is set.

plugins

Array<oneOf [object , string]>

A list of ESBuild plugins. Note: this is only supported in Angular versions >= 17.0.0.

resourcesOutputPath

string

The path where style resources will be placed, relative to outputPath.

scripts

Array<oneOf [object , string]>
Default: []

Global scripts to be included in the build.

styles

Array<oneOf [object , string]>
Default: []

Global styles to be included in the build.

stylePreprocessorOptions

Options to pass to style preprocessors.

sourceMap

oneOf [object , boolean]
Default: false

Output source maps for scripts and styles. For more information, see https://angular.dev/reference/configs/workspace-config#source-map-configuration.

subresourceIntegrity

boolean
Default: false

Enables the use of subresource integrity validation.

serviceWorker

boolean
Default: false

Generates a service worker config for production builds.

statsJson

boolean
Default: false

Generates a 'stats.json' file which can be analyzed using tools such as 'webpack-bundle-analyzer'.

vendorChunk

boolean
Default: false

Generate a separate bundle containing only vendor libraries. This option should only be used for development to reduce the incremental compilation time.

verbose

boolean
Default: false

Adds more details to output logging.

watch

boolean
Default: false

Run build when files change.

webWorkerTsConfig

string

TypeScript configuration for Web Worker modules.