Forem: Nacho Vazquez

Announcing Lumberjack v16: Life improvements, deprecations and an ambicius roadmap

Nacho Vazquez — Sat, 20 Jan 2024 13:32:43 +0000

We are back, bringing a new version of Lumberjack with deprecations, improvements, and a secret project.

TL;DR - Lumberjack version 16 introduces the following updates: new level-based logging methods for the Lumberjack service, alignment with Angular 16.2, deprecation of all Lumberjack NgModules, and the introduction of a new spin-off project.

New level-based logging methods

In our constant intent to improve the developer experience, we have introduced new level-based logging methods for the Lumberjack service.

Previously, a single log method accepted a LumberjackLog object. This object contained the log message and the log level. We have now introduced a new method for each log level:

// (...)
import { LumberjackService, LumberjackTimeService } from '@ngworker/lumberjack';

// (...)
export class MyComponent implements OnInit {
  readonly #lumberjack = inject(LumberjackService);
  readonly #time = inject(LumberjackTimeService);

  // (...)
  ngOnInit(): void {
    this.#lumberjack.log({
      level: LumberjackLevel.Info,
      message: 'Hello, World!',
      scope: 'MyComponent',
      createdAt: this.#time.getUnixEpochTicks(),
    });
  }
}

New:

// (...)
import { LumberjackService, LumberjackTimeService } from '@ngworker/lumberjack';

// (...)
export class MyComponent implements OnInit {
  readonly #lumberjack = inject(LumberjackService);
  readonly #time = inject(LumberjackTimeService);

  // (...)
  ngOnInit(): void {
    this.#lumberjack.logInfo('Hello, World!');
  }
}

This new API is courtesy of our new contributor, Pierre Bouillon. Thank you, @pbouillon !

NgModule deprecation

At Lumberjack, we embrace the new standalone APIs as the best way to configure our libraries and applications. That's why we have decided to deprecate all Lumberjack NgModules.

NgModules will be available until Lumberjack v18. After that, we will remove them from the library.

As an additional benefit, after deleting the NgModules in version 18, we will receive a nice reduction in our bundle size.

We remove all usage of NgModule in our internal codebase and are happy with the result. We hope you will be too.

Ambitious Secret Project

Since version 15, we have been playing with an idea: what if we could create the best framework agnostic logging library? For that, we created a PR (now closed) where we experimented with extracting the agnostic API of Lumberjack. There are also a few discussions that you can read here and here.

However, we noticed that we were prisoners of our old API and wanted to try something new. That's why we decided to create a new spin-off project called LumberjackJS.

We will offer more information when we are ready, but we are excited about the future of this project.

The idea is to merge the two projects eventually and have a single library that can be used in any framework. But there is much work and experimentation to be done before that.

Community

We are proud and thrilled to have Pierre Bouillon contributing to our project.

DEV

Starting from this blog post, we will cross-post all our articles and release notes in our newly created DEV organization

Please give it a follow.

Wrapping Up

Our goal for 2024 is to keep updating Lumberjack at the same rate as Angular. That's why we will release very shortly Lumberjack v17 with Angular 17 support.

The remaining of our efforts will be on improving the Lumberjack Developer experience and documentation. But the main chunk of our time will be spent on LumberjackJS.

Architects Delight: Enforcing Layers and Project Boundaries with Nx

Nacho Vazquez — Sun, 11 Jun 2023 12:20:53 +0000

Introduction

When I embarked on my journey as a software developer, I delved into the depths of software architecture. Renowned books such as "Clean Architecture" and "Domain-Driven Design (DDD)" provided valuable insights into concepts like project boundaries and software layers (both vertical and horizontal). Yet, what was sorely missing was a quick and efficient tool to enforce these principles.

Then, I discovered Nx, specifically its @nx/enforce-module-boundaries ESLint plugin, which has revolutionized how I enforce these boundaries.

The Hidden Side of the Iceberg

Interestingly, although the @nx/enforce-module-boundaries ELLint plugin is embedded in the generated code of every integrated Nx-Monorepo, it seems to fly under the radar when the conversation turns to Nx's merits, which are indeed numerous. Even Nx's video, "The Nx Iceberg," doesn't mention it, despite its focus on the tool's lesser-known features.

Several authors, including Manfred Steyer, Lars Gyrup Brink Nielsen, and myself, have delved into this subject. Still, many developers using Nx aren't utilizing this feature as much as possible. That sparked me to write this article highlighting Nx's power in enforcing project boundaries.

What are Project Boundaries and Layers?

Before we delve into enforcing project boundaries, it's essential to understand what they are. These rules or principles dictate how different parts of our software interact.

For instance, software architects often use philosophies such as onion architecture and clean architecture to define horizontal layers. These layers are then grouped into vertical slices or boundaries using principles like the strategic design from Domain-Driven Design.

