#1 Boolean inputs are often unnecessary

In this first problem case, an Angular boolean input is introduced into a component unnecessarily. The logic that depends on the boolean input could also be dependent on other data. Let’s see a simple example. In a ProductComponent there is a boolean @Input showProductDescription. As the name suggests, the variable is used to decide whether a description should be shown for a product.

export class ProductComponent {
  @Input()
  product: Product;

  @Input()
  showProductDescription: boolean;
}

The value for this boolean input is calculated on the consumer side of the ProductComponent. Probably it looks like the following and is solely dependent on the product itself: !!product.description. So, it just checks on the presence of the description value on the product.

The component’s template consumes then the flag in a ngIf:

<article>
  <img [src]="'/assets/images/shop/' + product.image" />
  {{ product.name }} - {{ product.price | price }}

  <p *ngIf="showProductDescription">
    {{ product.description }}
  </p>
</article>

The above implementation comes with the following problems:

• The showProductDescription is an additional input to the ProductComponent and makes its interface more complex.
• If this showProductDescription is also needed further down the component hierarchy it needs to be passed multiple times alongside the product. This makes code hard to change.

The alternative

We can just make the displaying of the paragraph dependent on the description field of the product. Then we can get rid of showProductDescription. The ngIf is therefore updated and receives the argument product.description.

<article>
  <img [src]="'/assets/images/shop/' + product.image" />
  {{ product.name }} - {{ product.price | price }}

  <p *ngIf="product.description">
    {{ product.description }}
  </p>
</article>

This first example was an easy one. I guess most Angular developers do not make such mistakes. However, I have seen such cases already and wanted to point them out too. The next case will be more interesting.

#2 Boolean inputs are hard to extend

As we know a boolean can only have two values (or four if you count null/undefined). When we want to extend by a third variant, we are restricted because of the type. Let’s see an example. For that, we stay with the theme of products. But this time we deal with product availability:

export class ProductAvailabilityComponent {
  @Input() availability: boolean;
}

We have a ProductAvailabilityComponent that shows if the product is available or not. The corresponding template might look like that:

<span *ngIf="availability; else notAvailable">Product is available</span>

<ng-template #notAvailable>
  <span>Unfortunately not available</span>
</ng-template>

And availability is always a boolean, isn’t it? Well, it turns out that our products can be unavailable in the online shop, but could be available for preorder. And we want to inform the customers about that fact. So, now we have three mutually exclusive options: available, available for preorder, and unavailable. But availability is not easily extendable because it’s a boolean. Therefore we add another flag:

export class ProductAvailabilityComponent {
  @Input() availability: boolean;
  @Input() preorderPossible: boolean;
}

Consequently, our template becomes something like this:

<span *ngIf="availability; else notAvailable">Product is available</span>

<ng-template #notAvailable>
  <span *ngIf="preorderPossible; else reallyNotAvailable">
    Not available yet. Preorder possible.
  </span>

  <ng-template #reallyNotAvailable>
    <span>Unfortunately not available</span>
  </ng-template>
</ng-template>

This doesn’t look too good. The template is already a bit bloated and the ngIf-else logic is not ideal. Especially if we would like to add a fourth possible value in the future it’s not clear at first sight how to do it. But there is for sure a cleaner way.

The alternative

We need to define the availability as an extendable data type. In this case, we choose a union type. Availability changes from boolean to:

export type Availability = 'AVAILABLE' | 'NOT_AVAILABLE' | 'PREORDER_POSSIBLE';

And our component and template can be simplified to the following:

export class ProductAvailabilityComponent {
  @Input() availability: Availability;
}

<div [ngSwitch]="availability">
  <span *ngSwitchCase="'AVAILABLE'">Product available</span>
  <span *ngSwitchCase="'PREORDER_POSSIBLE'">Not available yet. Preorder possible.</span>
  <span *ngSwitchCase="'NOT_AVAILABLE'">Unfortunately not available</span>
</div>

This is more extendable and we can even add a fourth value without a problem.

#3 Boolean inputs cause breaking changes

This is related to point #2 above. The consumer of the ProductAvailabilityComponent relied on a boolean and now would have to pass the two booleans availability and preorderPossible. This is a breaking change in most situations. Would the data type have been the Availability union type from the beginning then the consumer can adapt more easily.

This becomes even clearer when the ProductAvailabilityComponent is deep down a component tree. The type potentially has to be adapted in the whole chain from Store, StoreFacade, ProductPageComponent, ProductComponent, ProductDetailComponent to ProductAvailabilityComponent. Depending on the setup and where the product availability is determined this could result in changes in a lot of files.

