DEV Community: Igor Katsuba

Mutate a code with Angular schematics like a boss

Igor Katsuba — Tue, 28 Dec 2021 09:59:04 +0000

For fulfilling using Angular CLI, developers have to know about Angular schematics. ng add, ng update and ng generate use schematics to add, update and configure libraries and generate code for applications. In runtime, you get access to a virtual file system and can mutate source code as you need. "But for code mutation, I have to work with AST. It is so hard." — say you. And you are right!

This article tells you how we are trying to do work with schematics easily and how to work with AST outside schematics in any project.

What is a schematic?

Technically, the schematic is a function with two arguments:

Schematic configuration
Context. Used it for logging. Contains some utils.

The schematic function returns type Rule. Let's look at this type:

type Rule = (tree: Tree, context: SchematicContext) => Tree | Observable<Tree> | Rule | Promise<void | Rule> | void;

Rule can be synchronous or asynchronous. Like a bonus, Rule can return Observable.

The last unknown type here is Tree. Tree is an abstraction for working with the virtual file system. Any changes in the virtual file system apply to the real file system.

Each Angular CLI command working with schematics has its configuration, but in the end, it is just calling the above function.

Why do we use schematics?

We use schematics a lot, and we have reasons:

Migrations. We use migrations when releasing libraries with breaking changes. Migrations help developers make updates softer. Angular CLI uses migrations with the ng update command. We even contributed to RenovateBot to run migrations automatically when the dependencies are updated.
Library configuration when added to a project. Schematics allow preparation immediately for the project for using the library (add imports to the module, inject default configs, change build process, etc.).
Code generation (easy and quick creation of component, directive, library, service, etc.). For example, schematics can create a lazy route with all the needed configurations.

I can write a large list of cases for each item, but let's leave it to your imagination.

As a result, we can say that writing schematics is a good time saver for users, but...

We have a problem

We had a simple task to add the module import to AppModule. After development, we realized that we had spent much more time than expected.

What was the problem? We decided to use AST for code mutation. But AST is not a simple thing for developers who are just working with Angular services and components.

For example, the Angular team uses the typescript API for migrations. How often do you face using typescript programmatically? How often do you operate the nodes from the TS compiler to add a couple of properties to the object?

Below is a simple example of a function that adds data to the module metadata (original code). CAUTION: the code is given as an example. I do not advise you to strain yourself and understand what is happening in it!