Without automated tools, though, maintaining these boundaries becomes tricky. Developers might inadvertently cross these boundaries, leading to issues with maintainability and scalability.

Creating Projects and Boundaries with Nx

Firstly, we must have projects and boundaries before we start enforcing boundaries restrictions. Nx simplifies this process with its generators that swiftly create applications and libraries. Here is a simple command to generate a library:

nx generate @nx/js:library feature-booking

But a main ingredient is missing; Nx project tags are crucial here. They act as written definitions of our boundaries. For instance:

// project.json
{
...
  "tags": ["bounded-context:booking", "type:feature"],
...
}

In the current example, we define a vertical slice or vertical layer based on the bounded context containing the library: The booking bounded context. Not only that, but we also define a horizontal layer based on the type of the library: The feature type.

Additionally, we can use grouping folders with Nx to further streamline the structure. I believe there should be a direct connection between tags and grouping folders. I've discussed these patterns extensively in my article "Semantic Grouping Folders with Nx."

Enforcing Project Boundaries with Nx

With our projects and boundaries in place, we can utilize the power of the Nx @nx/enforce-module-boundaries ESLint plugin to set restrictions between layers.

For example, if we want to restrict that, a library belonging to the booking bounded context can only import libraries from the same bounded context. Or in other words, if we want to enforce the vertical boundary defined by the bounded-context tags, we can do the following:

        "@nx/enforce-module-boundaries": [
          "error",
          {
            "enforceBuildableLibDependency": true,
            ...
            "depConstraints": [
              ...
              {
                "sourceTag": "bounded-context:booking",
                "onlyDependOnLibsWithTags": ["bounded-context:booking"]
              },
              ...
            ]
          }
        ]

The same can be done for our horizontal layers. In the following example, we will enforce the following:

libraries with type feature can only import libraries with type feature, domain, ui
libraries with type ui can only depend on libraries with type ui and domain
libraries with type domain can only depend on libraries with type domain.

        "@nx/enforce-module-boundaries": [
          "error",
          {
            "enforceBuildableLibDependency": true,
            ...
            "depConstraints": [
              ...
              {
                "sourceTag": "type:feature",
                "onlyDependOnLibsWithTags": ["type:feature", "type:domain", "type:ui"]
              },
              {
                "sourceTag": "type:ui",
                "onlyDependOnLibsWithTags": ["type:domain", "type:ui"]
              },
              {
                "sourceTag": "type:domain",
                "onlyDependOnLibsWithTags": ["type:domain"]
              },
              ...
            ]
          }
        ]

With these restrictions in place, if you try to import a library that breaks one of these enforced boundaries, you will get an ESLint error. Here is a hypothetical situation:

// File: libs/boundary/domain/types.ts
import { Button } from '@my-org/ui';

error  A project tagged with "type:domain" can only depend on libs tagged with "type:domain"  @nx/enforce-module-boundaries

This error message signifies that we've attempted to cross a boundary, thus helping us maintain the integrity of our architecture.

And this is not everything; we can even restrict external imports as described in the docs. I've found this. tool extremely useful when using technologies that look similar like React, Qwik and SolidJS; or even backend and frontend like Angular and NestJS.

Conclusion

Enforcing project boundaries and layers easily was a dream I thought was too much to ask.

Nx's @nx/enforce-module-boundaries ESLint plugin offers a powerful solution. The more we understand its potential and learn to utilize its power, the more we move towards creating robust, scalable, and maintainable software solutions. Nx is genuinely leading the way in the future of software architecture.

Plugin Architecture for Angular Libraries using Dependency Injection

Nacho Vazquez — Tue, 06 Apr 2021 19:43:00 +0000

The plugin architecture is a well-known software design pattern used for its flexibility, extensibility, and isolation. It consists of a core system and several separate plugin modules.

We will cover how to create a plugin-based architecture in Angular using its Dependency Injection system and why this is an excellent tool to have in our Engineers belt.

Plugin Architecture

The Plugin Architecture concept is simple: the Core System manages the essential functionalities and orchestrates the Plugins, but it is agnostic in its behavior. The Plugins implement the use-case-specific functionalities, and they are agnostic of other plugins and the system behavior.

The Core System is responsible for defining the contract used by itself and the Plugins to communicate.

Plugins aren't necessarily designed for a particular Core System, but in those cases, an adapter is required to make the Plugins follow the contract.

The main principles related to this kind of Architecture are the Inversion of Control (IoC) Principle and the Dependency Inversion Principle (DIP, the D from the SOLID principles)

While the Plugins follow the IoC by extracting behavior and control from the main flow or Core System, the DIP is necessary for avoiding coupling and establishing the contract.

Dependency Injection is not the only design pattern that allows building a Plugin Architecture or follows the IoC Principle; callbacks, schedulers, event loops, and message queues are also valid options.

If you are interested in learning more about Plugin Architecture, check the following links.

