Forem: Dana Ciubancan

From Angular 16 to 17: The Strategy and The Results

Dana Ciubancan — Wed, 22 Jan 2025 12:27:57 +0000

Although a bit late to the party, I recently took on the task of upgrading a complex Angular project from version 16 to 17. While the official upgrade guide provides a great foundation, every project has unique challenges. Here’s my journey through the upgrade process, including the obstacles I encountered and how I resolved them. I hope sharing these experiences helps others facing similar challenges.

The Upgrade Strategy

When starting an upgrade, I always (re-)read the official announcement (Angular 17) to understand how our project might be impacted, what improvements I can bring to our codebase, and what new guidelines and concepts I can promote to our team.

The second step is to check Angular’s official update guide for similar reasons: getting an understanding of possible failure points and changes I can expect in the code as part of the migration to the new version.

The next and final step before starting the hands-on migration is to check the Angular-NX version compatibility matrix. Since our project uses NX this will be the driver for our migration steps.

Another step I take, usually before I even consider an upgrade, is to check all our third-party dependencies and see if we might have any compatibility issues and possible solutions for them. With this in mind, after our main migration has successfully taken place I update each one of them to a compatible version.

The Update Process

For the update process, I always take an incremental approach: updating through each minor version rather than jumping straight to the latest. This helps me better identify the cause and resolve issues at each step.
We’ve also decided to keep the NX version in sync with Angular and have not updated to the latest NX version. So, given the Angular-NX compatibility matrix below, we had a four-step migration on our hands: 17.1.0 -> 17.3.0 -> 18.1.1 -> 18.2.0.

For each NX version, we followed these steps:

npx nx migrate <nx-version> — Initiate the migration
Review and validate changes
npm install — Update dependencies
Commit changes
npx nx migrate --run-migrations - Execute migrations
Test, lint, and build for production

Version-specific Challenges

npx nx migrate 17.1.0

Our first interesting challenge was upgrading to NX version 17.1.0. The migration failed instantly. Can you guess why? :) NX version 17.1.0 doesn’t exist. If you go digging through versions you will see there have been some 17.1.0 beta versions but then directly 17.1.1.

The solution was to use npx nx migrate 17.1 instead of 17.1.0, which allowed us to upgrade to the latest 17.1.x version.

This first migration step updated the code base to the Angular 17 version and this brought our main issues of the migration, the unsupported libraries:

ngx-matomo
ngx-quill

ngx-matomo hasn’t seen updates in 2 years and it doesn’t support Angular 17. While this library has served us well until now, we moved to ngx-matomo-client which offers the same functionality with few code changes and it is better maintained. For more details into this transition, you can check out my ngx-matomo to ngx-matomo-client article.

The ngx-quill version that we had was using quill v1 underneath and only ngx-quill versions using quill v2 were also supporting Angular 17. While I thought quill v2 would bring many changes, the transition was quite smooth. We only encountered issues with our keyboard bindings, where we had to migrate from using key number values to names: key: 13 -> key: ‘Enter’

Other changes that we had to address included some changes to eslint rules that cause our linting step to fail. I reviewed the changes and decided for each to either adjust the code or adjust the rule.

npx nx migrate 17.3.0

During this phase, we encountered several (smaller) challenges:

Jest undefined errors required explicit imports from @jest/globals
Comply with new lint rules regarding paths and module boundaries

A notable issue we encountered was with the NX CLI commands. The nx serve --project=project-name syntax stopped working in this version. While this was fixed in later NX versions, we temporarily switched to using nx run project-name:serve as a workaround.

Versions 18.1.0 and 18.2.0

I have no issues to report for versions 18.1.0 and 18.2.0. The NX migrations worked perfectly on our code!

Additional Angular 17 Improvements

We took this upgrade opportunity to implement some significant improvements in our codebase:

Standalone Components Migration

While we have been migrating components to standalone one-by-one as part of our day-to-day business, we now took the opportunity to migrate all components (except the main app component). While this wasn’t strictly required for Angular 17, it aligned well with the framework’s direction and helped modernize our codebase.

Built-in Control Flow Implementation

Implementing the new control flow syntax was one of our major goals. To optimise this step, I used the automatic migration command npx nx generate @angular/core:control-flow-migration and then checked each changed file (yeah, about 300 of them), to make sure no defects were introduced. Plus, additional changes were needed for the @for track by to be properly set. Besides this, I also discovered some important caveats of using the automated migration:

At times it deleted <ng-template> tags which led to duplicated code and broken ViewChild references
Elements within new if/else statements that were used for content projection using <ng-content select="..."> needed wrapping with <ng-container>to work properly

Looking forward

This upgrade has been an exciting journey. The performance benefits from the new control flow syntax are already noticeable in our application. I’m particularly looking forward to expanding our use of Angular 17’s features, especially implementing signals and deferrable views in the coming months.

Conclusion

While every Angular project is unique, I hope sharing my way of approaching the upgrade, as well as the specific challenges and solutions I encountered, helps you plan your upgrade to Angular 17.

Remember that the official upgrade guide is your foundation, but be prepared to tackle project-specific issues along the way. Take time to review your project’s dependencies and test thoroughly at each step.

Cheers!

Migrate from ngx-matomo to ngx-matomo-client

Dana Ciubancan — Fri, 16 Aug 2024 06:00:00 +0000

Funny enough, my first interaction with Matomo was on the exact date they switched from Piwik.

While ngx-matomo has been my go-to library for Matomo integration in Angular projects ever since, its delayed compatibility with recent Angular versions has motivated me to research other available options.

In this article, I'll go over the reasons you might want to stick to ngx-matomo, but also what to do when you decide to switch.

Why ngx-matomo to begin with?

When I first had to integrate Matomo in an Angular project, ngx-matomo was one of the few libraries available. It was quick to set up and easy to understand, so it was the best choice at the moment, the alternative being writing the integration from scratch.

We used features ranging from tracking regular user navigation to advanced tracking via tag manager configurations and custom variables.

What I appreciate about the library:

it's easy to get started with
it has simple user consent management
it comes with a small bundle, of 16.18kb on the production build

If you are already using ngx-matomo and are not looking to use the latest versions of Angular early on, this library still covers most of the use cases you might be looking for.

You can follow this thread for updates on the latest Angular version support (Angular 18).

Best alternative: ngx-matomo-client

Previously distributed as two separate packages (ngx-matomo/tracker and ngx-matomo/router), ngx-matomo-client is now the most popular and well-maintained Angular library for Matomo integration. Taking into account also its resemblance to the existing library and its minimal impact of just 15.92 kb on our production build, ngx-matomo-client stood out as the most logical for replacing ngx-matomo.

If you are starting from scratch, I would definitely recommend going directly for the ngx-matomo-client library.

In the following sections, I will show you how I translated the capabilities of ngx-matomo into ngx-matomo-client.

Configuration

First up, is the configuration. This part has suffered the most changes, but it is still quite straightforward.

In ngx-matomo, the configuration and module import might look something like the following:

// app.module.ts
import { MatomoModule } from 'ngx-matomo';
...
imports: [
  ...
  MatomoModule.forRoot(environment.matomoConfig)
  ...
]

// environment config

matomoConfig: {
  scriptUrl: `${matomoBaseUrl}/js/container_<containerId>.js`,
  trackers: [
    {
      trackerUrl: `${matomoBaseUrl}/matomo.php`,
      siteId: 1,
    },
  ],
  requireConsent: true,
  routeTracking: {
    enable: true,
  },
},

For ngx-matomo-client it is a bit simpler, making use of Angular injection for including route tracking:

// app.module.ts
import { MatomoModule, MatomoRouterModule } from 'ngx-matomo-client';
...
imports: [
  ...
  MatomoModule.forRoot(environment.matomoConfig),
  MatomoRouterModule,
  ...
]

// environment config

matomoConfig: {
  siteId: 1,
  trackerUrl: `${matomoBaseUrl}`,
  scriptUrl: `${matomoBaseUrl}/js/container_<containerId>.js`,
  requireConsent: 'tracking',
},

If no route tracking is needed, the MatomoRouterModule can be skipped and the import of MatomoModule can be adjusted to avoid dependencies on @angular/router as seen below:

// app.module.ts
import { MatomoModule } from 'ngx-matomo-client/core';
...

If you only need to ask user consent for using cookies and not the tracking itself, the equivalent configurations are the following:

// ngx-matomo
{
  ...
  requireConsent: false,
  requireCookieConsent: true
}

// ngx-matomo-client
{
  ...
  requireConsent: 'cookie'
}

User consent management

