DEV Community: Manfred Steyer

Tutorial: Getting Started with Webpack Module Federation and Angular

Manfred Steyer — Sun, 29 Nov 2020 14:06:03 +0000

This tutorial shows how to use Webpack Module Federation together with the Angular CLI and the @angular-architects/module-federation plugin. The goal is to make a shell capable of loading a separately compiled and deployed microfrontend:

This topic is also an important part of our Angular Workshop with a focus on Architectures (100% Online, Advanced, available in English and German)

Part 1: Clone and Inspect the Starterkit

In this part you will clone the starterkit and inspect its projects.

Clone the starterkit for this tutorial:

git clone https://github.com/manfredsteyer/module-federation-plugin-example.git --branch starter

Have a look to the package.json. You should find this section:
```
"resolutions": {
  "webpack": "5.0.0"
},
```
This section makes yarn to install webpack 5 for the CLI (and for all the other libraries depending on webpack).
Move into the project directory and install the dependencies with yarn:
```
cd module-federation-plugin-example
yarn
```
You really need to install the dependencies with yarn because providing resolutions as shown above is a yarn feature.
Start the shell (ng serve shell -o) and inspect it a bit:
1. Click on the flights link. It leads to a dummy route. This route will later be used for loading the separately compiled microfrontend.
  
  Please ignore depreaction warnings. They are a temporal issue in the current CLI beta when using webpack 5.
2. Have a look to the shell's source code.
  
  Please note that the current CLI beta lacks some features when using it with webpack 5, e. g. reloading an application in debug mode (when using ng serve). Hence, you have to restart ng serve after changing a source file. This is just a temporal limitation and will be solved with one of the upcoming versions.
3. Stop the CLI (CTRL+C).
Do the same for the microfrontend. In this project, it's called mfe1 (Microfrontend 1) You can start it with ng serve mfe1 -o.

Part 2: Activate and Configure Module Federation

Now, let's activate and configure module federation:

Install @angular-architects/module-federation into the shell and into the micro frontend:
```
ng add @angular-architects/module-federation --project shell --port 5000

ng add @angular-architects/module-federation --project mfe1 --port 3000
```
This activates module federation, assigns a port for ng serve, and generates the skeleton of a module federation configuration.

Switch into the project mfe1 and open the generated configuration file projects\mfe1\webpack.config.js. It contains the module federation configuration for mfe1. Adjust it as follows:

const ModuleFederationPlugin = require("webpack/lib/container/ModuleFederationPlugin");

[...]

module.exports = {
    output: {
        uniqueName: "mfe1"
    },
    optimization: {
        // Only needed to bypass a temporary bug
        runtimeChunk: false
    },
    plugins: [
        new ModuleFederationPlugin({

            // For remotes (please adjust)
            name: "mfe1",
            filename: "remoteEntry.js",

            exposes: {
                './Module': './projects/mfe1/src/app/flights/flights.module.ts',
            },        
            shared: {
                "@angular/core": { singleton: true, strictVersion: true }, 
                "@angular/common": { singleton: true, strictVersion: true }, 
                "@angular/router": { singleton: true, strictVersion: true },
                [...]
            }
        }),
        [...]
    ],
};

This exposes the FlightsModule under the Name ./Module.. Hence, the shell can use this path to load it.

Switch into the shell project and open the file projects\shell\webpack.config.js. Adjust it as follows:

const ModuleFederationPlugin = require("webpack/lib/container/ModuleFederationPlugin");

[...]

module.exports = {
    output: {
        uniqueName: "shell"
    },
    optimization: {
        // Only needed to bypass a temporary bug
        runtimeChunk: false
    },
    plugins: [
        new ModuleFederationPlugin({
            remotes: {
                'mfe1': "mfe1@http://localhost:3000/remoteEntry.js" 
            },
            shared: {
                "@angular/core": { singleton: true, strictVersion: true }, 
                "@angular/common": { singleton: true, strictVersion: true }, 
                "@angular/router": { singleton: true, strictVersion: true },
                [...]
            }
        }),
        [...]
    ],
};

This references the separately compiled and deployed mfe1 project. There are some alternatives to configure its URL (see links at the end).

Open the shell's router config (projects\shell\src\app\app.routes.ts) and add a route loading the microfrontend:
```
{
    path: 'flights',
    loadChildren: () => import('mfe1/Module').then(m => m.FlightsModule)
},
```
Please note that the imported URL consists of the names defined in the configuration files above.
As the Url mfe1/Module does not exist at compile time, ease the TypeScript compiler by adding the following line to the file projects\shell\src\decl.d.ts:
```
declare module 'mfe1/Module';
```

Part 3: Try it out

Now, let's try it out!