Plugin-based Angular Libraries

The Angular community is big and healthy, every day, new packages get published, and our favorite tools get renewed.

In this constellation, not all libraries are built using a Plugin Architecture, and with a good reason. This pattern is NOT a silver bullet, and you should not try to design all your libraries using Plugins.

But there are some scenarios where the Plugin Architecture provides outstanding flexibility and relief maintainers from creating all possible features for a given domain.
For example, in Components libraries, using content projection is a great way to achieve IoC. From there, it is pretty easy to build plugins that extend your core Component functionality or customize the UI.

This article will focus on another of the design patterns implemented in Angular, the Dependency Injection (DI) pattern.

Implementing a Plugin Architecture with Dependency Injection

As described previously, the Plugin Architecture has two components. The Core System and the Plugins.

The Plugins depend on the Core System, but not the other way around. Therefore, we should start designing the Core System first.

The minimum elements we are going to need are

PluginContract, this is the contract that our Plugins will implement and that the Core System uses for communication.
PluginInjectionToken, in some technologies, the
PluginContract would be used as the injection token. Still, since interfaces are not genuine artifacts in typescript and they disappear at build time, we have to define an additional token. It is good to notice that this splitting also contributes to the separation of concerns.
OrchestrationService will gather all the plugins, orchestrate their behavior, and provide error resolution.

We will also have some configuration elements, optional for small and straightforward systems but instrumental in building flexible libraries.

PluginConfiguration contains information about the integration of the Plugin with the Core system. The OrchestrationService uses it to identify if it should execute a Plugin and how. The Plugin can extend it to configure internal Plugin behavior. The core system can provide a default configuration for the Plugins.
PluginConfigurationToken, injection token for the PluginConfiguration
CoreConfiguration provides configuration at a Core level, makes the overall system execute in a certain way.
CoreConfigurationToken, injection token for the CoreConfiguration

The dependency flow would look like Fig.2.

The Angular code

Now that we have a big picture of our architectural design let's jump into the details and learn how to implement our library following this pattern.

The core system

The first thing we need is the contract that our plugins need to implement to communicate with the core system.

import { PluginConfig } from './plugin.config';

export interface SystemPlugin {
  config: PluginConfig; // 👈

  operationA(...args: unknown[]): unknown;
  operationB(...args: unknown[]): unknown;
  operationZ(...args: unknown[]): unknown;
}

This contract could have any signature; it is up to the library that you are building. The only remarkable element is the config. We are forcing the Plugin to have it since the Core System needs it to handle the Plugin correctly.

The config itself is very basic and generic for our demonstrational purpose. Still, the idea is to define in the PluginConfig everything that we want to make adjustable in our Plugin behavior. This config can serve both the Plugin and the Core System.

export interface PluginConfig {
  optionA: unknown;
  optionB: unknown;
  optionZ: unknown;
}

Of course, we need some injectors here since we cannot use the interfaces with Angular Dependency Injection. Let's add those.

import { InjectionToken } from '@angular/core';
import { SystemPlugin } from './plugin';

export const pluginToken: InjectionToken<SystemPlugin> = new InjectionToken(
  '__PLUGIN_TOKEN__'
);

and

import { InjectionToken } from '@angular/core';
import { PluginConfig } from './plugin.config';

export const pluginConfigToken: InjectionToken<PluginConfig> = new InjectionToken(
  '__PLUGIN_CONFIG_TOKEN__'
);

The next thing we are going to implement is our Core System configuration.

export interface CoreConfig {
  coreOptionsA: unknown;
  coreOptionsB: unknown;
  coreOptionsZ: unknown;
}

The CoreConfig, like all other elements of this example, should be implemented accordingly with your library. For simplicity, let's imagine it represents all the different configurable tweaks we can make to our Core System. Occasionally, part of the configuration options of the CoreConfig is used as global defaults for not required configuration options in the PluginConfig.

As before, we will also create the coreConfigToken to inject the CoreConfig.

import { InjectionToken } from '@angular/core';
import { CoreConfig } from './core.config';

export const coreConfigToken: InjectionToken<CoreConfig> = new InjectionToken(
  '__CORE_CONFIG_TOKEN__'
);

Next, let's take a look at our OrchestratorService, the heart of our library. In our example, the OrchestratorService will also be the entry point to our library, but this is not required. The library entry points can vary from a directive to a secondary service that uses the orchestrator service to any other communication form between the client code and our library.

import { Inject, Injectable, Optional } from '@angular/core';
import { coreConfigToken } from './core-config.token';
import { CoreConfig } from './core.config';
import { SystemPlugin } from './plugin';
import { pluginToken } from './plugin.token';

@Injectable({ providedIn: 'root' })
export class OrchestratorService {
  private readonly plugins: SystemPlugin[];