The alternative is, as mentioned, to use a type that allows adding further values. Also moving from the boolean to the union type is quite some change. You should go with the more extendable type from the beginning if you can’t rule out an extension to the values.

#4 Boolean inputs bloat your templates

Here we are considering again the example from point #2 where we had the two boolean flags and ended up with the following template:

<span *ngIf="availability; else notAvailable">Product is available</span>

<ng-template #notAvailable>
  <span *ngIf="preorderPossible; else reallyNotAvailable">
    Not available yet. Preorder possible.
  </span>

  <ng-template #reallyNotAvailable>
    <span>Unfortunately not available</span>
  </ng-template>
</ng-template>

This looks terrible. It is hard to read and hard to extend. Especially if all options are mutually exclusive there is a cleaner way where everything is on one level.

The alternative

We have already seen a better way and it looked like that using a ngSwitch:

<div [ngSwitch]="availability">
  <span *ngSwitchCase="'AVAILABLE'">Product available</span>
  <span *ngSwitchCase="'PREORDER_POSSIBLE'">Not available yet. Preorder possible.</span>
  <span *ngSwitchCase="'NOT_AVAILABLE'">Unfortunately not available</span>
</div>

All the cases are handled the same way which brings clarity and consistency. But we can even simplify more in certain situations when it is just about showing the text:

<span>{{ ('PRODUCT_AVAILABILITY.' + availability ) | translate }}</span>

The translation keys can be directly constructed based on the availability union type value. This leaves us with a one-liner in the template compared to about 9 lines before.

Conclusion

Importantly, you should not stop entirely using boolean inputs in Angular. But you should think carefully about the above scenarios when introducing one. In a lot of cases, your code becomes simpler and better maintainable when you choose alternative types.
If the boolean input really maps to something that is not extendable and completely boolean it might be okay.

Another interesting article on boolean parameters in general, is What is wrong with boolean parameters? They suggest splitting methods that have a boolean parameter. Related to that, you could also think of splitting into two different components for certain cases where you started with a boolean input for a single component.

The post Why you should stop using boolean @Input in Angular appeared first on Ronnie Schaniel.

We saw how to generate a basic Angular http service with a schematic in the previous post. What if we want to easily add a new call to an existing service the same way? Just using the basic Angular schematic for http services would replace the file. Then we probably loose some other methods or imports.

This is why we will explore in this article how to update existing files. Specifically we will add a new method to an existing service class.

But first we need to understand what an Abstract Syntax Tree is.

AST Basics

An Abstract Syntax Tree (AST) describes a programming language’s source file. As the name suggests, constructs like classes or methods are represented as a tree. Let’s check the AST of the following simple TypeScript class to understand it:

export class Service {
    public call(): Observable<Response> {
        return of(null);
    }
}

The tree behind this source “file” looks as follows:

On the left hand side, we see the high-level view. There is a ClassDeclaration with an Identifier as child. Another child of the ClassDeclaration is of course the MethodDeclaration. Since the class Service has a method call there is a direct parent-child relation between those two language constructs. All those children (and also the SourceFile itself) are Nodes.

Furthermore, as we can see on the right hand side of above picture, the Identifier is another interesting child of the ClassDeclaration. The Identifier contains the name of the class in the escapedText, here “Service”. So, basically the AST gives you the access to everything in the code in a structured way.

How do we read a tree programmatically? We have to traverse it and check the attributes of the nodes to find a node we’re interested in.

Reading an Existing File

Our goal is to add a method for an HTTP call into an existing Angular http service. As an example we take the following service that already contains two methods to load customers by GET.

import { Injectable } from '@angular/core';
import { HttpClient } from '@angular/common/http';
import { Observable } from 'rxjs';

@Injectable({
  providedIn: 'root',
})
export class CustomerHttpService {
  private readonly baseUrl = '';

  constructor(private http: HttpClient) {
  }

  public getAll(): Observable<Customer[]> {
    return this.http.get<Customer[]>(this.baseUrl);
  }

  public getById(id: number): Observable<Customer> {
    return this.http.get<Customer>(`${this.baseUrl}/${id}`);
  }
}

If we now want to add a method to the CustomerHttpService class we need to know a few things:

• What is the source text of the customer.http-service.ts file in an Angular project?
• Where is our existing Service class in the tree, i.e. CustomerHttpService?
• What is the last position in the file for a certain method within CustomerHttpService, e.g. what is the position of the closing } for the getById method?

Basic Angular add http call schematic function

The high-level view of our schematic function is shown in the code below.