Start the shell and mfe1 side by side:
```
ng serve shell -o
ng serve mfe1 -o
```
Hint: You might use two terminals for this.
After a browser window with the shell opened (http://localhost:5000), click on Flights. This should load the microfrontend into the shell:
Also, ensure yourself that the microfrontend also runs in standalone mode at http://localhost:3000:

Congratulations! You've implemented your first Module Federation project with Angular!

Part 4: Switch to Dynamic Federation

Now, let's remove the need for registering the micro frontends upfront with with shell.

Switch to your shell application and open the file webpack.config.js. Here, remove the registered remotes:

remotes: {
    // Remove this line or comment it out:
    // "mfe1": "mfe1@http://localhost:3000/remoteEntry.js",
},

Open the file app.routes.ts and use the function loadRemoteModule instead of the dynamic import statement:

import { loadRemoteModule } from '@angular-architects/module-federation';

[...]
const routes: Routes = [
    [...]
    {
        path: 'flights',
        loadChildren: () =>
            loadRemoteModule({
                remoteEntry: 'http://localhost:3000/remoteEntry.js',
                remoteName: 'mfe1',
                exposedModule: './Module'
            })
            .then(m => m.FlightsModule)
    },
    [...]
]

Restart both, the shell and the micro frontend (mfe1).
The shell should still be able to load the micro frontend. However, now it's loaded dynamically.

This was quite easy, wasn't it? However, we can improve this solution a bit. Ideally, we load the remote entry upfront before Angular bootstraps. In this early phase, Module Federation tries to determine the highest compatible versions of all dependencies. Let's assume, the shell provides version 1.0.0 of a dependency (specifying ^1.0.0 in its package.json) and the micro frontend uses version 1.1.0 (specifying ^1.1.0 in its package.json). In this case, they would go with version 1.1.0. However, this is only possible if the remote's entry is loaded upfront.

Switch to the shell project and open the file main.ts. Adjust it as follows:

import { loadRemoteEntry } from '@angular-architects/module-federation';

Promise.all([
    loadRemoteEntry('http://localhost:3000/remoteEntry.js', 'mfe1')
])
.catch(err => console.error('Error loading remote entries', err))
.then(() => import('./bootstrap'))
.catch(err => console.error(err));

Open the file app.routes.ts and comment out (or remove) the property remoteEntry:

import { loadRemoteModule } from '@angular-architects/module-federation';

[...]
const routes: Routes = [
    [...]
    {
        path: 'flights',
        loadChildren: () =>
            loadRemoteModule({
                // remoteEntry: 'http://localhost:3000/remoteEntry.js',
                remoteName: 'mfe1',
                exposedModule: './Module'
            })
            .then(m => m.FlightsModule)
    },
    [...]
]

Restart both, the shell and the micro frontend (mfe1).
The shell should still be able to load the micro frontend.

Step 5: Share a Library of Your Monorepo

Add a library to your monorepo:
```
ng g lib auth-lib
```
In your tsconfig.json in the project's root, adjust the path mapping for auth-lib so that it points to the libs entry point:
```
"auth-lib": [
 "projects/auth-lib/src/public-api.ts"
]
```
As most IDEs only read global configuration files like the tsconfig.json once, restart your IDE (Alternatively, your IDE might also provide an option for reloading these settings).

Open the shell's webpack.config.js and register the created auth-lib with the sharedMappings:

const sharedMappings = new mf.SharedMappings();
sharedMappings.register(
    path.join(__dirname, '../../tsconfig.json'),
    ['auth-lib'] // <-- Add this entry!  
);

Also open the micro frontends (mfe1) webpack.config.js and do the same.

Switch to your auth-lib project and open the file auth-lib.service.ts. Adjust it as follows:

@Injectable({
    providedIn: 'root'
})
export class AuthLibService {

    private userName: string;

    public get user(): string {
        return this.userName;
    }

    constructor() { }

    public login(userName: string, password: string): void {
        // Authentication for **honest** users TM. (c) Manfred Steyer
        this.userName = userName;
    }

}

Switch to your shell project and open its app.component.ts. Use the shared AuthLibService to login a user:

import { AuthLibService } from 'auth-lib';

@Component({
    selector: 'app-root',
    templateUrl: './app.component.html'
})
export class AppComponent {
    title = 'shell';

    constructor(private service: AuthLibService) {
        this.service.login('Max', null);
    }

}

Switch to your mfe1 project and open its flights-search.component.ts. Use the shared service to retrieve the current user's name:

export class FlightsSearchComponent {

    [...]

    user = this.service.user;

    constructor(private service: AuthLibService, [...]) { }

    [...]
}

Open this component's template(flights-search.component.html) and data bind the property user:
```
<div id="container">
    <div>{{user}}</div>
    [...]
</div>
```
Restart both, the shell and the micro frontend (mfe1).
In the shell, navigate to the micro frontend. If it shows the same user name, the library is shared.

More Details on Module Federation

Have a look at this article series about Module Federation

Angular Trainings, Workshops, and Consulting

6 Steps to your Angular-based Microfrontend Shell

Manfred Steyer — Sun, 01 Dec 2019 23:08:14 +0000

In the last time, I helped numerous companies implementing Angular SPAs for microservice environments. As outlined in a former blog article, there are several approaches for this.

In this article, I show how to implement one of them in 6 steps: A shell loading micro frontends on demand. Other than in my article about micro frontends and web components, I don't use web components for the macro architecture. Instead, I just go with ordinary SPAs which are loaded and bootstrapped on demand. For the micro architecture I still use web components.

While this decision simplifies the implementation, we can still isolate different applications using shadow DOM as Angular also supports this standard associated with web components for traditional Angular components since its first day.

The case study loads a simple client-a and a simple client-b into the shell. Also, the former one shares a widget with the latter one:

The source code for this can be found in my GitHub account here.

Step 0: Make sure you need it

Make sure this approach fits to your architectural goals. Micro frontends come with a lot of consequences. You should be aware of them. My blog article here provides some guidance.

Step 1: Implement Your SPAs

Implement your micro frontends as ordinary Angular applications. In an micro service architecture it's quite common that every part gets its own repository in order to decouple them as much as possible (see Componentization via Services) On contrary, I've seen a lot of micro frontends based upon monorepos for practical reasons.

Of course, now, we could discuss when the term micro frontend is appropriate. I won't, because this discussion doesn't really help. What counts is to find a architecture that fits your goals and to be aware of its consequences.

If we go with a monorepo, we have to ensure, e. g. with linting rules, that the micro frontends are not coupled to each other. Nrwl's Nx provides a great solution for that: It allows to set up access restrictions defining which library can access which other one. Also, Nx can detect which parts of your monorepo are affected by a change in order to only recompile and retest them.

Of course, this decision has consequences, as discussed in the mentioned blog article.

To make routing across micro frontends easier, it's a good idea to prefix all the routes with the application's name. In the following case, the application name is client-a

@NgModule({
  imports: [
    ReactiveFormsModule,
    BrowserModule,
    RouterModule.forRoot([
      { path: 'client-a/page1', component: Page1Component },
      { path: 'client-a/page2', component: Page2Component },
      { path: '**', component: EmptyComponent}
    ], { useHash: true })
  ],
  [...] 
})
export class AppModule {
  [...]
}

Step 2: Expose Shared Widgets

Expose widgets you want to share as Web Components/ Custom Elements. Please note that from the perspective of micro services, you should avoid sharing code between micro frontends as much as possible. The reason is that this causes coupling which is exactly what you want to avoid with this architectural style.

For exposing an Angular Component as a Custom Element, you can use Angular Elements. My blog article about Angular Elements and lazy and external Angular Elements provides the necessary information.

Step 3: Compile your SPAs

Webpack, and hence the Angular CLI, use a global array for registering bundles. It enables different (lazy) chunks of your application to find each other. However, if we are going to load several SPAs into one page, they will compete over this array, mess it up, and stop working.

For this dilemma, we have two solutions:

1) Just put everything into one bundle, so that this global array is not needed
2) Rename the global array