  constructor(
    @Optional()
    @Inject(pluginToken)
    plugins: SystemPlugin[],
    @Inject(coreConfigToken) private config: CoreConfig
  ) {
    plugins = plugins || [];
    this.plugins = Array.isArray(plugins) ? plugins : [plugins];
  }

  coreOperationA(...args: any[]): unknown {
    // just a demonstration of what can be done
    return this.plugins
      .filter((plugin) => this.canPluginExecute(plugin))
      .reduce<unknown>((acc, plugin) => plugin.operationA(acc), null);
  }

  private canPluginExecute(plugin: SystemPlugin): boolean {
    // implement any validation to determine whether the plugin should be executed or not

    // use the  core config and/or the driver config

    // just a demonstration of what can be done
    return (
      (this.config.coreOptionsA as boolean) &&
      (plugin.config.optionA as boolean)
    );
  }
}

Wow, a lot is going on in there. Since this service is larger than the other files, let's split it to understand what is going on.

constructor(
    @Optional()
    @Inject(pluginToken)
    plugins: SystemPlugin[],
    @Inject(coreConfigToken) private config: CoreConfig
  ) {
    plugins = plugins || [];
    this.plugins = Array.isArray(plugins) ? plugins : [plugins];
  }

The first thing we need to do is inject what we are going to need.

The key elements are the Plugins, and I want to emphasize the plural, Plugins. We are receiving an Array of Plugins. However, it is possible that we only received a single Plugin or none plugin at all. In such cases, we need to transform the data to a suitable form, to an Array.

But, how is it possible to receive multiple instances of the same Injection token? That's one of the critical ingredients when using Angular's Dependency Injection as the Plugin Architecture mechanism. We will go over this feature when we provide our Plugins, but the key is in the multi options of Angular's StaticProvider.

 coreOperationA(...args: any[]): unknown {
    // just a demonstration of what can be done
    return this.plugins
      .filter((plugin) => this.canPluginExecute(plugin))
      .reduce<unknown>((acc, plugin) => plugin.operationA(acc), null);
  }

The coreOperationA is an example of how the client code could use our library and how the OrchestratorService handles our plugins.

The example implementation shows how we can filter which plugins are configured to execute at a given moment and how to compose the different plugins to build a response. Real-world implementations could differ significantly, but the point is that we can access all the configured plugins and make decisions about them in our orchestrator.

Finally, we use our canPluginExecute method to determine if a Plugin should be used or not based on both the CoreConfig and the PluginConfig.

 private canPluginExecute(plugin: SystemPlugin): boolean {
    // implement any validation to determine whether the plugin should be executed or not

    // use the  core config and/or the driver config

    // just a demonstration of what can be done
    return (
      (this.config.coreOptionsA as boolean) &&
      (plugin.config.optionA as boolean)
    );
  }

And that's it. That is our Core System, well almost, we still need a module to configure everything. Let's see how we can do that.

import { ModuleWithProviders, NgModule } from '@angular/core';

import { CoreConfig } from './core.config';
import { coreConfigToken } from './core-config.token';

@NgModule()
export class CoreSystemModule {
  static forRoot(config: CoreConfig): ModuleWithProviders<CoreSystemModule> {
    return {
      ngModule: CoreSystemModule,
      providers: [{ provide: coreConfigToken, useValue: config }],
    };
  }
}

We are using the static method forRoot to received the CoreConfig configuration from the client code and then provided it to the DI system. Otherwise, we might not need to have a module, but this is a well-known pattern.

The Plugins

The Core System exports everything we need, and possibly it could execute independently, but a Plugin Architecture makes little sense without plugins.

Let's start by implementing our SystemPlugin contract; that's where our unique Plugin logic will leave after all.

import { Inject, Injectable } from '@angular/core';
import {
  PluginConfig,
  pluginConfigToken,
  SystemPlugin,
} from 'projects/core-system/src/public-api';

@Injectable()
export class ExamplePlugin implements SystemPlugin {
  constructor(@Inject(pluginConfigToken) readonly config: PluginConfig) {}
  operationA(...args: unknown[]): unknown {
    throw new Error('Method not implemented.');
  }
  operationB(...args: unknown[]): unknown {
    throw new Error('Method not implemented.');
  }
  operationZ(...args: unknown[]): unknown {
    throw new Error('Method not implemented.');
  }
}

We need to inject our PluginConfig and implement the interface; the particular implementation is unique to every Plugin. This example shows non-implemented methods, but the idea is there.

The final piece and essential part is the Plugin configuration.