export function addSymbolToNgModuleMetadata(
  source: ts.SourceFile,
  ngModulePath: string,
  metadataField: string,
  symbolName: string,
  importPath: string | null = null,
): Change[] {
  const nodes = getDecoratorMetadata(source, 'NgModule', '@angular/core');
  let node: any = nodes[0];  // tslint:disable-line:no-any

  // Find the decorator declaration.
  if (!node) {
    return [];
  }

  // Get all the children property assignment of object literals.
  const matchingProperties = getMetadataField(
    node as ts.ObjectLiteralExpression,
    metadataField,
  );

  // Get the last node of the array literal.
  if (!matchingProperties) {
    return [];
  }
  if (matchingProperties.length == 0) {
    // We haven't found the field in the metadata declaration. Insert a new field.
    const expr = node as ts.ObjectLiteralExpression;
    let position: number;
    let toInsert: string;
    if (expr.properties.length == 0) {
      position = expr.getEnd() - 1;
      toInsert = `  ${metadataField}: [${symbolName}]\\n`;
    } else {
      node = expr.properties[expr.properties.length - 1];
      position = node.getEnd();
      // Get the indentation of the last element, if any.
      const text = node.getFullText(source);
      const matches = text.match(/^\\r?\\n\\s*/);
      if (matches && matches.length > 0) {
        toInsert = `,${matches[0]}${metadataField}: [${symbolName}]`;
      } else {
        toInsert = `, ${metadataField}: [${symbolName}]`;
      }
    }
    if (importPath !== null) {
      return [
        new InsertChange(ngModulePath, position, toInsert),
        insertImport(source, ngModulePath, symbolName.replace(/\\..*$/, ''), importPath),
      ];
    } else {
      return [new InsertChange(ngModulePath, position, toInsert)];
    }
  }
  const assignment = matchingProperties[0] as ts.PropertyAssignment;

  // If it's not an array, nothing we can do really.
  if (assignment.initializer.kind !== ts.SyntaxKind.ArrayLiteralExpression) {
    return [];
  }

  const arrLiteral = assignment.initializer as ts.ArrayLiteralExpression;
  if (arrLiteral.elements.length == 0) {
    // Forward the property.
    node = arrLiteral;
  } else {
    node = arrLiteral.elements;
  }

  if (!node) {
    // tslint:disable-next-line: no-console
    console.error('No app module found. Please add your new class to your component.');

    return [];
  }

  if (Array.isArray(node)) {
    const nodeArray = node as {} as Array<ts.Node>;
    const symbolsArray = nodeArray.map(node => node.getText());
    if (symbolsArray.includes(symbolName)) {
      return [];
    }

    node = node[node.length - 1];
  }

  let toInsert: string;
  let position = node.getEnd();
  if (node.kind == ts.SyntaxKind.ObjectLiteralExpression) {
    // We haven't found the field in the metadata declaration. Insert a new
    // field.
    const expr = node as ts.ObjectLiteralExpression;
    if (expr.properties.length == 0) {
      position = expr.getEnd() - 1;
      toInsert = `  ${symbolName}\\n`;
    } else {
      // Get the indentation of the last element, if any.
      const text = node.getFullText(source);
      if (text.match(/^\\r?\\r?\\n/)) {
        toInsert = `,${text.match(/^\\r?\\n\\s*/)[0]}${symbolName}`;
      } else {
        toInsert = `, ${symbolName}`;
      }
    }
  } else if (node.kind == ts.SyntaxKind.ArrayLiteralExpression) {
    // We found the field but it's empty. Insert it just before the `]`.
    position--;
    toInsert = `${symbolName}`;
  } else {
    // Get the indentation of the last element, if any.
    const text = node.getFullText(source);
    if (text.match(/^\\r?\\n/)) {
      toInsert = `,${text.match(/^\\r?\\n(\\r?)\\s*/)[0]}${symbolName}`;
    } else {
      toInsert = `, ${symbolName}`;
    }
  }
  if (importPath !== null) {
    return [
      new InsertChange(ngModulePath, position, toInsert),
      insertImport(source, ngModulePath, symbolName.replace(/\\..*$/, ''), importPath),
    ];
  }

  return [new InsertChange(ngModulePath, position, toInsert)];
}

Looks difficult.

Complexity is the main reason for creating a high-level library that allows you to mutate your code easier!

`ng-morph`

It has ts-morph under the hood and allows you to manipulate with safe TypeScript AST.

ng-morph is a set of utilities that will allow you to write schematics much easier and faster. Let's look at a few examples of using it.

Example #1

Add import of the SomeModule module to the root module of the application.

Solution.


const rule: Rule = (tree: Tree, context: SchematicContext): void => {
  setActiveProject(createProject(tree));

  const appModule = getMainModule('src/main.ts');

  addImportToNgModule(appModule, 'SomeModule');

  addImports(appModule.getFilePath(), {moduleSpecifier: '@some/package', namedExports: ['SomeModule']})

  saveActiveProject();
}

Let's look at the solution line by line:

Create the ng-morph project and set it active. It is important because all of the functions work in the context of the active project. Project is a class with access to a file system, the TS compiler, etc.
Find the main application module by entry point.
Add a new import to the main module.
Add a new import to the file of the main module.
Save the project.

Now compare this solution with the function above from the Angular sources. If you use ng-morph, you probably won't have to write something like this.

Example #2

We should rewrite enum names to uppercase.

Solution

Common questions: "Why should we use schematics for this? The schematics are too complex to rename enums".

You are right. But let’s look at ng-morph power!

setActiveProject(createProject(new NgMorphTree('/')));

const enums = getEnums('/**/*.ts');

editEnums(enums, ({name}) => ({name: name.toUpperCase()}))

Create a project. There is an important moment. The script is not wrapped by schematic function, and Tree is created manually with NgMorphTree.
Find all enums.
Rename all enums.

This example shows us that ng-morph can work outside of schematics! And yes, we use ng-morph in non-Angular projects!

What else can `ng-morph` do?

Create

createImports('/src/some.ts', [
  {
    namedImports: ['CoreModule'],
    moduleSpecifier: '@org/core',
    isTypeOnly: true,
  }
]);

Find

const imports = getImports('src/**/*.ts', {
  moduleSpecifier: '@org/*',
});

Edit