Here, I use solution 1) because a micro frontend is by definition small and just having one bundle makes loading it on demand easier. Also, as we will see later, we can share libraries like RxJS or Angular itself between them.

To accompish this, you can leverage ngx-build-plus which extenses the CLI by a --single-bundle switch:

ng add ngx-build-plus
ng build --prod --single-bundle

This switch makes the CLI to put your whole code into one main bundle. However, scripts, styles, and polyfills are still put into a bundle of their own. The reason behind this is, that it's very likely that the shell already loads these aspects and you don't want to load them again.

If you favor solution 2) you could use ngx-build-plus to influence the CLI's webpack config. Using the setting output.jsonpFunction you can define the name for the array mentioned.

We also offer an advanced Angular workshop containing this topic and more strategies for your Angular-based enterprise architectures. Please find all the information about it here

Step 4: Create a shell and load the bundles on demand

Loading the bundles on demand is straight forward. All you need is some vanilla JavaScript code dynamically creating a script tag and the tag for application's root element:

// add script tag
const script = document.createElement('script');
script.src = '[...]/client-a/main.js';
document.body.appendChild(script);

// add app
const frontend = document.createElement('client-a');
const content = document.getElementById('content');
content.appendChild(frontend);

Of course, you can also wrap this into a directive.

Also, you need some code to show and hide the loaded micro frontend on demand:

frontend['visible'] = false;

Step 5: Communication Between Microfrontends

In general, we should keep the communication between microfrontends at a minimum, as it couples them to each other.

To implement communication, we have several options. Here, I go with the least obtrusive one: using the query string. This has several advantages:

1) It does not matter in which order the micro frontends are loaded. When they are loaded, they can grab the current parameters from the url
2) It allows deep linking
3) It's like the web is supposed to work
4) It's easy to implement

Setting an url parameter with the Angular router is just a matter of calling one method:

this.router.navigate(['.'], { queryParamsHandling: 'merge', queryParams: { id: 17 }});

The option merge makes sure that the existing url parameters are not lost. If there is already a parameter id, the router will overwrite it.

Also, listening for changes within url parameters is also something the Angular router can help with:

route.queryParams.subscribe(params => {
    console.debug('params', params);
});

There are some alternatives for this:

If you wrap your micro frontends into web components, you could use their properties and events to communicate with the shell.
The shell could put a "message bus" into the global namespace:
```
(window as any).messageBus = new BehaviorSubject<MicroFrontendEvent>(null);
```
Both, the shell and the Microfrontends could now subscribe to this message bus and listen for specific events they are interested into. Also, both can emit events.

Using custom Events provided by the browser:

// Sender
const customer = { id: 17, ... };
window.raiseEvent(new CustomEvent('CustomerSelected', {details: customer}))

// Receiver
window.addEventListener('CustomerSelected', (e) => { ... })

Step 6: Sharing Libraries Between Micro Frontends

Now, as we have several self-contained micro frontends, each of them has its own dependencies, e. g. Angular itself or RxJS. From an micro service perspective, this is perfect because it allows each team behind your micro frontends to choose any library or framework in any version. They can even decide by their own if and when to update to newer versions.

However, from the perspective of performance and loading time, this is a bad situation because it leads to code duplication within the bundles. For instance, we could end up with having a specific angular version in several of your bundles:

Fortunately, there is a solution for this: Webpack externals. I've already written about it in the context of external (standalone) Angular Elements and for micro apps I will repeat the most important aspects here:

Externals allow us to share common libraries. For this, they are just loaded so that they can be referenced via the global namespace. In the case of most libraries we can use UMD bundles which do exactly this besides other things. Then, we have to tell webpack to not bundle them together with every micro frontend but to reference it within the global namespace instead:

To use webpack externals together with the Angular CLI you can leverage ngx-build-plus which even comes with a schematic introducing the needed changes into your application.

To get it, you can ng add it:

ng add ngx-build-plus

Then, call the following schematic:

ng g ngx-build-plus:externals

This also introduces an npm script build:<project-name>:externals. For the default project there is a script build:externals too.

If you look into the angular.json after running this script, you see that Angular is loaded using UMD bundles:

"scripts": [
  "node_modules/rxjs/bundles/rxjs.umd.js",
  "node_modules/@angular/core/bundles/core.umd.js",
  "node_modules/@angular/common/bundles/common.umd.js",
  "node_modules/@angular/common/bundles/common-http.umd.js",
  "node_modules/@angular/compiler/bundles/compiler.umd.js",
  "node_modules/@angular/elements/bundles/elements.umd.js",
  "node_modules/@angular/platform-browser/bundles/platform-browser.umd.js",
  "node_modules/@angular/platform-browser-dynamic/bundles/platform-browser-dynamic.umd.js"
]

These UMD bundles put Angular into window.ng where it can be reused by several separately compiled micro frontends.

Also, if you have a look into the generated webpack.externals.js, you find a section mapping package names to global variables:

const webpack = require('webpack');

module.exports = {
    "externals": {
        "rxjs": "rxjs",
        "@angular/core": "ng.core",
        "@angular/common": "ng.common",
        "@angular/common/http": "ng.common.http",
        "@angular/platform-browser": "ng.platformBrowser",
        "@angular/platform-browser-dynamic": "ng.platformBrowserDynamic",
        "@angular/compiler": "ng.compiler",
        "@angular/elements": "ng.elements",
        "@angular/router": "ng.router",
        "@angular/forms": "ng.forms"
    }
}

This, for instance, makes the produced bundle to reference the global variable ng.core when it needs @angular/core. Hence, @angular/core does not need to be part of the bundle anymore.

Please note that this is not the default operation mode for Angular and hence it comes with some risks.

Conclusion

With the right wrinkles, implementing a shell for micro elements is not that difficult. However, as outlined here, this is only one way for implementing micro apps and -- as all -- it comes with its very own advantages and disadvantages. Hence, before implementing it, make sure it fits your architectural goals.

More Free e-Book

If you liked this article, you also may like my free e-Book on Angular Architecture, which can be found here.

Also, we offer an advanced Angular workshop containing this topic and more strategies for your Angular-based enterprise architectures.

Sustainable Angular Architectures with Tactical DDD and MonoRepos?

Manfred Steyer — Tue, 17 Sep 2019 18:16:30 +0000

Business and industrial applications are usually long-lived. These applications include customer-facing applications layered with complex backend services and systems. Many of these applications are now implemented with web frontends using JavaScript.

So how can we build and maintain such software systems?

Domain Driven Design (DDD) provides the answer! Best of all, it is especially suitable for complex Angular solutions.

In this article we will learn:

How Tactical Design (DDD) helps to organize our source code as smaller, manageable, coherent parts.
How monorepos help implementing them
How Facades help with isolating your domain logic
How client-side DDD paves the way to micro frontends

All these topics are also part of our advanced Angular Architecture workshop. Have a look at it if you're implementing business or industrial software with Angular!

As always, the examples used can be found in my GitHub account.

Big thanks to Thomas Burleson who deeply reviewed this article and contributed to it.

Domain Decomposition

Let's consider a consumer travel web application we are building. We have several domains that we can identify:

To manage complexity of these domains, we should leverage Domain-Driven Design and best practices from the Angular community.

Domain Driven Design comes with the two types of design

Strategic Domain Design
Tactical Design

While the former one is about identifying domains and the communication between them, tactical design deals with structuring these domains.

I've already written about the use of Strategic Design in Angular applications. Have a look at this article for foundational understandings. Hence, here, I'll focus on Tactical Domain Design.

Applying Tactical Design

Now let's talk about how to structure our application with tactical design.

Domain Organization using Layers

For domains we use column subdivisions ("swimlanes"). Moreover, those domains can be organized with layers of libraries which leads to row subdivisions:

Note how each layer could consists one or more libraries

While using layers is quite a traditional way of organizing an domain, there are also alternatives like hexagonal architectures or clean architecture.

What about shared functionality?

For those aspects that are to be shared and used across domains, an additional shared swimlane is used. Shared libraries can be quite useful. Consider - for example - shared libraries for authentication or logging.

Note: the shared swimlane corresponds to the Shared Kernel proposed by DDD and also includes technical libraries to share.

How to prevent high coupling?

Access constrains define which libraries can use/depend upon other libraries. Typically, each layer is only allowed to communicate with underlying layers. Cross-domain access is allowed only with the shared area. The benefit of using these restrictions can result in loose coupling and thus increased maintainability.

To prevent too much logic to be put into the shared area, the approach presented here also uses APIs that publish building blocks for other domains. This corresponds to the idea of Open Services in DDD.

Regarding the shared part, one can see the following two characteristics:

As the grayed-out blocks indicate, most util libraries are in the shared area, especially as aspects such as authentication or logging are used across systems.
The same applies to general UI libraries that ensure a system-wide look and feel.

What about feature-specific functionality?

Notice that domain-specific feature libraries, however, are not in the shared area. Feature-related code should be placed within its own domain.