import { ModuleWithProviders, NgModule } from '@angular/core';
import {
  PluginConfig,
  pluginConfigToken,
  pluginToken,
} from 'projects/core-system/src/public-api';
import { ExamplePlugin } from './example.plugin';
export function examplePluginFactory(config: PluginConfig): ExamplePlugin {
  return new ExamplePlugin(config);
}
@NgModule()
export class ExamplePluginModule {
  static forRoot(
    config: PluginConfig
  ): ModuleWithProviders<ExamplePluginModule> {
    return {
      ngModule: ExamplePluginModule,
      providers: [
        { provide: pluginConfigToken, useValue: config },
        {
          provide: pluginToken,
          useFactory: examplePluginFactory,
          deps: [pluginConfigToken],
          multi: true,
        },
      ],
    };
  }
}

Firstly, we are receiving the PluginConfig from the client code and providing it to the Dependency Injection system. Then it is time to provide our Plugin.

Since our Plugin depends on the provided PluginConfig we need to use a factory function combined with the deps property.

The critical part is the multi options. If missed, that single configuration can make the whole system fail because it can overwrite all other plugins and only provide the one without multi. When set to true, it enables the power of importing multiple artifacts using a single injection token, in this case, our Plugins.

And that's all we need! Now we can start using our Plugin-based library.

Usage

Like with any other Angular library, we have to import it and configure its module.

import { NgModule } from '@angular/core';
import { BrowserModule } from '@angular/platform-browser';
import { CoreSystemModule } from 'projects/core-system/src/public-api';

import { AppComponent } from './app.component';

@NgModule({
  declarations: [AppComponent],
  imports: [
    BrowserModule,
    CoreSystemModule.forRoot({
      coreOptionsA: '_A_',
      coreOptionsB: '_B_',
      coreOptionsZ: '_Z_',
    }),
  ],
  bootstrap: [AppComponent],
})
export class AppModule {}

Now we can start using our OrchestratorService or any other communication form we have in place in our library.

However, we will not go far if we don't have any Plugins; let's add the one we already implemented.

import { NgModule } from '@angular/core';
import { BrowserModule } from '@angular/platform-browser';
import { CoreSystemModule } from 'projects/core-system/src/public-api';
import { ExamplePluginModule } from 'projects/example-plugin/src/public-api';

import { AppComponent } from './app.component';

@NgModule({
  declarations: [AppComponent],
  imports: [
    BrowserModule,
    CoreSystemModule.forRoot({
      coreOptionsA: '_A_',
      coreOptionsB: '_B_',
      coreOptionsZ: '_Z_',
    }),
    ExamplePluginModule.forRoot({
      optionA: '-A-',
      optionB: '-B-',
      optionZ: '-Z-',
    }),
  ],
  bootstrap: [AppComponent],
})
export class AppModule {}

And as simple as that, without letting the CoreSystemModule know anything about our Plugin, we have our system configured.

I hope you can appreciate the simplicity of the configuration of our Plugin Architecture. Exactly as we imported our ExamplePluginModule, we can import as many Plugins as we want, following the same structure. The Core System will access all the imported Plugins and manage their usage for us.

Now we are set up, let's start using our library.

import { Component } from '@angular/core';
import { OrchestratorService } from 'projects/core-system/src/public-api';

@Component({
  selector: 'app-root',
  templateUrl: './app.component.html',
  styleUrls: ['./app.component.scss'],
})
export class AppComponent {
  title = 'plugins-architecture-demo';

  constructor(private orchestrator: OrchestratorService) {
    this.orchestrator.coreOperationA();
  }
}

The client application or library now only has to inject our library entry point. In our example, it is the OrchestrationService. Then, it can start interacting with the library. Plugins are only a concern of the library. The client code is agnostic to the Plugins' existence except for the configuration part.

Conclusion

The Plugin Architecture pattern is a great pattern to create extensible systems using the Inversion of Control Principle and lift our system's focused functionalities to the Plugins.

We have learned how to implement a custom Angular library following a Plugin Architecture using Angular Dependency Injection while briefly introducing the Angular Dependency Injection elements that allow us to make our Plugins decoupled from our Core System.

You can find the final solution at this repo

And if you want to see a real-world usage of this pattern, you can visit Lumberjack

Semantic Grouping Folders with Nx

Nacho Vazquez — Tue, 06 Apr 2021 05:30:07 +0000

Photo by Barn Images on Unsplash

This article is part of the Angular Architectural Patterns series.

Grouping Folders in an Nx and Monorepo context are folders that only contain other Grouping Folders and projects (applications, libraries, testing projects).

In this article, we will focus on Grouping Folders containing other Grouping Folders and libraries.

They help us enforce our architectural decisions and act as a guideline for our team.

This article will discuss the most common types of Grouping Folders and their impact on our architecture.

We will also discover how to use Nx schematics to give additional semantic value to our Grouping Folders.

A world without Grouping Folders

Why do we need Grouping Folders?

That is a very valid question; I'm happy you asked!

It would be better if I show you.

The following folder structure is a snapshot of a fictitious airline software project taken from the free Nrwl e-book.

Listing 1. Ungrouped libraries workspace