export function addHttpCall(_options: any): Rule {
    return (tree: Tree, _context: SchematicContext) => {
        const workspaceConfigBuffer = tree.read('angular.json');
        if (!workspaceConfigBuffer) {
            throw new SchematicsException('Not an Angular CLI workspace! The angular.json file is missing');
        }
        const methodName = 'getById';

        // steps 1 to 5:
        const filePath = determineTargetFilePath(workspaceConfigBuffer, _options);
        const nodes: ts.Node[] = getASTFromSourceFilePath(tree, filePath);
        const lastPositionOfMethod = getLastPositionOfMethod(nodes, methodName);
        const methodAddChange = createInsertChange(filePath, lastPositionOfMethod!);
        updateTree(tree, filePath, methodAddChange);

        return tree;
    };
}

To get some helper methods we install a schematics package:

npm i @schematics/angular

Please also install @angular-devkit/schematics and @angular-devkit/core if not yet done.

We want to keep things simple at the moment. So, we skip a few inputs for the schematic, like the HTTP method or the placeMethodAfterExistingMethodNamed. So, the schematic can be called as follows:

ng generate add-http-call shared/services/Customer

We have divided the overall functionality into 5 steps:

1. Determining the file path in the Angular project dependent on the input (shared/services/Customer is mapped to the correct path in the project)
2. Having the file path we can read the existing file, create a temporary source file and create the AST for that file
3. In the AST we search for a method after which we want to position our new method. In this example I simplified it by hardcoding ‘getById’. So, we will return the last position of the getById method.
4. Based on the position and file path we can create an InsertChange object to modify the actual file. In the InsertChange we hardcode the method to a create() method using POST.
5. Finally the tree is updated with the InsertChange for the new method

These 5 steps are described in the rest of this section.

1. Determine target file path

We use the workspace config together with the options to find the file path:

function  determineTargetFilePath(workspaceConfigBuffer: Buffer, _options: any): string {
    const workspaceConfig = JSON.parse(workspaceConfigBuffer.toString());
    const projectName = _options.project || workspaceConfig.defaultProject;
    const project = workspaceConfig.projects[projectName];

    const defaultProjectPath = buildDefaultPath(project);
    const parsedPath = parseName(defaultProjectPath, _options.name);
    const {name, path} = parsedPath;

    const filePath = `${path}/${name.toLowerCase()}.http-service.ts`;
    return filePath;
}

This is somewhat basic code for a lot of schematics. After reading the angular.json config we create the file name. In our case we assume that http service files end with http-service.ts. Like that we find the customer.http-service.ts.

2. Retrieve source code and create the AST

Now it becomes interesting. We create the AST based on the file path:

function getASTFromSourceFilePath(tree: Tree, filePath: string): ts.Node[] {
    const content = tree.read(filePath);
    if (!content) {
        throw new SchematicsException(`File ${filePath} does not exist.`);
    }

    const sourceText = content.toString('utf-8');
    const sourceFile = ts.createSourceFile(filePath, sourceText, ts.ScriptTarget.Latest, true);
    const nodes = getSourceNodes(sourceFile);
    return nodes;
}

The schematic’s Tree helps us to read the file content. Based on the sourceText we can then create a TypeScript file. Now we are using the getSourceNodes method from @schematics/angular/utility/ast-utils to get the AST of this source file.

3. Find the last position of an existing method

We read a file and got the AST of that file. Now we need to work with this AST. That means we need to traverse the tree and find relevant nodes.

function getLastPositionOfMethod(nodes: ts.Node[], methodName: string) {
    const serviceClassNode = findServiceClassNode(nodes[0]);
    if (!serviceClassNode) {
        throw new SchematicsException(`Did not find a service class node`);
    }

    const methodNode = findMethodNode(serviceClassNode, methodName);
    if (!methodNode) {
        throw new SchematicsException(`Did not find the ${methodName}`);
    }

    const lastPositionOfMethod = getLastPosition(methodNode);
    return lastPositionOfMethod;
}

In simple words we are finding the last position of the ‘getById’ method by:

• traversing through the nodes to find the service class node (helper method findServiceClassNode)
• starting from this service class node to find the method’s node (helper method findMethodNode)
• examining the methodNode and returning the last position of it in the file (helper method getLastPosition)

The helper methods are available here https://github.com/rschaniel/ng-blocks-factory/blob/main/src/add-http-call/ast-utils/ast-utils.ts if you are interested in the details. Probably there are more efficient and safer ways to traverse the tree. Anyway the created utils were good enough to get a basic example running and should be optimised later.

4. Generate the new method

We have found the last position of an existing method. This allows us to create a change for the file because now we know where to insert the new code.

function createInsertChange(filePath: string, lastPositionOfMethod: number) {
    const methodToAdd = 'public create(customer: Customer): Observable<Customer> {\n' +
        '    return this.http.post<Customer>(this.baseUrl, customer);\n' +
        '  }';
    const methodAddChange = new InsertChange(filePath, lastPositionOfMethod! + 1, methodToAdd);
    return methodAddChange;
}