While developers may elect to share feature code (between domains), this practice can lead to shared responsibilities, more coordination effort, and breaking changes. Hence, it should only be shared sparingly.

Code Organization

Based on Nrwl.io's Enterprise MonoRepository Patterns, I distinguish between five categories of layers or libraries:

Category	Description	Exemplary content
feature	Contains components for an use case.	search-flight component
ui	Contains so-called "dumb components" that are use-case agnostic and thus reusable.	datetime-component, address-component, adress-pipe
api	Exports building blocks from the current subdomain for others.	Flight API
domain	Contains the domain models (classes, interfaces, types) that are used by the domain (swimlane)
util	Include general utility functions	formatDate

This complete architectural matrix is initially overwhelming. But after a brief review, almost all developers I've worked with agreed that the code organization facilitates code reuse and future features.

Isolate the Domain

To isolate the domain logic, we hide it behind facades which represent it in an use-case specific way:

This facade can also deal with state mangement. Two excellent articles are available for deep dives into those areas:

While Facades are currently quite popular in the Angular environment, this idea also correlates wonderfully with DDD (where they are called application services).

It is important to architecturally separate infrastructure requirements from the actual domain logic.

In an SPA, infrastructure concerns are -- at least most of the time -- asynchronous communication with the server and data exchanges. Maintaining this separation results in three additional layers:

the application services/ facades,
the actual domain layer, and
the infrastructure layer.

Of course, these layers can now also be packaged in their own libraries. For the sake of simplicity, it is also possible to store them in a single library, which is subdivided accordingly. This decision makes sense if these layers are usually used together and only need to be exchanged for unit tests.

Implementations in a Monorepos

Once the components of our architecture have been determined, the question arises of how they can be implemented in the world of Angular. A very common approach also used by Google itself is using a monorepo. It is a code repository that contains all the libraries of a software system.

While a project created with the Angular CLI can nowadays be used as a monorepo, the popular tool Nx offers some additional possibilities which are especially valuable for large enterprise solutions. These include the previously discussed ways to introduce access restrictions between libraries. This prevents each library from accessing each other, resulting in a highly coupled overall system.

To create a library in a monorepo, one instruction is enough:

ng generate library domain --directory boarding

As you just use ng generate library instead of ng generate module there is not more effort for you. However, you get a cleaner structure, improved maintainability, and less coupling.

The switch directory provided by Nx specifies an optional subdirectory where the libraries are to be put. This way, they can be grouped by domain:

The names of the libraries also reflect the layers.
If a layer has several libraries, it makes sense to use these names as a prefix. This results in names such as feature-search or feature-edit.

In order to isolate the actual domain model, the example shown here divides the domain library into the three further layers mentioned:

Builds within a Monorepo

By looking at the git commit log, Nx can also identify which libraries are affected by the latest code changes.

This change information is used to recompile only the affected libraries or just run their affected tests. Obviously, this saves a lot of time on large systems that are stored in a repository as a whole.

Entities and your Tactical Design

Tactical Design provides many ideas for structuring the domain layer. At the center of this layer, there are entities the reflecting real world domain and constructs.

The following listing shows an enum and two entities that conform to the usual practices of object-oriented languages such as Java or C#.

public enum BoardingStatus {
  WAIT_FOR_BOARDING,
  BOARDED,
  NO_SHOW
}

public class BoardingList {

  private int id;
  private int flightId;
  private List<BoardingListEntry> entries;
  private boolean completed;

  // getters and setters

  public void setStatus (int passengerId, BoardingStatus status) {
    // Complex logic to update status
  }

}

public class BoardingListEntry {

  private int id;
  private boarding status status;

  // getters and setters
}

As usual in OO-land, these entities use information hiding to ensure that their state remains consistent. You implement this with private fields and public methods that operate on them.

These entities not only encapsulate data, but also business rules. At least the method setStatus indicates this circumstance. Only for cases where business rules can not be meaningfully accommodated in an entity, DDD defines so-called domain services.

Entities that only represent data structures are frowned upon in DDD. The community calls them devaluing bloodless (anemic).

Tactical DDD with Functional Programming

From an object-oriented point of view, the previous approach makes sense. However - with languages such as JavaScript and TypeScript - object-orientation is less important.

Typescript is a multi-paradigm language in which Functional Programming plays a big role. Books dealing with Functional DDD can be found here:

With functional programming, the previously considered entity model would therefore be separated into a data part and a logic part. Domain-Driven Design Distilled which is one of the standard works for DDD and primarily relies on OOP, also admits that this rule change is necessary in the world of FP:

export type BoardingStatus = 'WAIT_FOR_BOARDING' | 'BOARDED' | 'NO_SHOW' ;

export interface BoardingList {
    readonly id: number;
    readonly flightId: number;
    readonly entries: BoardingListEntry [];
    readonly completed: boolean;
}

export interface BoardingListEntry {
    readonly passengerId: number;
    readonly status: BoardingStatus;
}

export function updateBoardingStatus (
                   boardingList: BoardingList,
                   passengerId: number,
                   status: BoardingStatus): Promise <BoardingList> {

        // Complex logic to update status

}

Here the entities also use public properties. This practice is quite common in FP; the excessive use of getters and setters, which only delegate to private properties, is often ridiculed!

Much more interesting, however, is the question of how the functional world avoids inconsistent states. The answer is amazingly simple: data structures are preferably immutable. The keyword readonly in the example shown emphasizes this.