For managing user consent opt-in, there is not much difference between the two libraries. Both of them have similar methods on a class called MatomoTracker, so what you have to do is make sure you change the import to the new library.

import { MatomoTracker } from 'ngx-matomo-client';

// usage
this.matomoTracker.rememberConsentGiven(hoursToExpire);
this.matomoTracker.forgetConsentGiven();

Custom variables and custom dimensions

Similar to user consent, methods like setUserId, setCustomVariable, setCustomDimension are the same for both libraries. Here as well you just need to make sure the import is updated to the new library.

Custom event triggers

In our project, we had the need to create triggers based on custom events. This is a requirement that none of the two libraries provide a wrapper for, so for this, we were left interacting directly with the _mtm object.

You can read more about this and why we no longer use a third-party library in my article about architectural mistakes.

Closing thoughts

When looking into libraries I looked into the ones that focus on direct integration with Matomo. If you are looking for a vendor-agnostic library you might want to look into the following:

https://www.npmjs.com/package/angulartics2

I hope you found this article helpful. Let me know in the comments section what was your experience with integrating Matomo.

Learn from small architectural mistakes — Frontend edition

Dana Ciubancan — Tue, 13 Aug 2024 06:51:42 +0000

As a junior developer, I would always reach out to a third-party library to cover my needs. Ranging from combo boxes to dialogs and toast messages, if it was out there it was definitely the best choice.

I would later learn that, at times, it’s better to write your own code and be independent. You will understand why after reading this article.

Background: The Project and the Library

The starting point was the need to integrate Matomo into our Angular application to gain more insights regarding its usage.

To do this, there are a couple of libraries that offer wrapper functionality over the Matomo interface, the one that I recommend being ngx-matomo-client.

There was just one requirement we couldn’t cover by the main integration library. We needed to create an event to be used as the trigger in our tag manager configuration.

Matomo offers this by creating a trigger of type Custom Event. And based on their documentation, this is how it should work:

Triggered when a custom event is pushed to the Data-Layer. Allows developers to define manually when this trigger should be triggered by pushing an event to the Data-Layer. This way you can for example execute certain actions when a product is added to the cart, or when a user logs in.

The Decision to Integrate

The Matomo Data Layer is represented by the _mtm object and this is what we needed to interact with to achieve our last requirement. There were close to no examples of people using it and interacting directly with it, so we were not sure if this was the best approach or whether we should continue digging.

Then, we found our holy grail, angular-matomo-tag-manager library.

It was doing just what we needed, a wrapper over sending event information to the Matomo Data Layer. It was working and it was out there. This gave us the assurance we had the right solution, and the library was the obvious choice, right? This was happening three years ago.

Consequences and Confusion

The library depends on Angular v11. At the integration time, our project was using Angular v12, but npm was throwing only warnings for mismatched dependencies, so it didn't catch the attention of the developer who integrated the library.

This became a problem when updating to newer versions of Angular and npm. Both our local and CI/CD builds started failing as npm changed the warnings into errors for mismatching dependencies.

The library had no updates for supporting newer versions of Angular and we were no longer sure why this library was needed, because of course, the person who stumbled upon the issues was not the same as the person who integrated the library, Murphy’s Law at its best.

Pressed for time and unsure of the potential impact of taking the library out, we made the classic mistake of choosing the path of least resistance. We implemented a temporary fix to get our builds running again and moved on, leaving the underlying issue unresolved. Little did we know that the library would no longer get updates and this issue would come back to haunt us repeatedly, each time consuming valuable time and resources.

Newer Angular versions, new version mismatch investigations, the same issues. When we reached this point the third time, we decided to invest a bit more time and finally took the library out.

What is left now, is a one-liner:

window['_mtm'].push({ event: 'eventId' });

Lessons Learned

By far the biggest lesson that I learned from this is that if all you need is a one-liner, don’t integrate a library for it :).

Looking back, the following would have made our journey here easier to navigate:

spend more time understanding what you need before finding a solution (always a lesson, never learned)
have requirement to implementation traceability
don’t hesitate to question legacy code and dependencies

Closing thoughts

As software architects and developers, we often pride ourselves on our ability to leverage existing solutions to solve complex problems efficiently. However, our experience, as described in this article, serves as a reminder that not all integrations are created equal, and the allure of a quick fix can sometimes blind us to the long-term implications of our choices.

Let me know what is your viewpoint when it comes to integrating third-party libraries and if our experience changed your perspective in any way.