Listing 1. is a contrived example; production apps could have hundreds of libraries and dozens of applications.

It follows the Nx suggested type libraries; it uses shell libraries to coordinate configuration and navigation.

However, it is hard to grasp by just looking at this structure, which files you are supposed to work on when dealing with a new use case or making amendments to an existing one.

Therefore, it is violating the Common Closure Principle.

We struggle to keep control of the relationship between our libraries and applications.

It is not easy to tell if we are implementing strategic design since we don't have clear evidence of Bounded Contexts or vertical slices.

This design problem is time-consuming for the developer, and the harm grows at the same rate as the source code.

There is a short limit of how many "naked" libraries we can handle.

Can Grouping Folders help?

Seeking shelter on Grouping Folders

When we are writing Nx and Monorepo based projects, we are encouraged to split our application content into libraries.

There are many ways to perform such splitting, but four main basic classifiers guide this process; we split our libraries by scope, type, platform, and technology.

Classifiers are represented in our workspace as Tags.

Tags are a great tool to enforce horizontal and vertical dependency boundaries, making them an efficient mechanism to guide the creation of library-enclosing Grouping Folders.

The following sections describe the fundamental Grouping Folders building-blocks created due to a successful library classification and tagging.

Those are the foundations of more elaborate architectural structures and Grouping Folder combinations.

Scope Building Blocks

The library's scope tag provides context about the piece of the domain to which the library is related or subordinated.

The matching Grouping Folder could represent the domain-wise application, a Bounded Context, or merely a vertical slice in the domain to which it belongs.

Scope: Application

We use the Application Grouping Folders to organize libraries exclusive to an application of the workspace.

Having our libraries restricted to a single application is a simple and effective way to group our libraries by scope.

It focuses on how libraries collaborate at a higher level, increasing cohesion and readability.

Listing 2. Grouping folders by scope Application group workspace libraries based on the application where they are used.

Listing 2. shows us a typical example of application-scoped Grouping Folders.

In that workspace, airline-admin and airline-b2c are individually deployed applications.

Grouping Folders with the same name as workspace applications encapsulate all libraries specific to the matching application.

As a consistency recommendation, we should have one Grouping Folder per workspace application when following this pattern.

Each application imports and orchestrates its specific libraries by using a single feature-shell library.

The third Grouping Folder in Listing 2. is an application-level Shared Grouping Folder.

Application-level Shared Grouping Folders contains the libraries used between the different workspace applications, extracting common logic and other sharable code.

Application Grouping folders can be created at the root scope level (as a child of the libs folder), as a child of a root-level Platform grouping folder, or as a child of a root-level Technology grouping folder.

Scope: Bounded Context

Bounded Context Grouping folders cluster sub-domain-specific libraries that change at the same pace or for the same reasons.

This way of organizing our libraries produces a higher cohesion than only using Application Grouping Folders.

We cluster our libraries in more tight groups following the Common Closure Principle and the domain experts' descriptions of the model.

Bounded Context is a Domain-Driven Design concept with a more significant implication than just acting as a grouper.

Vertical Slice is a more general concept compatible with Bounded Contexts when talking about Grouping Folders' usage.

Nonetheless, both concepts are used interchangeably in the current article.

Listing 3. Grouping folders by scope Bounded Context group workspace libraries based on the Bounded Context where they are used.

Listing 3. is a representation of a Bounded Context organized workspace.

In the example, booking and check-in are vertical slices of the application domain.

Grouping Folders contain libraries marked with the tag scope:<bounded-context-name> or bc:<bounded-context-name> for greater granularity.

Libraries in a Bounded Context Grouping Folder can be used in different workspace applications.

However, it is a good recommendation NOT to import libraries from a Bounded Context Grouping Folder directly.

Instead, treat the functionality inside these Grouping Folders as a unit.

Use one or more Composite Shell libraries as the Bounded Context entry points.

As a result, we can connect applications and Bounded Context Grouping Folders in a many-to-many cardinality.

The third Grouping Folder in Listing 3. is a bounded-context-level Shared Grouping Folder.

Bounded-Context-level Shared Grouping Folders contains the libraries shared between the different libraries at the same Grouping Folder level.

Bounded Context grouping folders can be created independently and as a child of an application Grouping folder.

Platform

The platform tag refers to the deployment platform, like web, mobile, or desktop.

It organizes features that are only included in the platform build of an application or Bounded-Context/Vertical-Slice.

It may only make sense when the same application or bounded context is used differently for different platforms.

Listing 4.Grouping folders by Platform group workspace libraries that are specific to a deployment platform.

Listing 4. shows how inside the same sub-domain, we can split logic based on the platform where it is meant to be used.

This example shows that two feature-seat-listing libraries are present, one for each platform.

These libraries are not the same, they provide the same or a similar feature, but they are implemented differently for each platform.