A part of the program that wants to change such objects has to clone it, and if other parts of the program have first validated an object for their own purposes, they can assume that it remains valid.

A wonderful side-affect of using immutable data structures is that change detection performance is optimized. No longer are deep-comparisons required. Instead, a changed object is actually a new instance and thus the object references will no longer be the same.

Tactial DDD with Aggregates

To keep track of the components of a domain model, Tactical DDD combines entities into aggregates. In the last example, BoardingList and BoardingListEntry form such an aggregate.

The state of all components of an aggregate must be consistent as a whole. For example, in the example outlined above, one could specify that completed in BoardingList may only be set to true if no BoardingListEntry has the status WAIT_FOR_BOARDING .

In addition, different aggregates may not reference each other through object references. Instead, they can use IDs. This should prevent unnecessary coupling between aggregates. Large domains can thus be broken down into smaller groups of aggregates.

Domain-Driven Design Distilled suggests making aggregates as small as possible. First of all, consider each entity as an aggregate and then merge aggregates that need to be changed together without delay.

Facades

Facades (aka Applications Services) are used to represent the domain logic in an use case specific way. The provide several advantages:

Encapsulating complexity
Taking care about state management
Simplified APIs

Independent of DDD, this idea has been very popular in the world of Angular for some time.

For our example, we could create the following Facade:

@Injectable ({providedIn: 'root'})
export class FlightFacade {

    private notifier = new BehaviorSubject<Flight[]>([]);    
    public  flights$ = this.notifier.asObservable();

    constructor(private flightService: FlightService) { }

    search(from: string, to: string, urgent: boolean): void {
        this.flightService
            .find(from, to, urgent)
            .subscribe (
              (flights) => this.notifier.next(flights),
              (err) => console.error ('err', err);
            );
    }
}

Note the use of RxJS and observables in the facade. This means that the facade can auto-deliver updated flight information when conditions change. Another advantage of Facades is the ability to transparently introduce Redux and @ngrx/store later when needed. This can be done without affecting any of the external application components.

For the consumer of the Facade it is not relevant whether it manages the state by it self or by delegating to a state management library.

Developers are encouraged to read/watch Thomas Burleson's work about this topic:

Blog article Push-based Architectures using RxJS + Facades, or
YouTube video Push-based Architectures with RxJS

Stateless Facades

While it is a good practice to make server-side services stateless, often this goal is not performant for services in web/client-tier.

A web SPA has state and that's what makes it user-friendly!

To avoid UX issues, Angular applications do not want to reload all the information from the server over and over again. Hence, the Facade outlined holds the loaded flights (within the observable discussed before).

Domain Events

Besides performance improvements, using Observables provide a further advantage. Observables allow further decoupling, since the sender and the receiver do not have to know each other directly.

This also perfectly fits to DDD, where the use of domain events are now part of the architecture. If something interesting happens in one part of the application, it sends a domain event and other application parts can react to it.

In the shown example, a domain event could indicate that a passenger is now BOARDED. If this is interesting for other parts of the system they can execute specific logics.

For Angular developers familiar with Redux or Ngrx: Domain events can be represented as dispatched actions!

Domain-Driven Design and Micro Frontends?

The ideas of Domain-Driven Design are known to pave the way for micro-service architectures. Hence, client-side DDD can be used as a basis for micro frontends.

Whether a deployment monolith, micro frontends, or anything in between is created, depends on the use of the monorepo. If the monorepo gets an own application for each domain, a big step towards micro frontends is taken:

The access restrictions discussed above ensure a loose coupling and even allow a later split to multiple repositories. Then you can talk about micro frontends in the classic sense of a micro-service architecture. However, in this case the team has to take care of versioning and distributing shared libraries which is common with micro-services.

More thoughts about this topic can be found in my blog article It’s about cutting your domain, not (first and foremost) about micro frontends!.

Conclusion

Modern single page applications (SPAs) are often more than just recipients of data transfer objects (DTOs). They often contain significant domain logic which adds complexity. Ideas from DDD help developers to manage and scale with the resulting complexity.

Due to the object-functional nature of TypeScript and prevailing customs, a few rule changes are necessary. For instance, we usually use immutables and separate data structures from the logics operating on them.

The implementation outlined here bases upon the following ideas:

The use of monorepos with multiple libraries grouped by domains helps building the basic structure.
Access restrictions between libraries prevent coupling between domains.
Facades prepare the domain model for individual use cases and take care of maintaining the state.
If needed, Redux can be used behind the facade without the rest of the application noticing.

Besides, a team also creates the conditions for micro frontends by using client-side DDD.

If you want to see all these topics in action, checkout our Angular Architecture workshop.

Architecture with Angular Ivy - Part 1: A possible future without NgModules?

Manfred Steyer — Fri, 16 Aug 2019 10:23:09 +0000

In this post I want to show:

🔭 How a possible future without (with optional) NgModules could look like
🐹 How we can prepare for this future already today

The source code used for the examples can be found here.

DISCLAIMER: The examples here are an experiment showing a possible direction Angular might be heading to. Hence, it's not production ready and it does not reflect the Angular teams's official vision. Nethertheless, it shows what's possible with Ivy and it leads to a conclusion about how we can prepare already today for a future without NgModules.

A little history

When Angular -- back than called Angular 2 -- was envisioned, the team didn't plan to implement an own module system. While this was necessary in the times of AngularJS 1.x, the idea for Angular (2+) was to just leverage EcmaScript modules introduced in 2015.

