Setup incremental builds for Angular applications

In this guide we’ll specifically look into which changes need to be made to enable incremental builds for Angular applications.

Nx > 10.4.0

Incremental builds requires Nx version 10.4.0 or later.

Requirements

If your library consumes any Angular package that has not been compiled with Ivy, you must ensure the Angular compatibility compiler (ngcc) has run before building the library. The incremental build relies on the fact that ngcc must have already been run. One way to do this is to run ngcc after every package installation. You can check your package.json and make sure you have the following:

package.json
{
  ...
  "scripts": {
    ...
    "postinstall": "ngcc --properties es2015 browser module main",
    ...
  }
  ...
}

PNPM support

To use ngcc with pnpm, set node-linker=hoisted in .npmrc and explicitly declare node-gyp-build in package.json See angular/angular#50735, nrwl/nx#16319 and parcel-bundler/watcher#142 for more details.

.npmrc
node-linker=hoisted

package.json
{
  ...
  "devDependencies": {
    ...
    "node-gyp-build": "4.6.0",
    ...
  }
  ...
}

Use buildable libraries

To enable incremental builds you need to use buildable libraries.

Directory Flag Behavior Changes

The command below uses the as-provided directory flag behavior, which is the default in Nx 16.8.0. If you're on an earlier version of Nx or using the derived option, omit the --directory flag. See the workspace layout documentation for more details.

You can generate a new buildable library with:

❯

nx g @nx/angular:lib my-lib --directory=libs/my-lib --buildable

Nx 15 and lower use @nrwl/ instead of @nx/

The generated buildable library uses the @nx/angular:ng-packagr-lite executor which is optimized for the incremental builds scenario:

{
  "projectType": "library",
  ...
  "targets": {
    "build": {
      "executor": "@nx/angular:ng-packagr-lite",
      "outputs": [
        "{workspaceRoot}/dist/libs/my-lib"
      ],
      "options": {
        ...
      },
      "configurations": {
        ...
      },
      "defaultConfiguration": "production"
    },
    ...
  },
  ...
},
Nx 15 and lower use @nrwl/ instead of @nx/

More details

Please note that it is important to keep the outputs property in sync with the dest property in the file ng-package.json located inside the library root. When a library is generated, this is configured correctly, but if the path is later changed in ng-package.json, it needs to be updated as well in the project configuration.

The @nx/angular:package executor also supports incremental builds. It is used to build and package an Angular library to be distributed as an NPM package following the Angular Package Format (APF) specification. It will be automatically configured when generating a publishable library (nx g @nx/angular:lib my-lib --publishable --importPath my-lib).

Adjust the application executor

Change your Angular application’s "build" target executor to @nx/angular:webpack-browser and the "serve" target executor to @nx/web:file-server as shown below:

{
  "projectType": "application",
  ...
  "targets": {
    "build": {
      "executor": "@nx/angular:webpack-browser",
      "outputs": [
        "{options.outputPath}"
      ],
      "options": {
        "buildLibsFromSource": false
        ...
      },
      "configurations": {
        ...
      },
      "defaultConfiguration": "production"
    },
    "serve": {
      "executor": "@nx/web:file-server",
      "options": {
        "buildTarget": "my-app:build"
      },
      "configurations": {
        "production": {
          "buildTarget": "my-app:build:production"
        }
      }
    },
    ...
  }
},
Nx 15 and lower use @nrwl/ instead of @nx/

Running and serving incremental builds

To build an application incrementally use the following command:

❯

nx build my-app --parallel

To serve an application incrementally use this command:

❯

nx serve my-app --parallel

Project configuration option

You can specify the --parallel flags as part of the options property on the file-server executor in your project.json file. The file-server executor will pass those to the nx build command it invokes.

{
  "projectType": "application",
  ...
  "targets": {
    "build": {
      "executor": "@nx/angular:webpack-browser",
      "outputs": [
        "{options.outputPath}"
      ],
      "options": {
        "buildLibsFromSource": false
        ...
      },
      "configurations": {
        ...
      }
    },
    "serve": {
      "executor": "@nx/web:file-server",
      "options": {
        "buildTarget": "my-app:build",
        "parallel": true
      },
      "configurations": {
        "production": {
          "buildTarget": "my-app:build:production"
        }
      }
    },
    ...
  }
},
Nx 15 and lower use @nrwl/ instead of @nx/

Build target name

It is required to use the same target name for the build target (target using one of the executors that support incremental builds: @nx/angular:webpack-browser, @nx/angular:package and @nx/angular:ng-packagr-lite) in the project being built and the buildable libraries it depends on. The executors that support incremental builds rely on the build target name of the project to identify which of the libraries it depends on are buildable.

If you need to have a different build target name for an application (or library) build (e.g. when composing different targets), you need to make sure the build target name of all the relevant projects is the same.

Say you have the same application above with a configuration as follows:

{
  "projectType": "application",
  ...
  "targets": {
    "build-base": {
      "executor": "@nx/angular:webpack-browser",
      "outputs": [
        "{options.outputPath}"
      ],
      "options": {
        "buildLibsFromSource": false
        ...
      },
      "configurations": {
        ...
      }
    },
    "build": {
      "executor": "nx:run-commands",
      "outputs": [
        "{options.outputPath}"
      ],
      "options": {
        "commands": [
          "node ./tools/scripts/important-script.js",
          "node ./tools/scripts/another-important-script.js"
        ],
        ...
      },
      "configurations": {
        ...
      }
    },
    "serve": {
      "executor": "@nx/web:file-server",
      "options": {
        "buildTarget": "my-app:build-base",
        "parallel": true
      },
      "configurations": {
        "production": {
          "buildTarget": "my-app:build-base:production"
        }
      }
    },
    ...
  }
},
Nx 15 and lower use @nrwl/ instead of @nx/

And the targetDefaults configured in the nx.json as:

{
  "targetDefaults": {
    "build": {
      "dependsOn": ["build-base"]
    },
    "build-base": {
      "dependsOn": ["^build-base"]
    }
  }
}

The build target name of the application is build-base. Therefore, the build target name of the buildable libraries it depends on must also be build-base:

{
  "projectType": "library",
  ...
  "targets": {
    "build-base": {
      "executor": "@nx/angular:ng-packagr-lite",
      "outputs": [
        "{workspaceRoot}/dist/libs/my-lib"
      ],
      "options": {
        ...
      },
      "configurations": {
        ...
      },
      "defaultConfiguration": "production"
    },
    ...
  },
  ...
},
Nx 15 and lower use @nrwl/ instead of @nx/

Example repository

Check out the nx-incremental-large-repo for a live example.

Example repository/nrwl/nx-incremental-large-repo