Creating the Platform Grouping Folder, adds semantic value to each library, and therefore there is no need for extra differentiation like prefixing or suffixing the library name with the platform type.

Platform-level Shared Grouping Folders contain libraries that are being used by different platforms at the same scope level.

In the example, web, mobile, and shared are Platform Grouping folders used at an Application or Vertical slice scope level of name Booking.

The Platform Grouping Folders can be created at any scope level.

Technology

The technology classifier includes all those libraries that can only be used in a particular technology context.

It could be a high-level division like api and client or, more specific like react and angular.

It could also separate libraries from different languages or frameworks like Go and C#.

Do not confuse with Platform Grouping Folders which only refer to the change of features based on the deployed platform.

Listing 5. Grouping folders by Technology group workspace libraries that are specific to a development technology.

Listing 5. shows how server-side libraries are grouped independently of client-side libraries.

Technology-level shared Grouping Folders contain those libraries that can be used between different technologies.

A good candidate for the shared Grouping Folder is the DTO library. However, this is only possible when the technologies are dealing with the same programming language.

The Technology Grouping Folders should only exist as a direct child of the libs folder.

Type

The type classifiers identify to which horizontal layer of functionality our library belongs.

It could be data-access, agnostic ui, business specific feature, utils and others.

Most of the time, you would not create Grouping Folders for this type of classifier. Instead, it is usual to use these classifiers as a prefix of the libraries' names and include them in scope-type Grouping Folders.

Nonetheless, if the number of libraries inside a Grouping folder increases, adding type-based Grouping Folders can lighten the burden.

Listing 6. Type grouping folders organize libraries with the same type classifier

Listing 6. shows how we can organize our libraries by their type.

The Type Grouping Folders can be created at any scope level.

A word on Shared Grouping folders

Shared Grouping folders can be created by Scope, Platform, and sometimes by Technology.

Shared Grouping folders semantic level is determined by the classifier of its siblings' Grouping Folders.

For example, if a Shared Grouping Folder is the sibling of one or more Bounded Context Grouping Folders, it is a Bounded Context-level Shared Grouping Folder.

This design decision derives some extra rules.

Every scope level, including the root scope level, can only contain Grouping Folders of a single classifier type (technology, platform, application, or bounded context).
Libraries inside a Shared Grouping Folder can only be accessed by the libraries within its siblings' Grouping Folders or by libraries in children Grouping Folders.

Of course, all the mentioned restrictions are made to ensure a consistent, maintainable design. Unless you actively enforce these constraints in your tslint/eslint configuration, it is a matter of discipline to keep your workspace sharp.

Tags and restrictions

When creating a grouping folder, we are also creating a semantic context that encloses our libraries.

A different way of defining and enforcing this context is by using tags and restrictions.

Library tags are declared in the nx.json configuration file. In contrast, restrictions are added as eslint/tslint rules.

It is often recommended to create companion tags for our Grouping Folders and vice-versa.

Nrwl, in its Architecture Free E-books, articles and documentation usually mention two tag and restriction dimensions; scope and type.

In this article, we have added the technology and platform dimensions. Also, we have expanded the scope dimension in two, application and bounded context (bc).

Using type, technology, application, platform, and bc as our tags dimension instead of scope and type, allow us to achieve fined grain restrictions.

Otherwise, we could not distinguish a Technology-level Shared Grouping folder from other Shared Grouping Folders from a restriction perspective.

When creating a new library, this library should inherit all the tags related to its ancestors Grouping Folders.

Composing

In previous sections, we have briefly mentioned some limitations about where to place our Grouping Folders. Now, we will see some real examples of Grouping Folder composition.

Going back to the Nrwl Airlines example, let's see how we can fix the flat folder structure mess seen at this article's start.

Listing 7. Refactored Nrwl Airlines example using all existing Grouping Folders

Listing 7. shows how we could refactor the Listing 1. example by using all the discussed Grouping Folder types.

This is an extreme, demonstration-only usage of our Grouping Folders. It serves as educational material.

In practice, we might not want to have this level of nesting and use only a few Grouping Folder types.

However, Listing 7 can be a valid use case as it is.

Technology Grouping Folders

We use api and client as our top Technology Grouping folders. Those split our libraries between Backend and Frontend libraries.

Now we can add "technology:api" and "technology:client" as tags for every library place in one of these folders. Then we can add restrictions to enforce the boundaries.

{
    "sourceTag": "technology:api",
    "onlyDependOnLibsWithTags": [
       "technology:api",
       "technology:shared"
    ]
},
{
    "sourceTag": "technology:client",
    "onlyDependOnLibsWithTags": [
       "technology:client",
       "technology:shared"
    ]
},
{
    "sourceTag": "technology:shared",
    "onlyDependOnLibsWithTags": [
       "technology:shared"
    ]
},

At the same level, we added a Technology-level shared Grouping Folder where we placed the DTO's library.