First we create the text for the new method as simple string. The methodToAdd is currently hardcoded to keep things simple. Based on this String we can then create an InsertChange by specifying also the filePath and the position where to insert. In our case we are just inserting one position after the } of our getById.

5. Insert change into an Existing File

Lastly, we can insert the change into our tree. This is what happens in the updateTree method.

function updateTree(tree: Tree, filePath: string, methodAddChange: InsertChange) {
    const declarationRecorder = tree.beginUpdate(filePath);
    declarationRecorder.insertLeft(methodAddChange.pos, methodAddChange.toAdd);
    tree.commitUpdate(declarationRecorder);
}

We start kind of a transaction and add our change to that transaction before committing the update. This transaction is especially helpful of course in case of multiple changes that could go wrong. In the last step the tree is returned from the schematics method and our service file is updated.

Using the add-http-call Angular Schematic to Update a Service

After building the schematic project we can use it in an Angular project:

ng generate ../ng-blocks-factory/src/collection.json:add-http-call shared/services/Customer

If all went well we should see a success message in our terminal:

Our customer.http-service.ts file’s size increased by 696 bytes and if we open it we can find a new method:

Correcting the formatting should be easy then.

Summary and Limitations

You could see above how to do basic file updates with Angular schematics. In our case it was just adding a method. However, the same principles can be reused to change code in other ways. Nevertheless the described approach has some limitations. Hence, the next steps should be:

• Format the code after inserting the change into a file. Probably it’s a good idea to reuse existing format tools, e.g. prettier
• Having a more robust and user friendly AST util or find an npm package that already offers such functionality
• The added method is based on some assumptions, e.g. the HttpClient field is named http. This could also be retrieved dynamically from the existing file by checking the constructor AST.
• It is not checked if the method already exists in the file or a method with the same name.

Please find the code for this Angular add-http-call schematic on GitHub.

Finally the question: is it worth it? All this complicated tree traversal just to add three lines of code? In this basic example, I’d say no. But what if there is more code involved for such updates? Generating mocks, generating io-ts types, updating related NgRx files, etc.

The post Angular Schematics – Add Method to an HTTP Service appeared first on Ronnie Schaniel.

We all know about the value of ng g c HeaderComponent. The powerful angular schematics are part of basically every Angular developer’s repertoire. But still we often tend to create those components, services, pipes, etc. and then always add the same code to the generated files:

• We generate a dumb component and add the ChangeDetectionStrategy.OnPush manually
• A container component is generated but the store field is added manually to the constructor and the ngOnDestroy to unsubscribe from Observables too
• The angular CLI generates a service for us but when we want to add an HTTP request to that service manual work is involved

In this article we want to tackle the last point of the list above: using angular schematics to generate HTTP services. Generally, there are two main approaches:

• Extending the schematic for services used in the Angular CLI
• Creating a new schematic on our own

Because we don’t really need much of what is generated in case of a normal service we go for the second option. If we’re interested in spec file generation or want to keep much of what is generated, the first option would be more fitting.

Basic Setup for Angular Schematics

Angular schematics should be hermetic and standalone. Therefore we will create a separate project where our schematics are developed. Later this project can be consumed as a dependency in those projects that want to generate http services.

To get started we install the angular-devkit schematics-cli globally.

npm i -g @angular-devkit/schematics-cli

We want to generate a general angular building blocks schematic project with the following command:

schematics blank --name=ng-blocks-factory

Now we’ve got a blank project where we can develop our schematics:

Most interesting for us are the following two files:

• collection.json defines all the schematics available
• ng-blocks-factory/index.ts is the main file for our first schematic

We will rename a bit. The ng-blocks-factory folder inside src is changed to http-service to better indicate what the first schematic is about (don’t forget to rename inside the collection.json file too).

In the project we install another dependency that will give us some useful methods when working with schematics:

npm i --save-dev @schematics/angular

So far so good. We have a project and a more or less empty schematic.

Define the Angular schematics input parameters for the http service

In our use case a developer wants to create an HTTP service. Let’s think a moment about the basic inputs. I guess we can start with a name and base url. If we follow REST principles these two arguments should already suffice to generate the needed methods in the http service.

Hence, we create the following schema.json for our http-service schematic. This schema.json defines the inputs.