And so, Angular Modules have been among several AngularJS 1.x aspects that should have been skipped in the upcoming version of Google's SPA flagship. The following graphic, taken out of Igor Minar's and Tobias Bosch's presentation at ngEurope 2014 in Paris emphasizes this:

However, during the development of Angular it became obvious, that Angular Modules can come in handy for several reasons. One reason was lazy loading; another reason was the need to provide context for the Angular compiler. This is because the compiler needs to know which components, directives, and pipes are available within a template.

On the contrary, Ivy has a different strategy to define the compilation context -- at least under the covers. The next section gives some details about this.

Compilation Context for Ivy

One of the benefits of Ivy is that it produces simpler code. During compilation, it just adds a static ɵcmp property to components. This property contains a definition object describing the component for the compiler.

Similarly, the compiler adds also such a definition to directives and pipes. They are called ɵdir and ɵpipe.

You can even access it at runtime:

const def: ComponentDef<AppComponent> = AppComponent['ɵcmp'];
console.debug('def', def);

The respective console output would look like this:

As you see here, these properties contain everything Angular needs to know when executing the component. Perhaps you've noticed the directiveDefs and pipeDefs properties. They contain the compilation context for the template we've talked about above.

The first one points to an array of definitions for directives and components. Saying this, a component definition is just a special kind of a directive definition. Alternatively, directiveDefs can point to a factory function returning such an array.

The pipeDefs property does the same for pipe definitions.

This way, Angular knows which (sub-)components, directives, and pipes are available in a component's template.

Now, you might wonder how those properties are filled with the right values. In order to prevent breaking changes, the Ivy compiler just looks up the necessary entries in the component's module as well as in all other modules imported there. After this, it adds the found components, directives, and pipes to directiveDefs or pipeDefs.

However, if we wanted to use Ivy without modules, we could directly populate these two property. The next section provides some information about this idea.

Compilation Context without NgModules

Technically, it's possible to directly add the compilation context to directiveDefs and pipeDefs. Unfortunately, these properties are not part of Angular's public API currently.

This is for a reason: First of all, the Angular team concentrates on making sure Ivy is completely backwards compatible. Only than, they will introduce new features based upon Ivy step by step.

When that happens, the Component decorator might get some additional properties for this reason.

As the next section shows, we can already have a short look into this possible future today.

Calming the Angular-Compiler

While this all will work at runtime, it might cause some troubles during compilation due some of the Angular compiler's checks. For instance, it checks whether the used components and pipes are available by looking into NgModules. Of course, these checks will not work in our case as the goal was to work without them.

To calm the compiler, we should turn of fullTemplateTypeCheck in tsconfig.json:

"angularCompilerOptions": {
    "fullTemplateTypeCheck": true,
    "strictInjectionParameters": true,
}

Also, we should import the NO_ERRORS_SCHEMA into out AppModule:

@NgModule({
    imports: [
        BrowserModule
    ],
    declarations: [
        AppComponent
    ],
    schemas: [
        NO_ERRORS_SCHEMA
    ],
    providers: [],
    bootstrap: [
        AppComponent
    ]
})
export class AppModule { }

In this case study, the AppModule is the only module used. Technically, we could even get rid of this module.
Instead, we could just bootstrap the AppComponent using Ivy's ɵrenderComponent function which is also part of the private API. However, this would make things more complicated as renderComponent is currently not supporting automatic change detection out of the box.

Directly Providing the Compilation Context

As directly providing the compilation context is not possible with public APIs today, this section directly leverages the available private ones. Of course, they can change and hence the techniques outlined here are not feasible for production code.

Nethertheless, this experiment shows how modern Angular code might look like in the future. It also leads to a conclusion that tells us, how we can prepare for this future.

To demonstrate how to directly provide the compilation context, I'm using a simple example here. It just contains a tabbed-pane which displays one of several tabs at a time:

The example's AppComponent uses them:

<tabbed-pane>
  <tab title="Tab 1">
    Lorem ipsum ...
  </tab>
  <tab title="Tab 2">
    Lorem ipsum ...
  </tab>
  <tab title="Tab 3">
    Lorem ipsum ...
  </tab>
</tabbed-pane>

For showing and hiding the tabs, the TabbedPaneComponent uses Angular's *ngIf directive and for displaying the link it uses *ngFor.

If we want to provide the compilation context directly to these components, we need to get hold of the respective definition objects. For this, I've created a helper function:

import { Type } from "@angular/core";
import { ɵComponentDef as ComponentDef } from '@angular/core';

[...]

export function getComponentDef<T>(t: Type<T>): ComponentDef<T> {
  if (t['ɵcmp']) {
    return t['ɵcmp'] as ComponentDef<T>;
  }

  throw new Error('No Angular definition found for ' + t.name);
}

As you might have noticed, the ComponentDef class is prefixed with the ɵ sign. This denotes that the class is still part of Angular's private API.

I've written similar helper functions for getting DirectiveDefs and PipeDefs:

export function getDirectiveDef<T>(t: Type<T>): DirectiveDef<T> {

    if (t['ɵdir']) {
      return t['ɵdir'] as DirectiveDef<T>;
    }

    // A Component(Def) is also a Directive(Def)
    if (t['ɵcmp']) {
      return t['ɵcmp'] as ComponentDef<T>;
    }

    throw new Error('No Angular definition found for ' + t.name);
}