The DTO's library and any other library in the Technology-level shared Grouping Folder receives the tag "technology:shared".

Application Grouping Folders

One level below Technology, we placed our Application Grouping Folders, where we can isolate and group everything unique to each Application.

Every library grouped into an Application Grouping Folder should have a tag identifying the application to where they belong.

For example, every library descendent of the airline-admin Application Grouping Folder should at least have the tags "application:airline-admin" and "technology:client".

We could add the following restrictions for the current example.

{
    "sourceTag": "application:airline-admin",
    "onlyDependOnLibsWithTags": [
       "application:airline-admin",
       "application:shared"
    ]
},
{
    "sourceTag": "application:shared",
    "onlyDependOnLibsWithTags": [
       "application:shared"
    ]
},

A sibling Application-level Grouping Folder is present. This contains the ui-button and utils-date-pipe libraries shared between all our applications.

These shared Grouping Folders will receive the application:shared tag.

Bounded Context Grouping Folders

Our application airline-admin contains two Bounded Contexts, booking, and check-in.

One Grouping Folders of the same name is created for each of our Bounded Contexts plus a Bounded-Context-level Shared Grouping Folder.

The resulting tags can be "bc:booking", "bc:check-in" and "bc:shared" and the following restrictions can be applied.

{
    "sourceTag": "bc:booking",
    "onlyDependOnLibsWithTags": [
       "bc:booking",
       "bc:shared"
    ]
},
{
    "sourceTag": "bc:check-in",
    "onlyDependOnLibsWithTags": [
       "bc:check-in",
       "bc:shared"
    ]
},
{
    "sourceTag": "bc:shared",
    "onlyDependOnLibsWithTags": [
       "bc:shared"
    ]
},

Platform Grouping Folders

web and mobile are our Platform Grouping Folders. They also shared common logic using a Platform-level Shared Grouping Folder.

Within our Platforms Grouping Folders, we placed platform-specific libraries, no matter the libraries' depth.

The resulting tags are "platform:mobile", "platform:web" and "platform:shared".

Adding the restrictions.

{
    "sourceTag": "platform:web",
    "onlyDependOnLibsWithTags": [
       "platform:web",
       "platform:shared"
    ]
},
{
    "sourceTag": "platform:mobile",
    "onlyDependOnLibsWithTags": [
       "platform:mobile",
       "platform:shared"
    ]
},
{
    "sourceTag": "platform:shared",
    "onlyDependOnLibsWithTags": [
       "platform:shared"
    ]
},

Type Grouping Folders

Finally, we created a "feature" Type Grouping folder where we placed the multiple "feature" libraries at a given level.

Type Grouping Folders don't have sibling shared Grouping Folders.

The related tag, in this case, would be "type:feature", but it is independent of the existence of the Grouping Folder library.

Different decisions could have been made for the current example, but it is clear that Grouping Folders play a major role in our system architecture.

Acknowledgements

This article wouldn't be possible without the long and stimulating discussion with my friend and mentor Lars Gyrup Brink Nielsen who always provides the most accurate reviews.

Thanks to Nacho Vazquez Sr, my dear father, for helping me to find the right words when English was challenging.

Conclusions

Maintaining large multi-application monorepos involves discipline, good practices, and clear guidelines.

Grouping Folders can help your team to create boundaries and enforce organization and architectural decisions.

In this article, we have covered some of the most common Grouping Folders.

We saw how Nx tags and restrictions can provide additional semantic value to our folders, and together enforce the architectural boundaries defined beforehand.

This is just an introduction, be imaginative and adapt your solution to the problems. Find new ways of composing Grouping Folders, and create the companion rules that best apply to your workspace.

Forem: Nacho Vazquez

Announcing Lumberjack v16: Life improvements, deprecations and an ambicius roadmap

New level-based logging methods

NgModule deprecation

Ambitious Secret Project

Community

DEV

Wrapping Up

Architects Delight: Enforcing Layers and Project Boundaries with Nx

Introduction

The Hidden Side of the Iceberg

What are Project Boundaries and Layers?

Creating Projects and Boundaries with Nx

Enforcing Project Boundaries with Nx

Conclusion

Plugin Architecture for Angular Libraries using Dependency Injection

Plugin Architecture

Plugin-based Angular Libraries

Implementing a Plugin Architecture with Dependency Injection

The Angular code

The core system

The Plugins

Usage

Conclusion

Semantic Grouping Folders with Nx

A world without Grouping Folders

Seeking shelter on Grouping Folders

Scope Building Blocks

Scope: Application

Scope: Bounded Context

Platform

Technology

Type

A word on Shared Grouping folders

Tags and restrictions

Composing

Technology Grouping Folders

Application Grouping Folders

Bounded Context Grouping Folders

Platform Grouping Folders

Type Grouping Folders

Acknowledgements

Conclusions

References