{
  "$schema": "http://json-schema.org/schema",
  "$id": "HttpServiceSchema",
  "type": "object",
  "properties": {
    "path": {
      "type": "string",
      "format": "path",
      "visible": false
    },
    "name": {
      "type": "string",
      "$default": {
        "$source": "argv",
        "index": 0
      }
    },
    "url": {
      "type": "string",
      "$default": {
        "$source": "argv",
        "index": 1
      }
    }
  },
  "required": [
    "name",
    "url"
  ]
}

The file should be located in the http-service folder. Alongside url and name, we’ve also got a path input parameter. This path points to the location where the service should actually be created inside a project.

Afterwards we also need to update our collection.json to include the schema.json of the http-service schematic. We’re also updating the function name in the index.ts file. This function name is used to reference the factory in the schema.json (httpService in our case after #):

{
  "$schema": "../node_modules/@angular-devkit/schematics/collection-schema.json",
  "schematics": {
    "http-service": {
      "description": "Generate http services",
      "factory": "./http-service/index#httpService",
      "schema": "./http-service/schema.json"
    }
  }
}

Implementing the factory function

The index.ts contains the factory function used to create the files in our schematic. As a parameter it receives the options passed by the user (and defined in the schema.json). The basic version should look similar to that below.

import { Rule, SchematicContext, Tree } from '@angular-devkit/schematics';

export function httpService(_options: any): Rule {
    return (tree: Tree, _context: SchematicContext) => {
        return tree;
    };
}

We extend that file by the following parts:

• We first check if we’re in an Angular CLI workspace. If so, we read the workspace config, i.e. angular.json
• The options name and path are cleaned up and the path constructed based on the passed project (or default project).
• The template sources are defined. They point to a files folder where our templates will be added later. In the template function we provide the options alongside the functions classify and dasherize. This ensures that those values and functions are available in our template.

This should be the result:

export function httpService(_options: any): Rule {
    return (tree: Tree, _context: SchematicContext) => {
        const workspaceConfigBuffer = tree.read('angular.json');
        if (!workspaceConfigBuffer) {
            throw new SchematicsException('Not an Angular CLI workspace! The angular.json file is missing');
        }

        const workspaceConfig = JSON.parse(workspaceConfigBuffer.toString());
        const projectName = _options.project || workspaceConfig.defaultProject;
        const project = workspaceConfig.projects[projectName];

        const defaultProjectPath = buildDefaultPath(project);
        const parsedPath = parseName(defaultProjectPath, _options.name);
        const {name, path} = parsedPath;

        const templateSource = apply(
            url('./files'),
            [
                template({
                    ..._options,
                    classify: strings.classify,
                    dasherize: strings.dasherize,
                    name,
                }),
                move(path),
            ],
        );

        return mergeWith(templateSource)(tree, _context)
    };
}

The @schematics/angular utility method buildDefaultPath didn’t really work in my case and threw an error (reg. projectType property). That’s why I implemented the method myself as follows:

function buildDefaultPath(project: any) {
    const root = project.sourceRoot ? `/${project.sourceRoot}/` : `/${project.root}/src/`;
    const projectDirName = project['projectType'] === 'application' ? 'app' : 'lib';
    return `${root}${projectDirName}`;
}

This is our index.ts file. Next we can create the template file for our service.

Creating the Template for our Http Service

Templates in schematics are used as a base for the generated files. For our service we create a file named __name@dasherize__.http-service.ts in our http-service/files folder. The __name__ part refers to the name option passed to the templates in the index.ts file. To have a nice name we use @dasherize to format, e.g. ShoppingCart to shopping-cart. Because in the end we want to have dashes in our file names.

The content of the file will look similar to normal Angular service files, but the option values are included by using the <%= %> syntax.

import { Injectable } from '@angular/core';
import { HttpClient } from '@angular/common/http';
import { Observable } from 'rxjs';

@Injectable({
    providedIn: 'root',
})
export class <%= classify(name) %>HttpService {
    private readonly baseUrl = '<%= path %>';

    constructor(private http: HttpClient) {}

    public getAll(): Observable<<%= name %>[]> {
        return this.http.get<<%= name %>[]>(this.baseUrl);
    }

    public getById(id: number): Observable<<%= name %>> {
        return this.http.get<<%= name %>>(`${this.baseUrl}/${id}`);
    }
}

export interface <%= classify(name) %> {
    id: number;
    // other properties
}

As a start we are adding two GET calls to load either all resources or a specific resource identified through its ID. So, this template is created based on the following assumptions taking Customer as an example.

• All customers are available under the base url defined by the path, e.g. /api/v1/customers
• A specific customer is exposed under /api/v1/customers/<ID>
• The returned object’s type is Customer

To have valid code we define the interface for the response type inside the http service file. In the end that should probably be moved to a separate file.

After the factory function we now also have our template ready and can start to test our schematic.

Test the Schematic in an Angular Project

To test the schematic we first have to build it:

npm run build

Afterwards we can link it locally from an Angular Project. This assumes that your Angular project is on the same folder level as your ng-blocks-factory schematic project.

npm i --save-dev ../ng-blocks-factory

The schematic project is installed and we can now execute the schematic:

ng generate ng-blocks-factory:http-service Customer /api/v1/customer

We could also skip the installing and just execute the schematic by specifying the path to the collection as well as adding the schematic name after the colon:

ng generate ../ng-blocks-factory/src/collection.json:http-service shared/services/Customer /api/v1/customer 

This generates an http service for us:

import { Injectable } from '@angular/core';
import { HttpClient } from '@angular/common/http';
import { Observable } from 'rxjs';

@Injectable({
    providedIn: 'root',
})
export class CustomerHttpService {
    private readonly baseUrl = '';

    constructor(private http: HttpClient) {}

    public getAll(): Observable<Customer[]> {
        return this.http.get<Customer[]>(this.baseUrl);
    }

    public getById(id: number): Observable<Customer> {
        return this.http.get<Customer>(`${this.baseUrl}/${id}`);
    }
}

export interface Customer {
    id: number;
    // other properties
}

We’ve got our service generated. So, in the future we can just use a simple command instead of copying an existing services or generating a normal service and adding all the http part.

Of course you should probably build and publish your schematic to have an easy integration into any project. Finally, you could also add POST, PUT, PATCH and DELETE methods to your template.

The source are available on GitHub.

The post Angular Schematics – Generate an Http Service appeared first on Ronnie Schaniel.

Previously Webpack wanted to know all dependencies at compile time. With module federation dependencies can be resolved at run time. This allows us to deploy microfrontends independently while having a smooth integration. Despite all that hype and the technical possibilities, we should be careful. It is vital to think about the scenarios where module federation usage makes sense.

Let’s go through an example based on our eCommerce Playground Angular app. In this context we compare module federation to approaches using default Angular modules and additional Angular applications running separately.

Our Goal: Adding an Overview of Orders

Our application currently looks like this:

It’s an online shop with e.g. product list, search box and navigation bar at the bottom. Our customers want to have an overview of their orders. That’s why we plan to integrate an orders overview page and link it in the header behind “My Orders”.

Different Variants for the Solution

There are different variants how to integrate such an orders overview. We will explore 3 different ones. In this context the “main” app is the eCommerce application and “orders” the orders overview.

1) Integrate as Standard Angular Module