editImports(imports, ({moduleSpecifier}) => ({
  moduleSpecifier: moduleSpecifier.replace('@org', '@new-org')
})

Remove

removeImports(imports)

Almost every entity in TS has its own set of functions (get*, edit*, add*, remove*). For example getClass, removeConstrucor, addDecorator. We started to develop utility functions for working with Angular-specific cases:

getBootstrapFn is a function that returns CallExpression
getMainModule is a function that returns the main module declaration.
Many utility functions for changing the metadata of Angular entities: addDeclarationToNgModule, addProviderToDirective, etc.

ng-morph can work with json. For example, you can add dependencies in package.json:

addPackageJsonDependency(tree, {
  name: '@package/name',
  version: '~2.0.0',
  type: NodeDependencyType.Dev
});

If you need lower-level work, you can always work with the ts-morph API and fall even lower into the typescript API.

Summary

There is no roadmap at this time. We quickly implemented what we were missing and decided to show it to the community. We want to develop the instrument further.

Nevertheless, there is still a list of essential features:

High-level work with templates
High-level work with styles
Increasing tooling for working with Angular entities

And we'll be glad if the Angular community can help us do this!

Links

Code repository

taiga-family / ng-morph

Code mutations in your project or schematics were never easier than now.

Documentation and examples

Already using `ng-morph`

Our friendliest and best component library for Angular known to me

taiga-family / taiga-ui

Angular UI Kit and components library for awesome people

3 steps to understanding Angular

Igor Katsuba — Thu, 25 Mar 2021 06:58:21 +0000

Angular is a big and complicated framework. Like any complex tool, you can’t learn it for 2 days. You have to work hard and practice for several years to begin to feel comfortable using it.

I have identified 3 main steps that let me understand Angular.

Stage 1. 🧑‍💻 NgMan Begins.

The first stage began for me when I created an Angular project the first time. It was a payment page and a result page. I generated the project with ng new and learned tutorials from the official documentation. I have supported and developed this app for one year.

Here's what I've learned this year:

Learned to use directives, components, and modules correctly.
Researched a base routing configuration, including lazy routing.
Learned to use template-driven and reactive forms.
Used built-in pipes. Wrote new pipes myself.
Used HttpClient for messaging with a server and wrote interceptors.
Used base CLI features: build, serve, test, lint, new, generate
Learned to understand the angular.json format.
Used external schematic collections for code generation.
Learned the injector hierarchy. Used InjectionToken and providers (ClassProvider, ValueProvider, FactoryProvider). Read about resolution modifiers, but used only Optional.
Learned the Change Detection strategies. Optimized performance with ChangeDetectorRef
Read about zone.js. Learned how to run async tasks outside the Angular zone.

I think I had the right start. I learned basic Angular features and builded the app for production! I was so happy and excited. This stage prepared me well for the next one.

Stage 2. 🥷 CDK Ninja.

After application development, I started to develop a proprietary library of reusable components using @angular/cdk.

Result:

Created new structure directives myself.
Deep learned lifecycle hooks of components, directives, and services.
Learned ng-packagr and Angular Package Format.
Learned how to write schematics for code generation.
Wrote simple migrations.
Learned and used all providers.
Used tree-shakable providers and services.
Used all DI resolution modifiers, including the Host decorator.
Learned the inject function and its using context.
Learned a difference between providers and viewProviders.
Started learning Angular source code.

The development of the UI Kit boosted my understanding of all the processes in Angular. I was able to deep dive into the features of the framework like DI and Change Detection. The third stage opened the last part unknown to me.

Stage 3. 🅰️ Angular FrontOps

A year ago, I was invited to an interview at Tinkoff.ru. The guys painted everything so colorfully that I accepted a job offer. I started working in the platform team. It was the start of Stage 3.

Result:

Learn to write CLI builders and webpack plugins.
Started to write hard migrations. Created a high-level library for source code mutations.
Learned to extend and create platforms for Angular running.
Created a framework for microfrontends (WIP)
Learned to customize ng-packagr and write typescript transformers.
Learned Angular Universal.

This stage is not finished yet, but it showed me Angular from the other side. Usually, developers don’t customize or extend Angular CLI. They use standard platforms. But I have learned to solve problems and tasks in different ways.

Summary

I very shortly talked about the stages that I went through when learning Angular. Each stage opened many new framework features for me, but I cannot say that I know everything about it even now. And I hope this is just the beginning!

Angular Universal: real app problems

Igor Katsuba — Fri, 05 Mar 2021 07:22:05 +0000

Angular Universal: real app problems

Angular Universal is an open-source project that extends the functionality of @angular/platform-server. The project makes server-side rendering possible in Angular.

Angular Universal supports multiple backends:

Another package Socket Engine is a framework-agnostic that theoretically allows any backend to be connected to an SSR server.

This article will discuss the issues and possible solutions we encountered while developing a real application with Angular Universal and Express.

How Angular Universal Works

For rendering on the server, Angular uses the DOM implementation for node.js — domino. For each GET request, domino creates a similar Browser Document object. In that object context, Angular initializes the application. The app makes requests to the backend, performs various asynchronous tasks, and applies any change detection from components to the DOM while still running inside node.js environment. The render engine then serializes DOM into a string and serves up the string to the server. The server sends this HTML as a response to the GET request. Angular application on the server is destroyed after rendering.

SSR issues in Angular

1. Infinite page loading

Situation

The user opens a page on your site and sees a white screen. In other words, the time until the first byte takes too long. The browser really wants to receive a response from the server, but the request ends up with a timeout.

Why is this happening

Most likely, the problem lies in the Angular-specific SSR mechanism. Before we understand at what point the page is rendered, let's define Zone.js andApplicationRef.

Zone.js is a tool that allows you to track asynchronous operations. With its help, Angular creates its own zone and launches the application in it. At the end of each asynchronous operation in the Angular zone, change detection is triggered.

ApplicationRef is a reference to the running application (docs). Of all this class's functionality, we are interested in the ApplicationRef#isStable property. It is an Observable that emits a boolean. isStable is true when no asynchronous tasks are running in the Angular zone and false when there are no such tasks.

So, application stability is the state of the application, which depends on the presence of asynchronous tasks in the Angular zone.

So, at the moment of the first onset of stability, Angular renders the current state applications and destroys the platform. And the platform will destroy the application.

We can now assume that the user is trying to open an application that cannot achieve stability. setInterval, rxjs.interval or any other recursive asynchronous operation running in the Angular zone will make stability impossible. HTTP requests also affect stability. The lingering request on the server delays the moment the page is rendered.

Possible Solution

To avoid the situation with long requests, use the timeout operator from rxjs library:

import { timeout, catchError } from 'rxjs/operators';
import { of } from 'rxjs/observable/of';

http.get('https://example.com')
    .pipe(
        timeout(2000),
        catchError(e => of(null))
    ).subscribe()

The operator will throw an exception after a specified period of time if no server response is received.

This approach has 2 cons:

there is no convenient division of logic by platform;
the timeout operator must be written manually for each request.

As a more straightforward solution, you can use the NgxSsrTimeoutModule module from the @ngx-ssr/timeout package. Import the module with the timeout value into the root module of the application. If the module is imported into AppServerModule, then HTTP request timeouts will only work for the server.

import { NgModule } from '@angular/core';
import {
    ServerModule,
} from '@angular/platform-server';
import { AppModule } from './app.module';
import { AppComponent } from './app.component';
import { NgxSsrTimeoutModule } from '@ngx-ssr/timeout';

@NgModule({
    imports: [
        AppModule,
        ServerModule,
        NgxSsrTimeoutModule.forRoot({ timeout: 500 }),
    ],
    bootstrap: [AppComponent],
})
export class AppServerModule {}

Use the NgZone service to take asynchronous operations out of the Angular zone.

import { Injectable, NgZone } from "@angular/core";

@Injectable()
export class SomeService {
    constructor(private ngZone: NgZone){
        this.ngZone.runOutsideAngular(() => {
            interval(1).subscribe(() => {
                // somo code
            })
        });
    }
}

To solve this problem, you can use the tuiZonefree from the@taiga-ui/cdk:

import { Injectable, NgZone } from "@angular/core";
import { tuiZonefree } from "@taiga-ui/cdk";

@Injectable()
export class SomeService {
    constructor(private ngZone: NgZone){
        interval(1).pipe(tuiZonefree(ngZone)).subscribe()
    }
}

But there is a nuance. Any task must be interrupted when the application is destroyed. Otherwise, you can catch a memory leak (see issue #5). You also need to understand that tasks that are removed from the zone will not trigger change detection.

2. Lack of cache out of the box

Situation

The user loads the home page of the site. The server requests data for the master and renders it, spending 2 seconds on it. Then the user goes from the main to the child section. Then it tries to go back and waits for the same 2 seconds as the first time.

If we assume that the data on which the main render depends has not changed, it turns out that HTML with this set has already been rendered. And in theory, we can reuse the HTML we got earlier.

Possible Solution

Various caching techniques come to the rescue. We'll cover two: in-memory cache and HTTP cache.

HTTP cache. When using a network cache, it's all about setting the correct response headers on the server. They specify the cache lifetime and caching policy:

Cache-Control: max-age = 31536000

This option is suitable for an unauthorized zone and in the presence of long unchanging data.

You can read more about the HTTP cache here

In-memory cache. The in-memory cache can be used for both rendered pages and API requests within the application itself. Both possibilities are package @ngx-ssr/cache.

Add the NgxSsrCacheModule module to the AppModule to cache API requests and on the server in the browser.

The maxSize property is responsible for the maximum cache size. A value of 50 means that the cache will contain more than 50 of the last GET requests made from the application.

The maxAge property is responsible for the cache lifetime. Specified in milliseconds.

import { BrowserModule } from '@angular/platform-browser';
import { NgModule } from '@angular/core';
import { AppComponent } from './app.component';
import { NgxSsrCacheModule } from '@ngx-ssr/cache';
import { environment } from '../environments/environment';

@NgModule({
    declarations: [AppComponent],
    imports: [
        BrowserModule,
        NgxSsrCacheModule.configLruCache({ maxAge: 10 * 60_000, maxSize: 50 }),
    ],
    bootstrap: [AppComponent],
})
export class AppModule {}

You can go ahead and cache the HTML itself.

For example, everything in the same package @ngx-ssr/cache has a submodule@ngx-ssr/cache/express. It imports a single withCache function. The function is a wrapper over the render engine.

import { ngExpressEngine } from '@nguniversal/express-engine';
import { LRUCache } from '@ngx-ssr/cache';
import { withCache } from '@ngx-ssr/cache/express';

server.engine(
    'html',
    withCache(
        new LRUCache({ maxAge: 10 * 60_000, maxSize: 100 }),
        ngExpressEngine({
            bootstrap: AppServerModule,
        })
    )
);

3. Server errors of type ReferenceError: localStorage is not defined

Situation

The developer calls localStorage right in the body of the service. It retrieves data from the local storage by key. But on the server, this code crashes with an error: ReferenceError: localStorage is undefined.

Why is this happening

When running an Angular application on a server, the standard browser API is missing from the global space. For example, there's no global object document like you'd expect in a browser environment. To get the reference to the document, you must use the DOCUMENT token and DI.

Possible Solution

Don't use the browser API through the global space. There is DI for this. Through DI, you can replace or disable browser implementations for their safe use on the server.

The Web API for Angular can be used to resolve this issue.

For example:

import {Component, Inject, NgModule} from '@angular/core';
import {LOCAL_STORAGE} from '@ng-web-apis/common';

@Component({...})
export class SomeComponent {
    constructor(@Inject(LOCAL_STORAGE) localStorage: Storage) {
        localStorage.getItem('key');
    }
}

The example above uses the LOCAL_STORAGE token from the @ng-web-apis/common package. But when we run this code on the server, we will get an error from the description. Just add UNIVERSAL_LOCAL_STORAGE from the package @ng-web-apis/universal in the providersAppServerModule, and by the token LOCAL_STORAGE, you will receive an implementation of localStorage for the server.

import { NgModule } from '@angular/core';
import {
    ServerModule,
} from '@angular/platform-server';
import { AppModule } from './app.module';
import { AppComponent } from './app.component';
import { UNIVERSAL_LOCAL_STORAGE } from '@ngx-ssr/timeout';

@NgModule({
    imports: [
        AppModule,
        ServerModule,
    ],
    providers: [UNIVERSAL_LOCAL_STORAGE],
    bootstrap: [AppComponent],
})
export class AppServerModule {}

4. Inconvenient separation of logic

Situation

If you need to render the block only in the browser, you need to write approximately the following code:

@Component({
    selector: 'ram-root',
    template: '<some-сomp *ngIf="isServer"></some-сomp>',
    styleUrls: ['./app.component.less'],
})
export class AppComponent {
    isServer = isPlatformServer(this.platformId);

    constructor(@Inject(PLATFORM_ID) private platformId: Object){}
}

The component needs to get the PLATFORM_ID, target platform, and understand the class's public property. This property will be used in the template in conjunction with the ngIf directive.

Possible Solution

With the help of structural directives and DI, the above mechanism can be greatly simplified.

First, let's wrap the server definition in a token.

export const IS_SERVER_PLATFORM = new InjectionToken<boolean>('Is server?', {
    factory() {
        return isPlatformServer(inject(PLATFORM_ID));
    },
});

Create a structured directive using the IS_SERVER_PLATFORM token with one simple target: render the component only on the server.

@Directive({
    selector: '[ifIsServer]',
})
export class IfIsServerDirective {
    constructor(
        @Inject(IS_SERVER_PLATFORM) isServer: boolean,
        templateRef: TemplateRef<any>,
        viewContainer: ViewContainerRef
    ) {
        if (isServer) {
            viewContainer.createEmbeddedView(templateRef);
        }
    }
}

The code looks similar to the IfIsBowser directive.

Now let's refactor the component:

@Component({
    selector: 'ram-root',
    template: '<some-сomp *ifIsServer"></some-сomp>',
    styleUrls: ['./app.component.less'],
})
export class AppComponent {}

Extra properties have been removed from the component. The component template is now a bit simpler.

Such directives declaratively hide and show content depending on the platform.

We have collected the tokens and directives in the package @ngx-ssr/platform.

5. Memory Leak

Situation

At initialization, the service starts an interval and performs some actions.

import { Injectable, NgZone } from "@angular/core";
import { interval } from "rxjs";

@Injectable()
export class LocationService {
    constructor(ngZone: NgZone) {
        ngZone.runOutsideAngular(() => interval(1000).subscribe(() => {
          ...
        }));
    }
}

This code does not affect the application's stability, but the callback passed to subscribe will continue to be called if the application is destroyed on the server. Each launch of the application on the server will leave behind an artifact in the form of an interval. And this is a potential memory leak.

Possible Solution

In our case, the problem is solved by using the ngOnDestoroy hook. It works for both components and services. We need to save the subscription and terminate it when the service is destructed. There are many techniques for unsubscribing, but here is just one:

import { Injectable, NgZone, OnDestroy } from "@angular/core";
import { interval, Subscription } from "rxjs";

@Injectable()
export class LocationService implements OnDestroy {
  private subscription: Subscription;

  constructor(ngZone: NgZone) {
    this.subscription = ngZone.runOutsideAngular(() =>
      interval(1000).subscribe(() => {})
    );
  }

  ngOnDestroy(): void {
    this.subscription.unsubscribe();
  }
}

6. Lack of rehydration

Situation

The user's browser displays a page received from the server, a white screen flickers for a moment, and the application starts functioning and looks normal.

Why is this happening

Angular does not know how to reuse what it has rendered on the server. It strips all the HTML from the root element and starts painting all over again.

Possible Solution

It still doesn't exist. But there is hope that there will be a solution. Angular Universal's roadmap has a clause: "Full client rehydration strategy that reuses DOM elements/CSS rendered on the server".

7. Inability to abort rendering

Situation

We are catching a critical error. Rendering and waiting for stability are meaningless. You need to interrupt the process and give the client the default index.html.

Why is this happening

Let's go back to the moment of rendering the application. It occurs when the application becomes stable. We can make our application stable faster using the solution from problem #1. But what if we want to abort the rendering process on the first caught error? What if we want to set a time limit on trying to render an application?

Possible Solution

There is no solution to this problem now.

Summary

In fact, Angular Universal is the only supported and most widely used solution for rendering Angular applications on the server. The difficulty of integrating into an existing application depends largely on the developer. There are still unresolved issues that don't allow me to classify Angular Universal as a production-ready solution. It is suitable for landing pages and static pages, but on complex applications, you can collect many problems, the solution of which will break in the blink of the page due to the lack of rehydration.

How to stop being afraid and create your own Angular CLI Builder

Igor Katsuba — Wed, 20 Jan 2021 12:00:34 +0000

Angular CLI v8.0.0 brought us a stable CLI Builders API, which allows you to customize, replace, or even create new CLI commands

Now the most popular builder for customizing the webpack configuration is @angular-builders/custom-webpack. If you look at the source code of all the builders supplied with the package, you will see very compact solutions that do not exceed 30 lines of code.

Maybe make your own?

Challenge Accepted!

This material assumes that you are already familiar with the Angular and Angular CLI, you know what rxjs is and how to live with it, and you are also ready to read 50 lines of code.

So what exactly are these builders?

Bu*ilder* is just a function that can be called using the Angular CLI. It is called with two parameters:

JSON-like configuration object
BuilderContext — an object that provides access, for example, to the logger.

A function can be either synchronous or asynchronous. As a bonus, you can return Observable. But in any case, both Promise and Observable should emit BuilderOutput.

This function, packaged in a certain way in the npm package, can be used to configure such CLI commands as build, test, lint, deploy, and any other from the architect section of the angular.json configuration file.

OK. Will there be just an example from the documentation?

Not. Of course, at first, I made an example, most similar to the example from the documentation. I used such a builder when working with NX and deploying only modified applications. But I suddenly needed a builder who can run commands from angular.json in a certain order and depending on each other.

A more real-world example: you suddenly needed your application running dev-server in tests. There are various console utilities and npm packages for starting and waiting for the server to start, but why not create a builder that can run dev-server in watch mode before running the tests and kill dev-server as soon as the tests are complete?

Where to begin?

You need to start by creating a blank for the package in which we will pack the builders. I generated the workspace using NX, as well as the library blank for the builder.

npx create-nx-workspace ng-builders

cd ./ng-builders

npx ng g @nrwl/node:library build

Build Configuration

This is how I saw the configuration that solved my problem:

// angular.json
{
   "version": 1,
   "projects": {
     "app": {
       "architect": {
         "stepper": {
           "builder": "@ ng-builders / build: stepper",
           "options": {
             "targets": { // description of targets
               "jest": { // target name and configuration
                 "target": "app: jest", // existing task in angular.json
                 "deps": ["server"] // dependent targets that need to be run before the main
               },
               "server": {
                 "target": "app: serve",
                 "watch": true // watch mode
               }
             },
             "steps": ["jest"] // list of goals to complete
           }
         }
       }
     }
   }
 }

In theory, such a task in angular.json can be done using the command:

ng run app:stepper

Having worked a little on the specification, I came to the following interfaces:

export interface Target {
   / **
    * A list of target ids that must be completed before starting the task
    *
    * Differs from Schema#steps in that the task does not wait for the full
    * performing dependent tasks
    * /
   deps?: string[];
   / **
    * Purpose to fulfill
    * /
   target: string;
   / **
    * Turn on watch mode
    * /
   watch?: boolean;
   / **
    * Overriding target configuration parameters
    * /
   overrides?: {[key: string]: any};
 }

 export interface Targets {
   // targetId - task name
   [targetId: string]: Target;
 }

 export interface Schema {
   / **
    * Strict sequence of tasks in the array
    * indicate targetId of Targets
    *
    * The next task is launched only after the previous
    * /
   steps: string[];
   targets: Targets;
 }

The specification is completed. Of course, the scheme can be further expanded and, for example, add a configuration choice (production, dev, etc.), but for v1.0 this will be enough.

JSON schema was also written on these interfaces, which will be used when validating configuration data.

Let’s code

So, we have a configuration interface. When starting a task through the Angular CLI, everything should work wonderfully.

To begin with, write the runStepper function and create the StepperBuilder.

// index.ts
 export function runStepper(
   input: Schema,
   context: BuilderContext
 ): BuilderOutputLike {
   return buildSteps(input, context).pipe (
     map(() => ({
       success: true
     })),
     catchError(error => {
       return of({error: error.toString(), success: false});
     })
   );
 }

 export const StepperBuilder = createBuilder(runStepper);

 export default StepperBuilder;

Note that the type of the first argument of the runStepper function is the same Schema from the configuration specification above. The function returns Observable<BuilderOutput>.

Next, we will implement the buildSteps function, which will be responsible for the steps

 function buildSteps(config: Schema, context: BuilderContext): Observable<any> {
   return concat(
      config.steps.map(step => buildStep(step, config.targets, context))
   );
 }

It seems nothing complicated. Each next step is performed after the previous one is completed.

In fact, we have one thing that remains unknown — the buildStep function, which will run each individual step with its dependencies:

 function buildStep(
   stepName: string,
   targets: Targets,
   context: BuilderContext
 ): Observable<any> {
   const {deps = [], overrides, target, watch}: Target = targets[stepName];

   const deps$ = deps.length
     ?  combineLatest(deps.map(depName => buildStep(depName, targets, context)))
     : of(null);

   return deps$.pipe (
     concatMap(() => {
       return scheduleTargetAndForget(context, targetFromTargetString(target), {
         watch
         ...overrides
       });
     }),
     watch ? tap(noop) : take(1)
   );
 }

There are several interesting points in this function:

Step dependencies run in parallel, and the main task of the step is only after each of the dependencies emits at least one event. For example, this gives us a guarantee that the dev-server (if the task to start it in the list of dependencies of the current step) is launched before running the tests (if this is the main task of the step)
The function scheduleTargetAndForget, imported from @angular-devkit/architect. This function allows you to run targets from angular.json and override their settings. This function returns Observable, unsubscribing from which stops the task in progress.
If the watch parameter has a positive value, then the main task of the step will not end after the first emitted event, therefore the current task will live forever until it completes itself, or until the unsubscribe from the returned Observable, or the process is completed.

Actually, this is all about the builder itself. The full version can be viewed here. Stayed in 56 lines of code. Not bad, right?

The last point that is interesting and important for us is the builders.json file

{
   "$ schema": "../../@angular-devkit/architect/src/builders-schema.json",
   "builders": {
     "stepper": {
       "implementation": "./stepper",
       "schema": "./schema.json",
       "description": "Stepper"
     }
   }
 }

As you can see, this file lists the builders with the parameters “implementation” (entry point for importing the builder), “schema” (validation scheme) and “description”

Then we search for package.json and add the builders property with a relative path to the builders.json file

{
  "name": "@ng-builders/build",
  "builders": "./builders.json",
  …
}

It remains only to collect the package:

npm run build

Add everything into a commit and push all this beauty to Github.

And that’s all?

Yes, that’s all. Three simple functions, a little imagination, and the fulfillment of mandatory configuration contracts are all that is needed to quickly create custom builders for the Angular CLI. But an attentive reader, of course, will point out the lack of tests for a new builder. And I hope that this very reader unexpectedly ignites himself with the desire to close this gap, forks the project, and will try to write tests himself.

The builder can NOT be used (as soon as tests appear, I will definitely remove NOT) in your projects

npm i @ng-builders/build -D

Summary

The CLI Builders API is a powerful tool for extending and customizing the Angular CLI. The builder created by us does not solve the most popular problems, but it took only 1 hour to create the whole package. This means that creating a custom builder to solve particular problems is not such a difficult task.

What other builders can you create? It can be a builder for deploying, testing, and codebase checking for your application using special tools. It all depends on your needs and imagination.

P.S.:

Angular CLI Builders are perfectly used and work in NX Workspace even without Angular. An example of this miracle I will definitely show you in the future. In the meantime, you can read me on Twitter, write to me on Telegram, and speak only good words.

DEV Community: Igor Katsuba

Mutate a code with Angular schematics like a boss

What is a schematic?

Why do we use schematics?

We have a problem

ng-morph

Example #1

Solution.

Example #2

Solution

What else can ng-morph do?

Summary

Links

taiga-family / ng-morph

Code mutations in your project or schematics were never easier than now.

Already using ng-morph

taiga-family / taiga-ui

Angular UI Kit and components library for awesome people

3 steps to understanding Angular

Stage 1. 🧑‍💻 NgMan Begins.

Stage 2. 🥷 CDK Ninja.

Stage 3. 🅰️ Angular FrontOps

Summary

Angular Universal: real app problems

Angular Universal: real app problems

How Angular Universal Works

SSR issues in Angular

1. Infinite page loading

Situation

Why is this happening

Possible Solution

2. Lack of cache out of the box

Situation

Possible Solution

3. Server errors of type ReferenceError: localStorage is not defined

Situation

Why is this happening

Possible Solution

4. Inconvenient separation of logic

Situation

Possible Solution

5. Memory Leak

Situation

Possible Solution

6. Lack of rehydration

Situation

Why is this happening

Possible Solution

7. Inability to abort rendering

Situation

Why is this happening

Possible Solution

Summary

How to stop being afraid and create your own Angular CLI Builder

So what exactly are these builders?

OK. Will there be just an example from the documentation?

Where to begin?

Build Configuration

Let’s code

And that’s all?

Summary

P.S.:

`ng-morph`

What else can `ng-morph` do?

Already using `ng-morph`