Angular CLI hooks

This small package hooks into native Angular CLI builders. With it, you can...

... run code before Angular CLI invocates native builders
... and/or override invocations
... and/or run code after Angular CLI emits BuilderOutput

A few examples include

Running eslint before ng build runs
Using jest over jasmine when running ng test
Starting a mock server with ng serve

Usage

Step 1 - creating a hook package

First, you need to create a package of hooks. To, for example, run ESLint before ng build, add a hook to build and a before-function. The before-function can return either Observable, Promise or a sync value.

Then, to make the hook configurable, use the schema-property to add a JsonSchema for any configurations. When installing angular-cli-hooks, this schema is merged with the native Angular CLI builder schema.

Adding a JsonSchema makes both the hook configuration and the native builder configuration available when implementing the hook. Both are also listed when running ng build --help.

// index.ts in builder-hooks

import { BuilderOutput } from '@angular-devkit/architect';
import { hook } from 'angular-cli-hooks';
import { ESLint } from 'eslint';

export default [
  hook({
    name: 'build',
    schema: {
      properties: {
        failOnLintErrors: {
          type: 'boolean',
          description: 'Whether to fail the build on lint errors.',
        },
      },
    },
    before: async (
      { failOnLintErrors },
      { workspaceRoot }
    ): Promise<BuilderOutput> => {
      const eslint = new ESLint();
      const results = await eslint.lintFiles([`${workspaceRoot}/**/*.ts`]);

      if (results.length > 0) {
        console.log((await eslint.loadFormatter()).format(results));

        if (failOnLintErrors) {
          throw new Error('ESLint found lint errors.');
        }
      }

      return { success: true };
    },
  }),
];

This code hooks into ng build, but you can hook into other builders too.

Hook	Command	Node API
`build`	`ng build`	`executeBrowserBuilder`
`serve`	`ng serve`	`executeDevServerBuilder`
`build-lib`	`ng build` (in libraries)	`executeNgPackagrBuilder`
`i18n`	`ng i18n`	`executeExtractI18nBuilder`
`test`	`ng test`	`executeKarmaBuilder`
`e2e`	`ng e2e`	`executeProtractorBuilder`

Step 2 - using a hook package

Install the hook package wherever you want to hook into Angular CLI. Then add a angular-cli-hooks.json file to your project and specify the name of the package of hooks

{
  "$schema": "./node_modules/angular-cli-hooks/schema.json",
  "hookPackage": "builder-hooks"
}

or for multiple hook packages

{
  "$schema": "./node_modules/angular-cli-hooks/schema.json",
  "hookPackage": ["builder-hooks", "more-builder-hooks"]
}

Step 3 - updating angular.json

Update angular.json to use angular-cli-hooks over @angular-devkit/build-angular.

{
  "architect": {
    "build": {
      "builder": "@angular-devkit/build-angular:browser"
    }
  }
}

becomes

{
  "architect": {
    "build": {
      "builder": "angular-cli-hooks:browser"
    }
  }
}

And that's it.

Gotchas

The JsonSchema for custom configurations is merged with Angular native schemas in the postinstall hook of angular-cli-hooks. You have to reinstall to see changes.
The before hook will only run before the Angular native builder is invoked the first time.
The after hook will run after an Angular builder emits a BuilderOutput. This means the after hook will run for both fresh builds and rebuilds.