The most obvious solution is just to create a separate Angular Module and lazy load it through the router. This gives you the following advantages:

• 🧩 Smooth integration and lazy loading
• 🖇 Easy code sharing between main and orders

But this approach also comes with some drawbacks:

• ⏳ Main app build takes longer
• 📦 No separate deployments
• 🖇 More tightly coupled

2) Use a Second Angular App on a Specific URL

We can build a separate Angular app for the orders overview and just deploy it under the link behind “My Orders”. This gives us the following:

• ⏳ Lower build time because separated
• 📦 Standalone deployment possible

But it comes with disadvantages:

• 🧩 The integration is not smooth
• ⏱ Shared dependencies downloaded twice

3) Integrate by Using Module Federation

Finally, we are having a look at the new possibility. Webpack module federation allows us to integrate the orders overview like a module but still having it as a separate application. We walk through a short how-to for adding module federation and then come to the evaluation.

Setup webpack version 5

We need webpack version 5 to make use of module federation. First, we want to switch to yarn as package manager:

ng config cli.packageManager yarn

When we use yarn instead of npm, the resolutions section in the package.json forces our dependencies, e.g. the Angular CLI, to use a certain webpack version we specify. So, we can enable webpack 5 in our package.json:

"resolutions": {
    "webpack": "^5.0.0"
},

Finally run yarn install to get all the dependencies considering webpack 5:

yarn install

Create a project in the workspace

We assume you are having a nx workspace. With the following command we create a second project in that workspace named “orders”:

nx generate @nrwl/angular:app orders

There we add OrderModule with a component that shows the orders. Nothing fancy and nothing worth showing.

Adding module federation

We need some customisation for the Angular CLI to change the webpack behaviour. That’s why we install and use @angular-architects/module-federation (thanks to Manfred Steyer). Let’s configure module federation for our two projects with the following commands:

ng add @angular-architects/module-federation --project main --port 4200 
ng add @angular-architects/module-federation --project orders --port 5000

Main should run under port 4200, while orders is running on 5000.

Configure the orders app as federated module