export function getPipeDef<T>(t: Type<T>): PipeDef<T> {

  if (t['ɵpipe']) {
    return t['ɵpipe'] as PipeDef<T>;
  }

  throw new Error('No Angular definition found for ' + t.name);
}

Similarly, I've written helper functions for getting all the definition objects from an array of directives and an array of pipes:

export function getDirectiveDefs(types: Type<any>[]): DirectiveDef<any>[] {
  return types.map(t => getDirectiveDef(t));
}

export function getPipeDefs(types: Type<any>[]): PipeDef<any>[] {
  return types.map(t => getPipeDef(t));
}

Please note that the former one is also respecting component definitions, as a component definition is a special kind of a directive definition. Technically, ComponentDef even inherits DirectiveDef.

Using these helpers, we can easily add the compilation context to our components:

@Component({ [...] })
export class AppComponent {
  title = 'demo';
}

// Adding compilation context
const def = getComponentDef(AppComponent);

def.directiveDefs = [
  getDirectiveDef(TabComponent), 
  getDirectiveDef(TabbedPaneComponent)
];

For the sake of simplicity, I'm overwriting the directiveDefs property here. This means that values the compiler placed there after traversing possibly existing modules are overwritten too.

Of course, adding the same definition objects time and again to different consuming objects is annoying. However, we could group components belonging together using a central array:

export const TABBED_PANE_COMPONENTS = [
    TabbedPaneComponent,
    TabComponent
];

To import this array, we can use our getDirectiveDef helper function:

def.directiveDefs = [
  ...getDirectiveDefs(TABBED_PANE_COMPONENTS)
];

Similarly to this, I've written a file exporting all the directives I need from @angular/common:

export const COMMON_DIRECTIVES = [
    NgIf,
    NgForOf,
    // etc.
];

This one is used for the TabbedPaneComponent:

@Component({ [...] })
export class TabbedPaneComponent implements AfterContentInit {
    [...]
}

const def = getDef(TabbedPaneComponent);

def.directiveDefs = [
     ...getDefs(COMMON_DIRECTIVES)
];

Of course, as we have just two components, this is not a big win here but in bigger scenarios with lots of components using such an array comes quite in handy.

As patching a component after defining it is somewhat brutal, the next section shows a better way.

Providing the compilation context with a decorator

To add the compilation context to components in a way we are more used to as Angular developers, I've written a simple decorator:

export interface ComponentDepsConfig {
  directives?: Type<any>[];
  pipes?: Type<any>[];
}

export function ComponentDeps(config: ComponentDepsConfig) {
  return (component) => {

    const def = getComponentDef(component);

    def.directiveDefs = [
      ...getDirectiveDefs(config.directives || [])
    ];

    def.pipeDefs = [
      ...getPipeDefs(config.pipes || [])
    ];

  }
}

To be more precise, this is a factory for a decorator. It takes a config object containing the compilation context and returns a decorator for a component. This decorator adds the context to the component's definition.

Now, let's apply this decorator to our components:

@Component({ [...] })
@ComponentDeps({
  directives: [ 
    ...TABBED_PANE_COMPONENTS
  ]
})
export class AppComponent {
  title = 'demo';
}

This looks a lot like the envisioned possible future where the component decorator directly takes the compilation context. Also, Angular's Minko Gechev created a prototype of Angular which uses this idea. It's Component decorator come with a deps property that serves the same purpose. One more time, this is all is about showing what's possible and it doesn't reflect the Angular teams's official vision.

However, now the question is what can we learn from this case study. The next section provides an answer.

Preparing for a possible future without (with optional) NgModules

In this article, we've seen that we need a compilation context. If we don't have something like NgModules we could assign it directly to our components. This is already possible by using internal APIs and the respective properties might eventually be exposed a part of Angular's public API.

We've also seen that even in this case, it's in handy to group components, directives, or pipes belonging together. For this reason we've used a simple array:

export const TABBED_PANE_COMPONENTS = [
    TabbedPaneComponent,
    TabComponent
];

Interestingly, this array look like the export part of an NgModule. However, this is pure EcmaScript which makes its simpler and easier to understand.

Also, it's obvious that even in a future without NgModules we need a way to group parts of our code. We will also need some way of information hiding which means we have to define public and private parts of our APIs. Fortunately, this can also be accomplished with pure EcmaScript by using barrels.

For instance, in my case study, the tabbed-pane folder has the following index.ts:

export * from './tab.component';
export * from './tabbed-pane.component';

// array with components
export * from './components';

The app.component.ts imports this barrel:

import { TABBED_PANE_COMPONENTS } from './tabbed-pane';

We can even go one step further and use a monorepo with different libraries. Each library gets a barrel which defines the public API. Thanks to the Angular CLI creating libraries to group your code is very easy. It's just a matter of one command (ng generate lib my-lib) and it also makes your code more reusable.

Furthermore, when using Nrwl's Nx for creating an Angular CLI based monorepo, you can also define access restrictions between your libraries. Also, it contains linting rules preventing that someone uses private parts of your APIs by bypassing their barrels.

This all leads to my advice for preparing for this possible future without (with optional) Angular modules.

Conclusion

As you have seen here, we can already prepare today for a possible future without (with optional) NgModules. It's as easy as that:

Cut your application into libraries and use barrels to define their public APIs.
When NgModules become optional, replace them with an their export arrays.

Finally, let me tell you the best: Regardless, if this possible future will happen or not, this advice makes a lot of sense anyway, because cutting your application into tiny libraries with a public and a private part leads to a more robust architecture.