@nx/angular:application

Builds an application with esbuild with support for incremental builds. Note: this is only supported in Angular versions >= 17.0.0.

Options can be configured in project.json when defining the executor, or when invoking it. Read more about how to configure targets and executors here: https://nx.dev/reference/project-configuration#targets.

The @nx/angular:application executor is very similar to the @angular-devkit/build-angular:application builder provided by the Angular CLI. It builds an Angular application using esbuild with integrated SSR and prerendering capabilities.

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

Providing esbuild plugins
Providing a function to transform the application's index.html file
Incremental builds

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
{
  ...
  "targets": {
    "build": {
      "executor": "@nx/angular:application",
      "options": {
        ...
        "plugins": [
          "apps/my-app/plugins/plugin1.js",
          {
            "path": "apps/my-app/plugins/plugin2.js",
            "options": {
              "someOption": "some value"
            }
          }
        ]
      }
    }
    ...
  }
}

apps/my-app/plugins/plugin1.js
const plugin1 = {
  name: 'plugin1',
  setup(build) {
    const options = build.initialOptions;
    options.define.PLUGIN1_TEXT = '"Value was provided at build time"';
  },
};

module.exports = plugin1;

apps/my-app/plugins/plugin2.js
function plugin2({ someOption }) {
  return {
    name: 'plugin2',
    setup(build) {
      const options = build.initialOptions;
      options.define.PLUGIN2_TEXT = JSON.stringify(someOption);
    },
  };
}

module.exports = plugin2;

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
declare const PLUGIN1_TEXT: number;
declare const PLUGIN2_TEXT: string;

Options playground

Try out this interactive editor of the configuration object. Values are validated as you type and hovering over labels will give you more information.

Options

browser

Required

string

The full path for the browser entry point to the application, relative to the current workspace.

index

Required

oneOf [string, object , boolean]

Configures the generation of the application's HTML index.

outputPath

Required

oneOf [object , string]

Specify the output path relative to workspace root. Note: the object notation is only supported in Angular versions >= 17.1.0.

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.

appShell

boolean

Default: false

Generates an application shell during build time.

baseHref

string

Base url for the application being built.

budgets

Array<budgets items >

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.

clearScreen

boolean

Default: false

Automatically clear the terminal screen during rebuilds. Note: this is only supported in Angular versions >= 17.2.0.

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. Note: this is only supported in Angular versions >= 17.3.0.

define

Defines global identifiers that will be replaced with a specified constant value when found in any JavaScript or TypeScript code including libraries. The value will be used directly. String values must be put in quotes. Identifiers within Angular metadata such as Component Decorators will not be replaced. Note: this is only supported in Angular versions >= 17.2.0.

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

Array<fileReplacements items >

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.

indexHtmlTransformer

string

Path to a file exposing a default function to transform the index.html file. Note: this is only supported in Angular versions >= 17.1.0.

loader

Defines the type of loader to use with a specified file extension when used with a JavaScript import. text inlines the content as a string; binary inlines the content as a Uint8Array; file emits the file and provides the runtime location of the file; empty considers the content to be empty and not include it in bundles. Note: this is only supported in Angular versions >= 17.1.0.

localize

oneOf [boolean, Array<string>]

Translate the bundles in one or more locales.

namedChunks

boolean

Default: false

Use file name for lazy loaded chunks.

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.io/guide/workspace-config#optimization-configuration.

outputHashing

string

Default: none

Accepted values: none, all, media, bundles

Define the output filename cache-busting hashing mode.

polyfills

Array<string>

Default: []

A list of polyfills to include in the build. Can be a full path for a file, relative to the current workspace or module specifier. Example: 'zone.js'.

progress

boolean

Default: true

Log progress to the console while building.

poll

number

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

preserveSymlinks

boolean

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

prerender

oneOf [boolean, object ]

Default: false

Prerender (SSG) pages of your application during build time.

plugins

Array<oneOf [object , string]>

A list of ESBuild plugins.

server

string

The full path for the server entry point to the application, relative to the current workspace.

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.io/guide/workspace-config#source-map-configuration.

subresourceIntegrity

boolean

Default: false

Enables the use of subresource integrity validation.

serviceWorker

oneOf [string, boolean]

Default: false

Generates a service worker configuration.

statsJson

boolean

Default: false

Generates a 'stats.json' file which can be analyzed with https://esbuild.github.io/analyze/.

ssr

oneOf [boolean, object ]

Default: false

Server side render (SSR) pages of your application during runtime.

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.