Now we would be able to run the two apps, main and orders, but they are not really integrated yet. Let’s first add the relevant configuration to the “microfrontend”, i.e. orders app. Let’s first edit the webpack.config.js. Thanks to the module-federation package added above, the relevant config is already added to the ModuleFederationPlugin, but commented out. So, let’s enable the part for the orders app that is a “remote”:

// For remotes (please adjust)
name: "orders",
filename: "remoteEntry.js",
exposes: {
    './OrderModule': './apps/orders/src/app/order/order.module.ts',
},   
shared: {
  "@angular/core": { singleton: true, strictVersion: true }, 
  ...

We are setting a name and exposing a module. This is it for the orders app that functions as a remote in our federated module landscape. Note that libraries under “shared”, e.g. @angular/core, will only be downloaded once.
Further adjustments were done previously when installing the module-federation package. Please check for example the main.ts of the orders app.

Integrate the orders app into the main app

We have the orders app ready to be integrated as federated module. Let’s first add a route to the routing config of the main app:

{
  path: 'orders',
  loadChildren: () => import('orders/OrderModule').then(m => m.OrderModule)
},

We specify a path and a loadChildren function similar to traditional Angular modules. In the import path we specify the microfrontend “orders” and its Module. The TypeScript compiler is not happy about that because the ‘orders/Module’ is not known in the main app. To make the compiler happy again we can add a type definition by creating a decl.d.ts in the main app’s src directoy

declare module 'orders/OrderModule';

We also add an actual link to the new route in our template:

<a [routerLink]="['/orders']">My Orders</a>

As a last step we update the webpack.config also on the main app’s side. This time the “host” section is the relevant one:

// For hosts (please adjust)
remotes: {
     "orders": "orders@http://localhost:5000/remoteEntry.js",
},

We are telling webpack that the “orders” remote is found on port 5000.

Running everything

Let’s start both applications in separate terminals:

ng serve main
ng serve orders

If we now click on the “My Orders” link in the header the order list is shown:

In the network tab we see a common.js loaded that contains the OrderListComponent (but not the entire Angular package). The integration is very smooth and one doesn’t really notice that the functionality is coming from a different app.

Conclusion

Of course this was a quick walkthrough and possibly the simplest setup for webpack federated modules. But it demonstrated the idea and we can summarise the benefits as following:

• 🧩 The integration is smooth
• ⏳ Lower build time because separated
• 📦 Standalone deployment possible
• ⏱ Shared dependencies downloaded only once

My verdict on webpack module federation: something to try out!

Again, sources for above example can be found on GitHub.

The post Webpack Module Federation in Angular appeared first on Ronnie Schaniel.

Setting up Jenkins

First, we create the needed configuration in Jenkins, by creating a new pipeline:

The source code of our application should be coming from GitHub. So, we need to setup a connection. On the machine, where we are running Jenkins, we create a public/private key pair:

ssh-keygen -t rsa -b 4096

We add the public key to GitHub under deploy keys. And set the following for our pipeline in Jenkins:

If there is no red error message below the “Repository URL” field, you have successfully connected the GitHub repository to Jenkins.

As we have an Angular project we need to execute npm scripts for building and testing our application. So, we need NodeJs. Let’s install it under “Manage Jenkins” → ”Manage Plugins” → “Available”:

Next, we navigate to “Manage Jenkins” → “Global Tool Configuration” and make sure that a node version is installed and configured:

The name “node” here is important. It will be used later on. At this point Jenkins is set up for our needs and we can continue with the Angular project.

Configuring the Angular Project

The prerequisite for this part is that you have an Angular project ready that already uses Cypress (check for example this post) or other tutorials.

We don’t want to have our pipeline configuration stored in the Jenkins itself. What we want is the pipeline defined as code. Hence, we create a “Jenkinsfile” in our project’s root directory:

pipeline {
    agent any
    tools {nodejs "node"}

    environment {
        CHROME_BIN = '/bin/google-chrome'
    }

    stages {
        stage('Dependencies') {
            steps {
                sh 'npm i'
            }
        }

        stage('Build') {
            steps {
                sh 'npm run build'
            }
        }

        stage('Unit Tests') {
            steps {
                sh 'npm run test'
            }
        }

        stage('e2e Tests') {
            steps {
                sh 'npm run cypress:ci'
            }
        }

        stage('Deploy') {
            steps {
                echo 'Deploying....'
            }
        }
    }
}

We tell the pipeline to use Node.js with the version “node” previously defined. Additionally, you have to make sure that you have Google Chrome installed and referenced in the Jenkinsfile. The exact definition of the ‘Deploy’ stage is left out here for simplicity. This is a task for you.

We use a Chrome Browser for unit testing. Hence, we adjust our karma.conf.js to use the headless Chrome:

customLaunchers: {
  ChromeHeadless: {
    base: 'Chrome',
    flags: [
      '--headless',
      '--disable-gpu',
      '--no-sandbox',
      '--remote-debugging-port=9222',
    ]
  }
},
browsers: ['ChromeHeadless'],

That means we have our unit tests running. Let’s continue with the Cypress tests. If you have problems running Cypress in Jenkins, this excellent article will help: https://medium.com/aubergine-solutions/install-cypress-io-front-end-testing-tool-dependencies-on-amazon-linux-ami-ec2-instance-f676da4abbdd.

For the Cypress part we install the following node package that allows us to execute commands in parallel:

npm install concurrently --save-dev

And extend our package.json scripts section by:

"cypress:ci": "concurrently \"cypress run\" --kill-others \"ng serve\" --success first",

Running the build

The “cypress:ci” task will be executed by the “e2e Tests” step in the Jenkins pipeline. Now we can press the “Build Now” button in the Jenkins and get the following result:

When inspecting the console output of the build, we can verify that the Cypress tests really ran:

But what if a test fails? Currently we would need to check the console output in Jenkins to figure out what went wrong. What we need is a test reporter for Mocha. To have the relevant settings we put the following into the cypress.json file in our project’s root directory:

{
  "reporter": "junit",
  "reporterOptions": {
    "mochaFile": "results/cypress-report.xml",
    "toConsole": true
  }
}

For this to work we need to have the JUnit Plugin installed in the Jenkins. That should already be the case by default. We then insert a “post” block after the “stages” in our Jenkinsfile:

stages {
    ...
} post {
    always {
        junit 'results/cypress-report.xml'
    }
}

Thus, an action is added to the end of the pipeline, which is generating the test report and allows us to see the failing tests:

That’s it for now. Our Cypress tests run in Jenkins. The complete sources are available on GitHub. As a next step, you could look into Parallelisation of cypress tests to decrease your overall build time. And of course it would be cool to also see the screenshots and videos of the failed tests directly in Jenkins.

The post Cypress e2e Testing in the Jenkins Pipeline appeared first on Ronnie Schaniel.

We go through the process of integrating Cypress into an Angular project followed by writing and running a test. The example project we are using comes from the heroes tutorial that you probably know. After downloading the tutorial’s sources and installing it’s dependencies via npm, we add the Cypress package:

npm i cypress --save-dev

This command not only installs the Cypress node package but also creates a “cypress” directory in our Angular project. Within that directory we find examples for fixtures and tests amongst other stuff. The “integration” directory is the one wherein we write our tests later.

Next we create a cypress open command in the scripts section of our package.json alongside the `ng` command and others (that are omitted below):

"scripts": {
  "ng": "ng",
  "cypress:open": "$(npm bin)/cypress open"
},

It allows us to fire up the Cypress Electron app by executing `npm run cypress:open`. Once started, the Cypress app shows us the example tests that we can explore.
Before we use this app further though, we should write our own test. For that we create a new test file from our project directory:

touch cypress/integration/sample_spec.js

The Cypress app has auto reloading. So, if we switch back to it we can see the sample_spec.js file listed.

A click on the sample_spec.js opens the Chrome browser, where we have the following view:

So, Cypress notifies us that our test file does not contain a test yet. Let’s change that by putting content into sample_spec.js:

describe('Testing the hero list page', function() {
  it('should contain the word heroes', function() {
    cy.visit('http://localhost:4200');
    cy.contains("Heroes");
  });
});

Probably this looks quite familiar to you. What you see is the BDD syntax of mochajs with its expressions “describe”, “it”, and so on. Cypress itself offers a lot of test methods that we can access through the cy object.
No servers, drivers or other dependencies are needed. Only one thing is left to run the test. Of course we need to start the Angular app now to give Cypress a website to test:

npm start

Back on the Cypress app’s test browser the test has already run. We have the following result:

On the left hand side the test results are displayed. While on the right hand side the page under test is shown. The test is green since the page contains the word “Heroes”. You could even inspect the right hand side and debug. In the end it’s a browser.

Let’s compare our Cypress test browser view to the protractor output of a similar test:

I don’t know about you, but I prefer the Cypress view.

To conclude, the Cypress installation is straight-forward. There is zero configuration needed. Most importantly the test runs quickly and a nice interface shows exactly what went well or wrong. Cypress appears way more user friendly than for example Protractor. So, after this first steps, Cypress seems to be really the “Test runner built for humans”.

This is all it needs to get started with Cypress in Angular. For further steps and information to all the great features the excellent Cypress website https://www.cypress.io/ should be consulted.

The post Getting Started with Cypress e2e Testing in Angular appeared first on Ronnie Schaniel.