Forem: Matthieu Drouian

🧰 zsh-pkgmanager-switcher - A ZSH JavaScript package manager switcher plugin

Matthieu Drouian — Wed, 25 Oct 2023 20:30:39 +0000

If you work daily on JavaScript projects with various package manager configurations (npm, yarn, pnpm ...) and you use a ZSH shell (with or without Oh my ZSH), I just released a ZSH plugin to switch the package manager.

This module allows you to automatically load the right package manager by opening your project

The plugin is installed as follows:

git clone <https://github.com/drouian-m/zsh-pkgmanager-switcher> ~/.zsh/zsh-pkgmanager-switcher

Then declare it in your .zshrc file :

source ~/.zsh/zsh-pkgmanager-switcher/zsh-pkgmanager-switcher.zsh

The complete installation documentation is available here : https://github.com/drouian-m/zsh-pkgmanager-switcher/blob/main/INSTALL.md

Demo

Project link

https://github.com/drouian-m/zsh-pkgmanager-switcher

How to use AI to migrate a legacy AngularJS app to VueJS without writing (a lot of) code

Matthieu Drouian — Sun, 15 Oct 2023 06:42:02 +0000

The JavaScript ecosystem has the particularity of being very versatile. Every year, we see new frameworks and new tools replacing those already in place.

If, like me, you have JavaScript in production, you have probably experienced application rewrites for this reason.

Sometimes, applications are easy to rewrite, and it can be done quickly and easily following the deprecation of a framework.

However, if the scope of the application to be migrated is large... it can take a lot of time and represent a significant cost for the company that will tackle this tedious task.

It can even happen that the time estimates are so high that the company decides to give up before having a good reason to take action (security vulnerabilities, ...).

Ask for an AI!

Today AI types GPT3, GPT4 or even GitHub Copilot have the ability to write code.

Why not use this ability of AI available on the internet to save time?

We will test this idea with a deprecated AngularJS application that I will try to migrate to VueJS throughout this article.

Let’s summarize

AngularJS is an old framework, it will necessarily be present in the data of GPT3.5.
VueJS has also been present for a few years, ChatGPT should be able to transform AngularJS into VueJS.

The goal is simple: migrate this application by writing as little code as possible.

My migration plan

The application that will be used to do the test can be broken down into four major parts:

the components
the views
services (files used to call the API or do stuff with the browser)
the router

My migration plan is as follows:

Condition ChatGPT with the first prompt to be a JavaScript expert with strong knowledge of AngularJS and VueJS
Init a new VueJS app
Migrate components
Migrate services
Migrate views
Migrate router
Add application custom style

AI conditioning

I've conditioned my ChatGPT chat with this first prompt :

You are a senior Javascript frontend developper with strong skills in AngularJS and VueJS frameworks.
I need you today to help me migrate an AngularJS application to VueJS
My next messages will be parts of the AngularJS application to migrate.

This will help to have relevant results when migrating parts of our application.

Init the VueJS app

The simplest part of the project, we use the Vue CLI to create a new project that will be the target project of the migration.

~/Workspace/angularjs-to-vue3-project 
❯ npm create vue@latest
Need to install the following packages:
  create-vue@3.7.5
Ok to proceed? (y) 

Vue.js - The Progressive JavaScript Framework

✔ Project name: … frontend-target-app
✔ Add TypeScript? … No / Yes
✔ Add JSX Support? … No / Yes
✔ Add Vue Router for Single Page Application development? … No / Yes
✔ Add Pinia for state management? … No / Yes
✔ Add Vitest for Unit Testing? … No / Yes
✔ Add an End-to-End Testing Solution? › No
✔ Add ESLint for code quality? … No / Yes
✔ Add Prettier for code formatting? … No / Yes

Scaffolding project in /home/user/Workspace/angularjs-to-vue3-project/frontend-target-app...

Done. Now run:

  cd frontend-target-app
  npm install
  npm run format
  npm run dev

Migrate a component

The AI is now ready, let's try to migrate our first component.

Request

The rest of my message contains the JavaScript code and the html of the AngularJS component

import template from "./sign-form.template.html?raw";

function controller($scope) {
  this.$onInit = () => {
    this.bgImg = {
      "background-image": `url(${this.img})`,
    };
    this.username = "";
    this.password = "";
  };

  this.clearForm = () => {
    this.username = "";
    this.password = "";
  };

  this.handleSubmit = () => {
    $scope.$emit("signSubmited", {
      username: this.username,
      password: this.password,
    });
    this.clearForm();
  };
}

const component = {
  template,
  controller,
  bindings: {
    formTitle: "@",
    btnLabel: "@",
    img: "@",
  },
  transclude: {
    slot: "?slot",
  },
};

component.$inject = ["$scope"];

export default ["signForm", component];

<article class="grid">
  <div>
    <h2>{{$ctrl.formTitle}}</h2>
    <form ng-submit="$ctrl.handleSubmit()">
      <label htmlfor="username">
        Username
        <input type="text" id="username" ng-model="$ctrl.username" required />
      </label>
      <label htmlfor="password">
        Password
        <input type="password" id="password" ng-model="$ctrl.password" required />
      </label>
      <button class="contrast">{{$ctrl.btnLabel}}</button>
      <div ng-transclude="slot"></div>
    </form>
  </div>
  <div class="sign-img" ng-style="$ctrl.bgImg"></div>
</article>

Result

Now let’s see what ChatGPT generated in response.

<template>
  <article class="grid">
    <div>
      <h2>{{ formTitle }}</h2>
      <form @submit.prevent="handleSubmit">
        <label for="username">
          Username
          <input v-model="username" type="text" id="username" required />
        </label>
        <label for="password">
          Password
          <input v-model="password" type="password" id="password" required />
        </label>
        <button class="contrast">{{ btnLabel }}</button>
        <div v-if="$slots.slot"><slot name="slot"></slot></div>
      </form>
    </div>
    <div class="sign-img" :style="bgImg"></div>
  </article>
</template>

<script>
export default {
  props: {
    formTitle: String,
    btnLabel: String,
    img: String,
  },
  data() {
    return {
      username: "",
      password: "",
    };
  },
  computed: {
    bgImg() {
      return {
        "background-image": `url(${this.img})`,
      };
    },
  },
  methods: {
    handleSubmit() {
      this.$emit("signSubmited", {
        username: this.username,
        password: this.password,
      });
      this.clearForm();
    },
    clearForm() {
      this.username = "";
      this.password = "";
    },
  },
};
</script>

<style scoped>
/* Add your component-specific styles here */
</style>

And the explanations :

The result looks great, we now have a component translated into VueJS !

Let's do it with other components.

Migrate a service

After successfully migrating all our components, we can move to the service layer.

Request

As for the previous part, the rest of my message contains the JavaScript code of the service.

function accountService($cookies) {
  this.authenticate = (username: string, password: string) => {
    return fetch("http://localhost:8080/signin", {
      method: "POST",
      headers: {
        Accept: "text/plain",
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        username,
        password,
      }),
    })
      .then((response) => {
        return response.text();
      })
      .then((token) => {
        $cookies.put("auth-token", token);
      });
  };

  this.register = (username: string, password: string) => {
    return fetch("http://localhost:8080/signup", {
      method: "POST",
      headers: {
        Accept: "text/plain",
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        username,
        password,
      }),
    });
  };

  this.getToken = () => {
    return $cookies.get("auth-token");
  };

  this.isAuthenticated = () => {
    const token = this.getToken();
    return token?.length;
  };

  this.getUsername = () => {
    const token = this.getToken();
    const [user] = atob(token).split(":");
    return user;
  };

  this.logout = () => {
    $cookies.remove("auth-token");
  };
}

export default ["accountService", accountService];

Response

As for the components, ChatGPT generates a migrated version of our service.

import axios from 'axios'

export default {
  authenticate(username, password) {
    return axios
      .post('http://localhost:8080/signin', {
        username,
        password
      })
      .then((response) => {
        const token = response.data
        this.setToken(token)
      })
  },

  register(username, password) {
    return axios.post('http://localhost:8080/signup', {
      username,
      password
    })
  },

  setToken(token) {
    localStorage.setItem('auth-token', token)
  },

  getToken() {
    return localStorage.getItem('auth-token')
  },

  isAuthenticated() {
    const token = this.getToken()
    return token && token.length > 0
  },

  getUsername() {
    const token = this.getToken()
    if (token) {
      const user = atob(token).split(':')[0]
      return user
    }
    return null
  },

  logout() {
    localStorage.removeItem('auth-token')
  }
}

This part can be the simplest in some applications, especially if the service layer is written in pure Javascript, no need for migration in this case.

Migrate a view

We apply the same process again. We ask ChatGPT to migrate the view by providing JS code and HTML.

Do not forget to tell the AI to use the components and services generated previously.

Request

Migrate the signin view that use the SignForm.vue component created before :

function signInController($scope, $window, accountService) {
  function authenticate(event, data) {
    accountService.authenticate(data.username, data.password).then(() => {
      $window.location.href = "#/home";
    });
  }

  $scope.$on("signSubmited", authenticate);
}

signInController.$inject = ["$scope", "$window", "accountService"];

export default ["signInController", signInController];

<honk-layout>
  <slot-main>
    <sign-form
      form-title="Sign in"
      btn-label="Login"
      img="https://source.unsplash.com/uymG7UVPXpI/1000x1200"
      username="{{$scope.username}}"
      password="{{$scope.password}}"
    >
      <slot>
        <p class="sign-option">
          Don't have an account yet?
          <a href="#/signup">Register now</a>
        </p>
      </slot>
    </sign-form>
  </slot-main>
</honk-layout>

Response

Here's the Vue.js version of the signin view that uses the SignForm component:

<template>
    <HonkLayout>
        <template #main>
        <SignForm
            formTitle="Sign in"
            btnLabel="Login"
            :img="img"
            :username="username"
            :password="password"
            @signSubmited="authenticate"
        >
            <template v-slot:slot>
            <p class="sign-option">
                Don't have an account yet?
                <a href="#/signup">Register now</a>
            </p>
            </template>
        </SignForm>
        </template>
    </HonkLayout>
</template>

<script>
import HonkLayout from '../components/HonkLayout.vue'; // Import the HonkLayout component
import SignForm from '../components/SignForm.vue'; // Import the SignForm component
import accountService from '../services/account.service'; // Import the accountService

export default {
components: {
    HonkLayout,
    SignForm,
},
data() {
    return {
    img: 'https://source.unsplash.com/uymG7UVPXpI/1000x1200',
    username: '',
    password: '',
    };
},
methods: {
    authenticate(data) {
        const { username, password } = data;
        accountService.authenticate(username, password)
        .then(() => {
            // Redirect to the home page after successful authentication
            this.$router.push('/home');
        });
    },
},
};
</script>

<style scoped>
/* Add your component-specific styles here */
</style>

The generated VueJS component looks correct. Let’s repeat the action for the other views to finish this part.

Migrate the router

The router is a rather special part, it is the file that will manage the "UI" routes of our Single Page Application (SPA).

As for writing components this part will differ depending on the framework used.

Request

After seeing it I think you understood it, we will once again ask ChatGPT to migrate the router by providing the code 😅.

Now write the vue router from the angularjs one

function config($routeProvider, $locationProvider) {
  $locationProvider.hashPrefix("");
  $routeProvider
    .when("/", {
        template: signInTemplate,
        controller: "signInController",
        name: "signin",
    })
    .when("/home", {
      template: homeTemplate,
      controller: "homeController",
      name: "home",
    })
    .when("/signup", {
      template: signUpTemplate,
      controller: "signUpController",
      name: "signup",
    });
}

config.$inject = ["$routeProvider", "$locationProvider"];

export default config;

Response

In my case, ChatGPT was able to generate me an equivalent router in VueJS that works perfectly.

To create a Vue Router configuration based on the AngularJS route configuration you provided, you can define routes and use Vue Router for navigation. Here's the equivalent Vue Router configuration:

import { createRouter, createWebHashHistory } from 'vue-router'
import HomeView from '../views/HomeView.vue'
import SignInView from '../views/SignInView.vue'
import SignUpView from '../views/SignUpView.vue'

const router = createRouter({
  history: createWebHashHistory(),
  routes: [
    {
      path: '/',
      component: SignInView
    },
    {
      path: '/home',
      component: HomeView
    },
    {
      path: '/signup',
      component: SignUpView
    }
  ]
})

export default router

We now have our, components, views, services and router, all that’s missing is the migration of our app style!

Add application style

Now that all the application code is migrated, we can copy the CSS part.

Copy the app.scss from the AngularJS app to the assets Vue app directory.

Add sass dependencies in the project.

npm install --save-dev sass-loader sass

Finally, add the style import in the main.ts file of the application.

import '/posts/app.scss'

The new app is ready, we can proceed to the test.

Let's run the new app

In the case of our test app, we get exactly the same rendering with the new app! 🎉

Let’s look at each screen before and after migration.

Sign in form

AngularJS

VueJS

Sign up form

AngularJS

VueJS

Home page

AngularJS

VueJS

Facts !

Looking at the captures, one would think I just used the same image for both cases. Let’s see what the DOM says.

AngularJS

The application written in AngularJS has the ng-app attribute.

VueJS

The application written in VueJS has the data-v-app attribute.

Help, the code written by the AI is wrong! 😱

Do not hesitate to correct it when answers are wrong or if they are missing parts.

Example :

On the first migration code, the ChatGPT solution was not using the signSubmited event data.

Legacy code :

function authenticate(event, data) {
    accountService.authenticate(data.username, data.password).then(() => {
        $window.location.href = "#/home";
    });
}

$scope.$on("signSubmited", authenticate);

First wrong proposition :

authenticate() {
    accountService.authenticate(this.username, this.password)
    .then(() => {
        this.$router.push('/home');
    });
}

After that, i've say to ChatGPT that he is not using the event data :

you are not using the username and password sent in the signSubmited event

Then he correct it immediately !

You're correct; I apologize for the oversight. To use the username and password sent in the signSubmited event, you should update the authenticate method to receive the data object passed through the event. Here's the corrected signin Vue.js component:

authenticate(data) {
    const { username, password } = data;
    accountService.authenticate(username, password)
    .then(() => {
        this.$router.push('/home');
    });
}

Conclusion

I found the result of this migration test very interesting.

It took me less than two hours to fully migrate my test application.

Regarding the AI part, it is important to keep the same conversation throughout the migration to keep the same context.
This will facilitate the work of the AI when requesting changes to the generated code.

When the AI is wrong or forgets to migrate certain portions, it is important to correct it to keep a correct context.

Project link

https://gitlab.com/ziggornif/angularjs-to-vue3-project

Hexagonal architecture as a solution to the obsolescence of UI frameworks

Matthieu Drouian — Mon, 07 Nov 2022 13:18:41 +0000

Since the arrival of frontend frameworks and the advent of SPA (Single Page Application) type applications, the volatility of the frontend ecosystem and the adherence to frameworks make it difficult to produce robust and durable applications today.

The objective of this article is to show how the application of hexagonal architecture on the frontend can address this issue.

Presentation

Matthieu

Software architect and backend developer, I mostly develop in Java, JS and Go. Right now, I am starting to dabble in Rust.

I love everything about CI/CD (Gitlab 🦊 ❤️), imagining and creating robust, high-performance, and resource-efficient applications.

I share my insights and discoveries through blog posts.

When I'm not in my office tinkering with my 3D printer, you can find me on the water 🛶 !

Twitter
GitHub
Linkedin

Sebastián

Software architect and backend developer.

Former C# developer, until I got seduced by open source and NodeJS. I love Rust (but I am not yet sure that it's mutual 😅).

Linux ❤️ is my co-pilot. Like Matthew, I am a CI/CD enthusiast (Gitlab 🦊 gang), I like to optimize/automate anything that is optimizable/automatable.

I do more monitoring than I should, or maybe it's just that the day isn't long enough.

If you speak "un poquito de español", feel free to talk to me in the language of Cervantes 🙂

GitHub
Linkedin

Acknowledgements

We want to thank Simon Duhem for his help on the styling part and the web components.

Thanks also to Julien Topçu who advised us on the hexagonal architecture part and who answered our questions all along the project.

And thanks to Dawson Brown for helping us with the english translation.

Observations

Today most frontend applications are produced using frameworks.

The three main frameworks on the market are React, VueJS and Angular.

UI frameworks allow for faster application development. They natively manage the reactivity as well as the compatibility of applications with different browsers.

Issues

All the code dedicated to frontend business logic will generally also be linked to the functioning of the framework.

When a framework becomes deprecated, the whole application must be rewritten in a new framework.

Focus on AngularJS

2009: Google releases the first version of AngularJS.

The framework is going to become very popular, and many developers are going to build their SPA using this framework.

2018 : The team announces the end of the development of the framework and an end of maintenance on December 31, 2021 (https://blog.angular.io/stable-angularjs-and-long-term-support-7e077635ee9c).

Following this announcement, the teams in charge of maintaining angularjs apps were faced with a choice of how to maintain their apps:

Migrate from AngularJS to Angular?
Rewrite the application to use another framework?
Keep their legacy code and cross their fingers that no one finds a flaw?

The chosen solution will most likely involve a more or less complex rewriting of the code, including the front-end business logic of the application.

How to avoid it?

To avoid falling into this kind of trap, you need to try to decouple the frontend business logic from the UI / Framework part.

The idea is simple: build an application where on one side the framework is only in charge of html rendering and the reactivity of the components and on the other side the frontend business logic is isolated in agnostic code.

Advantages :

The code associated with the framework is isolated
Our business code becomes sustainable because it is agnostic

On paper the idea seems simple, but how to implement this division?

Hexagonal architecture for the front end

Hexagonal architecture is an architecture pattern created by Alistair Cockburn that places the business layer at the centre of the application (the hexagon) while ensuring a loose coupling with the technical blocks.

Basic concepts:

The business domain is agnostic and has no dependencies.
The tightness of the business domain is guaranteed by the port system.
The layers (adapters) gravitating around the hexagon must respect the interfaces defined in the ports to communicate with the domain.

To go deeper into hexagonal architecture, see the resources in the links section.

Here is an example of frontend application breakdown using the hexagonal architecture:

Starting project

The different steps to follow will be based on the migration of a legacy AngularJS app to a hexagonal model.

https://gitlab.com/thekitchen/frontend-legacy-app

This application is a simplified Twitter server that contains the following features:

authentication
account creation
creation of tweets
display of tweets
likes

It has been built in AngularJS to be an application built with a deprecated framework.

Goal

The goal of the article is to show step by step how to start from a legacy project and get to a hexagonal architecture that will allow us to easily change the framework of our application.

It will not be a magic recipe applicable to all applications but rather the steps of the migration process that we have undertaken during our research.

Organization of the new project

A project of this type needs some technical prerequisites to allow a trouble free development, in addition to providing a strict isolation of the technical blocks associated with the domain.

To focus purely on the code, and not on the tooling, we feel that the use of a monorepo is a must.

Obviously, the choice of a package management tool is secondary. On our side we have chosen pnpm + turborepo (if the need arises).

The hierarchy of the monorepo will be as follows:

.
├── package.json
├── pnpm-lock.yaml
├── pnpm-workspace.yaml
├── apps
│   ├── angular-app
│   ├── angularjs-app
│   ├── backend-api
│   ├── react-app
│   └── vue-app
├── configs
│   ├── eslint-config-hexademo
│   └── tsconfig
├── e2e
│   ├── package.json
│   └── tests
├── packages
│   ├── adapters
│   ├── domain
│   ├── loader
│   ├── style
│   └── web-components

The purpose and implementation of each file will be explained as the article progresses.

Identify your business requirements

The business requirements of our application is composed of two parts:

Account management
Tweet management

For the account part, the application enables:

Account creation
User authentication
Logging out
Knowing if the user is authenticated
Getting the jwt of the authenticated user
Getting the name of the authenticated user

For the tweets part, the application enables:

Creation of tweets
Retrieving tweets
Liking tweets

Domain - API interfaces creation

Once our business requirements have been identified, we can now write our domain interfaces.

The API layer contains all the interfaces allowing communication with the business layer.

This layer is defined by the domain to guarantee its integrity.

Account API

Here is the API created from the account business logic layer described above

ports/api/account.ts

interface IAccountAPI {
    authenticate(username: string, password: string): Promise<string>;
    isAuthenticated(): boolean;
    logout(): Promise<void>;
    register(username: string, password: string): Promise<Registration>;
    getToken(): string;
    getUsername(): string;
}

export type { IAccountAPI };

Tweet API

And here is the API created from the business logic layer for tweets

ports/api/twitter.ts

interface ITwitterAPI {
    tweet(message: string): Promise<Tweet>;
    like(tweetId: string): Promise<Tweet>;
    listTweets(): Promise<Array<Tweet>>;
}

export type { ITwitterAPI };

Domain - SPI interfaces creation

The SPI (Service Provider Interface) layer contains all the interfaces required and provided by the domain to interact with the data.

It is here that we will define the interfaces allowing the domain to retrieve / create tweets, authenticate etc...

These interfaces will then be implemented by the adapter layer.

ports/spi/iauthentication-adapter.ts

interface IAuthenticationAdapter {
    auth(username: string, password: string): Promise<string>;
    register(username: string, password: string);
}

ports/spi/itweet-adapter.ts

interface ITweetAdapter {
    listTweets(): Promise<Array<Tweet>>;
    createTweet(tweet: Tweet): Promise<Tweet>;
    likeTweet(tweetId: string): Promise<Tweet>;
}

Domain - Writing the business logic

Now that our API and SPI are coded, we can move on to writing the business logic.

Account logic

For the account part, we have the following business rules to apply:

It is not possible to create an account without a user/password

It is not possible to authenticate with an empty password

The token must be persisted during authentication

account.ts

import { IAccountAPI } from "./ports/api";
import { Registration } from "./types/registration";
import { IAuthenticationAdapter } from "./ports/spi/iauthentication-adapter";
import { ISessionAdapter } from "./ports/spi/isession-adapter";

class Account implements IAccountAPI {
    private authAdapter: IAuthenticationAdapter;

    private sessionAdapter: ISessionAdapter;

    private defaultSessionDuration: number;

    constructor(
        authAdapter: IAuthenticationAdapter,
        sessionAdapter: ISessionAdapter
    ) {
        this.authAdapter = authAdapter;
        this.sessionAdapter = sessionAdapter;
        this.defaultSessionDuration = 120;
    }

    async authenticate(username: string, password: string): Promise<string> {
        this.checkThatUserIsFilled(username);
        this.checkThatPasswordIsFilled(password);

        try {
            const token = await this.authAdapter.auth(username, password);

            this.sessionAdapter.storeValue(
                "auth-token",
                token,
                this.defaultSessionDuration
            );

            return token;
        } catch (error) {
            throw new Error(
                "Something went wrong during the authentication. Check your username and password."
            );
        }
    }

    async register(username: string, password: string): Promise<Registration> {
        this.checkThatUserIsFilled(username);
        this.checkThatPasswordIsFilled(password);

        try {
            await this.authAdapter.register(username, password);
            return {
                username,
                status: "CREATED",
            };
        } catch (error) {
            return {
                username,
                status: "ERROR",
            };
        }
    }

    async logout(): Promise<void> {
        this.sessionAdapter.flush();
    }

    getToken(): string {
        const token = this.sessionAdapter.getValue("auth-token");
        if (!token) {
            throw new Error("Token not found");
        }

        return token;
    }

    getUsername(): string {
        const token = this.getToken();
        const [user] = atob(token).split(":");
        if (!user) {
            throw new Error("Invalid token format");
        }
        return user;
    }

    isAuthenticated(): boolean {
        try {
            const token = this.getToken();
            if (token.length) {
                return true;
            }
            return false;
        } catch (error) {
            return false;
        }
    }

    checkThatUserIsFilled(username: string) {
        if (!username.length) {
            throw new Error("Username could not be empty");
        }
    }

    checkThatPasswordIsFilled(password: string) {
        if (!password.length) {
            throw new Error("Password could not be empty");
        }
    }
}

export { Account };

Tweets logic

For tweets, we have the following business rules to apply when creating a tweet:

It is not possible to create an empty tweet

It is not possible to create a tweet without an author

A tweet must not be longer than 144 characters

To start with, we will create a Tweet type with the attributes required by our front-end domain.

⚠️ This type does not have to match the format returned by our backend.
It is the representation of the business entity from our frontend.

types/tweet.ts

type Tweet = {
    id?: string;
    author: string;
    message: string;
    likes?: number;
    createdAt?: string;
};

export type { Tweet };

We can then move on to our business rules:

twitter.ts

import { Tweet } from "./types/tweet";
import { ITweetAdapter } from "./ports/spi/itweet-adapter";
import { IAccountAPI, ITwitterAPI } from "./ports/api";
import { ITweetDispatcher } from "./ports/spi/itweet-dispatcher";

class Twitter implements ITwitterAPI {
    accountAPI: IAccountAPI;

    tweetAdapter: ITweetAdapter;

    tweetDispatcher: ITweetDispatcher;

    constructor(
        accountAPI: IAccountAPI,
        tweetAdapter: ITweetAdapter,
        tweetDispatcher: ITweetDispatcher
    ) {
        this.accountAPI = accountAPI;
        this.tweetAdapter = tweetAdapter;
        this.tweetDispatcher = tweetDispatcher;
    }

    async listTweets(): Promise<Tweet[]> {
        const tweets = await this.tweetAdapter.listTweets();
        return tweets.reverse();
    }

    async tweet(message: string): Promise<Tweet> {
        this.#checkThatMessageIsFilled(message);
        this.#checkTweetLength(message);

        const author = this.accountAPI.getUsername();
        this.#checkThatAutorIsFilled(author);

        const tweet = await this.tweetAdapter.createTweet({ message, author });
        this.tweetDispatcher.emitTweetCreated(tweet);
        return tweet;
    }

    like(tweetId: string): Promise<Tweet> {
        return this.tweetAdapter.likeTweet(tweetId);
    }

    #checkThatMessageIsFilled(message: string) {
        if (!message.length) {
            throw new Error("Message could not be empty");
        }
    }

    #checkThatAutorIsFilled(author: string) {
        if (!author.length) {
            throw new Error("Author could not be empty");
        }
    }

    #checkTweetLength(message: string) {
        if (message.length > 144) {
            throw new Error("Message length must be lower than 144 characters");
        }
    }
}

export { Twitter };

Domain - setting up the stubs

To test the business code of our domain without needing to deploy the associated backend, we will set up adapter stubs that we will inject in place of the real adapters.

A stub is a technique used to isolate a portion of code in order to make it autonomous. In our case the stubs will be in-memory implementations which will return dummy data.

Some important points to know in our case:

the stubs must implement the SPI interfaces and thus respect the method signatures
to guarantee the integrity of the domain, the stubs are created in the domain
a good stub must return the necessary data sets to test all the business cases

In our project, we have placed the stubs in a stubs directory next to the SPI interfaces.

https://gitlab.com/thekitchen/frontend-hexagonal-demo/-/tree/main/packages/domain/src/ports/spi/stubs

ports/spi/stubs/authentication-inmem-adapter.ts

import { IAuthenticationAdapter } from "../iauthentication-adapter";

class AuthenticationInMemAdapter implements IAuthenticationAdapter {
    users;

    constructor() {
        this.users = [
            {
                username: "unicorn",
                password: "rainbow",
            },
        ];
    }

    async auth(username: string, password: string): Promise<string> {
        const found = this.users.find((user) => user.username === username);
        if (!found || found.password !== password) {
            throw new Error("Bad credentials");
        }
        return btoa(`${username}:${password}`);
    }

    async register(username: string, password: string) {
        const found = this.users.find((user) => user.username === username);
        if (found) {
            throw new Error("User already exists");
        }
        this.users.push({
            username,
            password,
        });
    }
}

export { AuthenticationInMemAdapter };

ports/spi/stubs/tweet-inmem-adapter.ts

import { nanoid } from "nanoid";
import { Tweet } from "../../../types/tweet";
import { ITweetAdapter } from "../itweet-adapter";

class TweetInMemAdapter implements ITweetAdapter {
    tweets: Tweet[];

    constructor() {
        this.tweets = [];
    }

    async listTweets(): Promise<Tweet[]> {
        return this.tweets;
    }

    async createTweet(tweet: Tweet): Promise<Tweet> {
        const tweetToCreate: Tweet = {
            id: nanoid(10),
            createdAt: new Intl.DateTimeFormat("fr-FR", {
                weekday: "short",
                year: "numeric",
                month: "short",
                day: "numeric",
                hour: "2-digit",
                minute: "2-digit",
                second: "2-digit",
            }).format(new Date()),
            likes: 0,
            ...tweet,
        };
        this.tweets.push(tweetToCreate);
        return tweetToCreate;
    }

    async likeTweet(tweetId: string): Promise<Tweet> {
        const tweet = this.tweets.find((t) => t.id === tweetId);
        if (!tweet) throw new Error(`Tweet ${tweetId} not found`);

        if (!tweet.likes) {
            tweet.likes = 0;
        }
        tweet.likes += 1;

        return tweet;
    }
}

export { TweetInMemAdapter };

Test your business logic domain

Now that we have stubs, we can easily test our business domain.

Unlike normal front-end testing, thanks to the hexagonal division we will be able to test the business rules of our domain rather than mounting UI components to test their behavior.

⚠️ : we don't mean to say that component tests are useless but rather that this division allows us to perform new types of tests on our front-end application.
Since our business is decoupled from the framework, we can easily test our business rules directly.

Business tests examples:

Twitter class instantiation with stub adapters:

const twitter = new Twitter(new TweetInMemAdapter());

Test of the rule on the number of characters:

test("should throw error if new tweet message is longer than 144 chars", async () => {
    await expect(() => twitter.tweet(new Array(160).join("x"))).rejects.toThrow(
        "Message length must be lower than 144 characters"
    );
});

Test of “like” of a tweet:

test("should like a tweet", async () => {
    const tweet = await twitter.tweet("Hi !");
    expect(tweet).toHaveProperty("id");
    expect(tweet).toHaveProperty("likes", 0);

    const updated = await twitter.like(tweet.id as string);
    expect(updated).toHaveProperty("likes", 1);
});

You can find all the application's test files next to the source code files *.spec.ts : https://gitlab.com/thekitchen/frontend-hexagonal-demo/-/tree/main/packages/domain/src

Writing adapters

Now that our business code is written and tested, we can proceed to the implementation of the adapter layer.

The adapter layer of our hexagon is where the SPI type interfaces are implemented.

This layer will be responsible for interacting with the data, usually through API calls (REST, GraphQL, etc...) for frontend applications.

In our case, the adapter layer will be responsible for calls to our backend which exposes a REST API.

As for the business logic, we split it into two adapters. One responsible for calling the accounts API, the other for calling the tweets API.

As seen above in the SPI section, these adapters must implement the interfaces defined in the domain SPI layer.

Here are our adapters used to communicate with our REST API:

authentication-rest-adapter.ts

import { IAuthenticationAdapter } from "@hexademo/domain";

class AuthenticationRestAdapter implements IAuthenticationAdapter {
    async auth(username: string, password: string): Promise<string> {
        const response = await fetch("http://localhost:8080/signin", {
            method: "POST",
            headers: {
                Accept: "text/plain",
                "Content-Type": "application/json",
            },
            body: JSON.stringify({
                username,
                password,
            }),
        });
        const token = await response.text();
        return token;
    }

    async register(username: string, password: string) {
        const response = await fetch("http://localhost:8080/signup", {
            method: "POST",
            headers: {
                Accept: "application/json",
                "Content-Type": "application/json",
            },
            body: JSON.stringify({
                username,
                password,
            }),
        });
        if (response.status !== 201) {
            throw new Error("Registration error");
        }
    }
}

export { AuthenticationRestAdapter };

tweet-rest-adapter.ts

import type { Tweet, ITweetAdapter } from "@hexademo/domain";

/**
 * Generate output date
 *
 * @param {Date} date input date
 * @returns {string} output
 */
function formatDate(date: Date): string {
    return new Intl.DateTimeFormat("fr-FR", {
        weekday: "short",
        year: "numeric",
        month: "short",
        day: "numeric",
        hour: "2-digit",
        minute: "2-digit",
        second: "2-digit",
    }).format(date);
}
class TweetRestAdapter implements ITweetAdapter {
    async listTweets(): Promise<Tweet[]> {
        const response = await fetch("http://localhost:8080/tweets");
        const jsonResp = await response.json();
        const tweets: Array<Tweet> = [];
        for (const tweet of jsonResp) {
            tweets.push({
                id: tweet.id,
                message: tweet.message,
                author: tweet.author,
                createdAt: formatDate(new Date(tweet.created_at)),
                likes: tweet.likes,
            });
        }
        return tweets;
    }

    async createTweet(tweet: Tweet): Promise<Tweet> {
        const response = await fetch("http://localhost:8080/tweets", {
            method: "POST",
            headers: {
                Accept: "application/json",
                "Content-Type": "application/json",
            },
            body: JSON.stringify({
                message: tweet.message,
                author: tweet.author,
            }),
        });

        const jsonResp = await response.json();

        return {
            id: jsonResp.id,
            message: jsonResp.message,
            author: jsonResp.author,
            createdAt: formatDate(new Date(jsonResp.created_at)),
            likes: jsonResp.likes,
        };
    }

    async likeTweet(tweetId: string): Promise<Tweet> {
        const response = await fetch(
            `http://localhost:8080/tweets/${tweetId}/like-tweet`,
            {
                method: "POST",
                headers: {
                    Accept: "application/json",
                    "Content-Type": "application/json",
                },
            }
        );
        const jsonResp = await response.json();
        return {
            id: jsonResp.id,
            message: jsonResp.message,
            author: jsonResp.author,
            createdAt: formatDate(new Date(jsonResp.created_at)),
            likes: jsonResp.likes,
        };
    }
}

export { TweetRestAdapter };

The advantage of this technique is that it guarantees the scalability of the communication layer with our backend.

If in the future we want to use a GraphQL API or even another external API to retrieve the data. We'll just have to create a new adapter for the new requirement.

The key is that it is the domain that determines the interface contract (inputs and outputs) and that the adapter layer respects this contract.

Hexagon loading

To instantiate the hexagon, we need to connect the adapters to the SPI ports of the domain.

From a technical point of view, we need to inject the dependencies (adapters) via the existing constructors in our domain layer.

To facilitate this orchestration, we have chosen to create a utility package called @hexademo/loader. This package takes care of instantiating classes in the right order.

Here is the code of our loader:

packages/loader/index.ts

import {
    AuthenticationInMemAdapter,
    SessionCookieAdapter,
    TweetIndexedDbAdapter,
    TweetEventsDispatcher,
} from "@hexademo/adapters";
import { Account, IAccountAPI, Twitter, ITwitterAPI } from "@hexademo/domain";

namespace AppLoader {
    const sessionAdapter = new SessionCookieAdapter();
    const authenticationAdater = new AuthenticationInMemAdapter();

    // nous avons le choix, en fonction de nos besoins
    // nous pouvons choisir le IndexedDBAdapter, InMemAdapter ou bien RestAdapter
    const tweetAdapter = new TweetIndexedDbAdapter();
    // const tweetAdapter = new TweetInMemAdapter();
    // const tweetAdapter = new TweetRestAdapter();

    const accountServiceAPI = new Account(authenticationAdater, sessionAdapter);
    const twitterServiceAPI = new Twitter(accountServiceAPI, tweetAdapter, tweetEventsDispatcher);

// Les instances API sont exposées, pour une utilisation dans un framework front
    export function getTwitterInstance(): ITwitterAPI {
        return twitterServiceAPI;
    }

💡 ️If the domain becomes complex, the integration of a dependency injection engine would be a wise choice.
We used manual injection (aka poor man's injection) to keep the example simple.

Connecting the domain to the framework

With this structure, our hexagon can be integrated from any client, whether it is coded in vanilla JS or using a front-end framework from the market.

To better show the flexibility of the domain, we have created 4 applications using the most widely used frameworks on the market:

AngularJS (example based on our initial legacy application, but framework still widely used in production)
VueJS
Angular
React

The package @hexademo/loader is simply to expose an instance of the domain.

Since each framework may have its own way of injecting its variables/dependencies, the responsibility of the loader stops here.

Depending on the framework used, you will have to consult the corresponding documentation to inject the domain.

React application example

Loading the domain instances using the loader in our App.tsx.

import { AppLoader } from "@hexademo/loader";

const twitterAPI = AppLoader.getTwitterInstance();
const accountAPI = AppLoader.getAccountInstance();

We then pass the instances to the components that will call the domain layer.

<HomeView accountAPI={accountInstance} twitterAPI={twitterInstance} />

The component can thus use the methods of the domain.

type HomeViewProps = {
    twitterAPI: ITwitterAPI;
    accountAPI: IAccountAPI;
};

function HomeView(props: HomeViewProps) {
    /**
     * Get tweets
     *
     * @returns {Promise<void>}
     */
    async function listTweets() {
        const resp = await props.twitterAPI.listTweets();
        await setTweets(resp);
    }
}

VueJS application example

Declaration of the domain by using injection keys.
Injection of the domain instance.
Call to the domain within a component.

And the injection into our legacy AngularJS application?

The beauty of this breakdown is that we can even make it work with our old legacy AngularJS application!

First of all we get the domain instances via the loader as we did for the React application.

This time we use the angularjs constants to make the instances accessible through our application.

import angular from "angular";
import { AppLoader } from "@hexademo/loader";

const accountAPI = AppLoader.getAccountInstance();
const twitterAPI = AppLoader.getTwitterInstance();

// Pour une meilleur organisation, le domain est déclaré dans un module angularjs indépendant.
export default angular
    .module("domain", [])
    .constant("accountAPI", accountAPI)
    .constant("twitterAPI", twitterAPI).name;

import angular from "angular";
import domain from "@/modules/domain/domain.module";

// le domain est une dependance du module "myApp"
// "myApp" aura accès à toutes les instances du domain
angular.module("myApp", [domain]);

This way the domain instances can be injected on demand

class HomeController implements IHomeController {
    tweets: Tweet[] = [];

    constructor(private twitterAPI: ITwitterAPI) {}

    async getTweets() {
        const tweets = await this.twitterAPI.listTweets();
    }
}

To summarize, even if each technology/framework implements its own way of injecting its dependencies, the loader and the hexagon remain independent bricks, with no link to the library or framework used in the application.

How to use a business domain from within another business domain?

Simply by declaring the dependency in the domain constructor using the API in question.

Use case: I want to use my account domain in the twitter domain to retrieve the name of the connected user.

We declare the API account in the constructor of the Twitter class


class Twitter implements ITwitterAPI {
    accountAPI: IAccountAPI;

    tweetAdapter: ITweetAdapter;

    constructor(
        accountAPI: IAccountAPI,
        tweetAdapter: ITweetAdapter,
    ) {
        this.accountAPI = accountAPI;
        this.tweetAdapter = tweetAdapter;
    }

Once declared, I can use it in the code of the class.

async tweet(message: string): Promise<Tweet> {
    this.#checkThatMessageIsFilled(message);
    this.#checkTweetLength(message);

    const author = this.accountAPI.getUsername();
    this.#checkThatAutorIsFilled(author);

    const tweet = await this.tweetAdapter.createTweet({ message, author });
    return tweet;
}

How to manage business events?

Some application events make sense to be taken out of the framework layer and integrated into the business domain layer.

In our case we identified the tweet-created event as a good candidate to experiment with.

To do this we will add a new dispatcher type adapter (adapter in charge of sending messages, events ...).

In our case, we will use the custom events natively supported in the browser to send our events.

import { ITweetDispatcher, Tweet } from "@hexademo/domain";

class TweetEventsDispatcher implements ITweetDispatcher {
    emitTweetCreated(tweet: Tweet): void {
        const event = new CustomEvent("tweetCreated", {
            detail: tweet,
        });
        document.dispatchEvent(event);
    }
}

export { TweetEventsDispatcher };

Then we will add it to our Twitter business class:

class Twitter implements ITwitterAPI {
    accountAPI: IAccountAPI;

    tweetAdapter: ITweetAdapter;

    tweetDispatcher: ITweetDispatcher;

    constructor(
        accountAPI: IAccountAPI,
        tweetAdapter: ITweetAdapter,
        tweetDispatcher: ITweetDispatcher
    ) {
        this.accountAPI = accountAPI;
        this.tweetAdapter = tweetAdapter;
        this.tweetDispatcher = tweetDispatcher;
    }
    ...

Now we can use it in the tweet() method:

async tweet(message: string): Promise<Tweet> {
    this.#checkThatMessageIsFilled(message);
    this.#checkTweetLength(message);

    ...

    const tweet = await this.tweetAdapter.createTweet({ message, author });

    // Event broadcasting
    this.tweetDispatcher.emitTweetCreated(tweet);

    return tweet;
}

And consume it from node code on the framework side 🙂

// Refresh the list of tweets when a new tweet is created
document.addEventListener("tweetCreated", refresh);

How to manage persistence (session, cookies …) ?

The information that we want to persist on the client side can be vary - sessions, JWT, preferences of the connected user, etc.

For this, we have different techniques at our disposal such as local storage, cookies or more recently the browser's IndexedDB API.

We can consider that it is the role of the business code of our application to manage the data persistence.

Data persistence will be the responsibility of the adapter layer.

For this, like for data consumption, we will create an SPI that we will name ISessionAdapter.

This interface will be used to define the session methods.

In our case, the interface is the following:

interface ISessionAdapter {
    storeValue(key: string, value: string, duration: number): void;
    getValue(key: string): string;
    flush(): void;
}

export type { ISessionAdapter };

We can now implement this interface in our adapter layer.

Here is an example of a session implementation with storage in the browser cookies.

session-cookie-adapter.ts

import { ISessionAdapter } from "@hexademo/domain";

class SessionCookieAdapter implements ISessionAdapter {
    storeValue(key: string, value: string, duration: number): void {
        document.cookie = `${key}=${value}; path=/; max-age=${duration}; SameSite=Strict`;
    }

    getValue(key: string): string {
        const value = `; ${document.cookie}`;
        const parts = value.split(`; ${key}=`);
        return parts.pop()?.split(";").shift() as string;
    }

    flush(): void {
        const cookies = document.cookie.split(";");

        for (const cookie of cookies) {
            const eqPos = cookie.indexOf("=");
            const name = eqPos > -1 ? cookie.substring(0, eqPos) : cookie;
            document.cookie = `${name}=;expires=Thu, 01 Jan 1970 00:00:00 GMT`;
        }
    }
}

export { SessionCookieAdapter };

If in the future we want to change to local storage or Indexed DB, we just have to write the corresponding adapter and load it instead of the adapter previously injected in the domain.

Use of web components

After testing the domain agnostic side, and connecting applications written in different frameworks, the realization comes quickly...

**⚠️ However, if in the future I change the framework, my pages will be deprecated too, right ?

That's a very good point, and the answer is a big yes 😕

The goal being to separate the business layer from the technology/framework used and especially to limit the impacts of a framework change, we still have one final hurdle to overcome: the interfaces.

Key interfaces can also be considered as an additional layer of the business.

The solution: use Web components 🪄 (aka custom elements)

Web components, allow you to create standard components, embeddable in any page whether it is made using a framework, or even in vanilla js/html.

For the creation of web components, even though writing in vanilla js is an option,
we have chosen to do it via a dedicated framework, which will solve
many potential integration/bundling problems. The choice of the framework will be made according to
different factors that are not part of the scope of this article.

Here is how a frontend application looks like once the web components are added:

For our application, we have identified the following components as being externalizable as web components:

The login / account creation form
The tweet creation component
The tweet display component

And here are the associated web components:

tweet-sign : login / account registration
tweet-card : display a tweet + like action
tweet-create : input message + create action

End-to-End Tests (E2E) with Playwright

End-to-end tests (or E2E) are designed to test the entirety of our application.

For this project, we decided to use Playwright to perform our tests on various browsers.

Playwright is an E2E testing framework compatible with all operating systems.

It supports Chromium, WebKit and Firefox which allows running tests on all major browsers on the market.

For a detailed presentation, you can watch the excellent video of Grafikart (FR) on the subject: https://www.youtube.com/watch?v=UgF2LwlNnC8

The various options of the framework (browsers, server to launch, screenshot ...) are configurable in the file playwright.config.ts.

E2E test example

For our application, we wrote a simple test case:

An existing user logs into our application
The user posts a tweet
The user likes a tweet
The user logs out

And here is what it looks like in terms of code :

e2e/tests/existing-user.spec.ts

import { test, expect } from "@playwright/test";

test("should login with unicorn account, like, post a message and disconnect", async ({
    page,
}) => {
    // login
    await page.goto("http://localhost:5173");
    await expect(page).toHaveURL("http://localhost:5173/#/signin");
    await page.locator("#username").click();
    await page.locator("#username").fill("unicorn");
    await page.locator("#password").click();
    await page.locator("#password").fill("rainbow");
    await page.locator("text=Login").click();
    await expect(page).toHaveURL("http://localhost:5173/#/home");

    // create a tweet
    await page.locator("#message").click();
    await page.locator("#message").fill("hello world !");
    await page.locator("text=Honk 🚀").click();
    const newTweet = await page.locator(
        "tweet-card:first-of-type .tweet-card__like-button"
    );
    await expect(newTweet).toHaveText("0 ❤️");

    // like a tweet
    const likes = await page.locator(":nth-of-type(3) .tweet-card__like-button");
    await expect(likes).toHaveText("3 ❤️");
    await likes.click();
    await expect(likes).toHaveText("4 ❤️");

    // logout
    await page.locator("text=Logout").click();
    await expect(page).toHaveURL("http://localhost:5173/#/signin");
});

Test report

Once the tests are finished, the command npx playwright show-report allows you to consult the test report.

Example of OK report

In case of errors, it is also possible to view the trace which allows you to see the browser rendering at the time of the error.

Test integration in Gitlab CI

In our case, we have integrated our E2E tests in Gitlab CI to test our different framework implementations.

This pipeline allows us to run the same test suite on our legacy Angularjs application as well as on the Vuejs, React and Angular.

The pipeline code is available here: https://gitlab.com/thekitchen/frontend-hexagonal-demo/-/blob/main/.gitlab-ci.yml

Final project

The completed project is available here: https://gitlab.com/thekitchen/frontend-hexagonal-demo

Conclusion

In conclusion, the realization of this project has allowed us to increase our skills in building and splitting front-end applications.

The implementation of the hexagonal architecture in the frontend allows us to build durable applications whose business code can survive even after the depreciation of a UI framework.

With this division, it is also possible to integrate backend developers in the development of applications on the domain part and to adapt it in the same way as backend Javascript.

And finally, the fact that our application becomes testable without backend and only in memory with the help of stubs has made it easier for us to deploy it for end-to-end testing.

If you have any questions about the code or the project execution, don't hesitate to contact us!

Thanks for your attention 🙇‍♂️.

Matthieu and Sebastian

Monitoring a Node.JS Typescript application with Prometheus and Grafana

Matthieu Drouian — Sun, 16 Oct 2022 13:02:05 +0000

Monitoring consists of observing metrics of your application that will allow you to know its health condition.

There are different observable metrics:

resources consumption (CPU, memory, IO, ...)
network traffic
business metrics (endpoint response time, requests errors, ...)

This post will be dedicated to setting up monitoring on a Node.JS application written in Typescript.

We will set up the business metrics exposure in our application and then we will exploit them with Prometheus and Grafana.

Requirements

You will need an existing Node.JS API project.

If you don't have an existing project, you can follow the next steps with my demo project.

Go to this URL https://gitlab.com/ziggornif/monitoring-article/-/tree/before

Then download the project and install it locally.



cd <project>
npm install

To quickly create the needed grafana and prometheus instances, I will use Docker all along this article

API prometheus metrics

Configuration

First, install the Node.JS Prometheus dependency.



npm add prom-client

Then, import the dependency in your application.



import promClient from 'prom-client';

And create a registry container.



const register = new promClient.Registry();
register.setDefaultLabels({
  app: 'monitoring-article',
});

Add the /metrics endpoint (i use ExpressJS in this example).



app.get('/metrics', async (req: Request, res: Response) => {
  res.setHeader('Content-Type', register.contentType);
  res.send(await register.metrics());
});

We have now a fully configured prometheus client to export our application metrics. Let's collect some data !

Collect API metrics

We will now collect the API endpoints response time and collect :

http code
method (GET, POST, ...)
route URI

Responses time will be stored in milliseconds.

To do that, we need to create an histogram.



const httpRequestTimer = new promClient.Histogram({
  name: 'http_request_duration_ms',
  help: 'Duration of HTTP requests in ms',
  labelNames: ['method', 'route', 'code'],
  // buckets for response time from 0.1ms to 1s
  buckets: [0.1, 5, 15, 50, 100, 200, 300, 400, 500, 1000],
});

Then, use the created historgram on each API endpoint to store the response times.



app.get('/tweets', async (req: Request, res: Response) => {
  const start = Date.now();
  try {
    ...
  } finally {
    const responseTimeInMs = Date.now() - start;
    httpRequestTimer.labels(req.method, req.route.path, res.statusCode.toString()).observe(responseTimeInMs);
  }
});

Now, the endpoint response time will be stored on the prometheus histogram on each call.

Setup Prometheus

Create a prometheus.yml file with the following content to declare the metrics scraper.



global:
  scrape_interval: 5s
scrape_configs:
  - job_name: "monitoring-article"
    static_configs:
      - targets: ["localhost:8080"]

Target configuration for each OS with docker :

Linux: - targets: ["localhost:8080"]
Mac: - targets: ["docker.for.mac.host.internal:8080"]
Windows: - targets: ["docker.for.win.localhost:8080"]

Setup Grafana

Create a datasource.yml file with the following content to set the prometheus datasource.



apiVersion: 1

datasources:
  - name: Prometheus
    type: prometheus
    access: proxy
    orgId: 1
    url: http://localhost:9090
    basicAuth: false
    isDefault: true
    editable: true

URL configuration for each OS with docker :

Linux: url: http://localhost:9090
Mac: url: http://docker.for.mac.host.internal:9090
Windows: url: http://docker.for.win.localhost:9090

Run services

For this demonstration, i will use a docker-compose file to declare my prometheus and grafana instances.

The previously created files have been created in the monitoring folder.



version: "3.3"
services:
  prometheus:
    image: prom/prometheus:latest
    volumes:
      - ./monitoring/:/etc/prometheus/
    ports:
      - 9090:9090
  grafana:
    image: grafana/grafana:latest
    volumes:
      - ./monitoring/datasources.yml:/etc/grafana/provisioning/datasources/datasources.yml
    ports:
      - 3000:3000
    environment:
      - GF_AUTH_DISABLE_LOGIN_FORM=true
      - GF_AUTH_ANONYMOUS_ENABLED=true
      - GF_AUTH_ANONYMOUS_ORG_ROLE=Admin

⚠️ this is a demo config only, do not use this in production

Then run the containers.



docker-compose up -d

We now have a prometheus and a grafana which are running in containers.

Create API Dashboard

💡 If you want to skip the dashboard creation, you can import it from the project sources (the bonus section explains how to import a dashboard).

Dashboard link

90th 95th 99th responses time panel

Let's create the first panel.

Click on the "Add a new panel" button.

Keep the default time series visualization.

Set the panel title on the right side bar.

On the Metrics browser field add the following query to create the 90th percentile response time :



histogram_quantile(0.90, sum(rate(http_request_duration_ms_bucket[1m])) by (le, route, method))

And add on the Legend field :



90th {{method}} {{route}}

Repeat the same operation for the 95th and 99th percentiles.

To do this, click on the "+ Query" button to add metrics.

To finish the configuration, set the Y axis unit to milliseconds in the right side bar (Time > milliseconds).

Then, click on the Apply button.

Repeat the same actions for the next panels.

Average response time

Create a new panel.

Keep the default time series visualization.

On the right side bar, set the panel title and the Y axis unit to milliseconds.

And the following query on the Metrics browser field.



avg(rate(http_request_duration_ms_sum[$__range]) / rate(http_request_duration_ms_count[$__range])) by (route, method)

💡 $__range is a Prometheus supported variable that represent the current dashboard range

And on the Legend field :



{{method}} {{route}}

Requests details

Create a new panel.

Keep the default time series visualization.

On the right side bar, set the panel title and don't touch to the Y axis unit.

Always on the side bar, go to Graph styles section and set style to Bars.

Create three metrics fields which will collect 2xx, 4xx and 5xx requests.

Metrics field :



sum(increase(http_request_duration_ms_count{code=~"2.*"}[1m])) by (route, method)

Label : 2xx {{method}} {{route}}

Metrics field :



sum(increase(http_request_duration_ms_count{code=~"4.*"}[1m])) by (route, method)

Label : 4xx {{method}} {{route}}



sum(increase(http_request_duration_ms_count{code=~"5.*"}[1m])) by (route, method)

Label : 5xx {{method}} {{route}}

Number of requests per minute

Create a new panel.

Keep the default time series visualization.

On the right side bar, set the panel title and don't touch to the Y axis unit.

And the following query on the Metrics browser field.

Metrics field :



sum(increase(http_request_duration_ms_count[1m]))

Label : Requests

Number of failed requests

Create a new panel.

Keep the default time series visualization.

On the right side bar, set the panel title and the graph style to Bars.

Create two metrics fields which will collect 4xx and 5xx requests.

Metrics field :



sum(increase(http_request_duration_ms_count{code=~"4.*"}[1m]))

Label : 4xx errors

Metrics field :



sum(increase(http_request_duration_ms_count{code=~"5.*"}[1m]))

Label : 5xx errors

Number of 200 OK vs Errors

Create a new panel.

Keep the default time series visualization.

On the right side bar, set the panel title and the graph style to Bars.

Create two metrics fields which will collect 200 and error requests.

Metrics field :



sum(increase(http_request_duration_ms_count{code=~"2.*"}[1m]))

code =~"2.*" will collect all results with a 2xx code

Label : Valid requests

Metrics field :



sum(increase(http_request_duration_ms_count{code!~"2.*"}[1m]))

code =~"2.*" will collect all results with a code other than 2xx

Label : Error requests

Load metrics

I have use a Postman Runner to generate some trafic on the application.

The scenario create resources with the POST Endpoint and get resources with the GET Endpoint.

The application endpoints also have a slowdown and error randomizer to test each dashboard panel.

Results

Here some screenshots of the API dashboard results.

Conclusion

Thanks to this dashboard, we can now monitor the following metrics:

The 90th 95th and 99th percentiles of the application endpoints
The average response time of the endpoints
The requests details (number of 2xx, 4xx, 5xx)
The number of requests per minute
Comparison of the number of OK requests with the number of KO requests

Bonus : monitoring Node.JS metrics

Add prometheus default metrics

Add the following line to enable Node.JS default metrics collection.



promClient.collectDefaultMetrics({ register });

NodeJS Application Dashboard

Go to the Grafana website to retrieve the Node.JS Application Dashboard

Then import it :

⚠️ Do not forget to select the prometheus source

After the import, you should have a new dashboard called "NodeJS Application Dashboard" that look like this :

This dashboard will provide you with important information such as:

CPU consumption
memory consumption
event-loop lag (very useful for detecting latency on Node.JS applications)

Final project

You can retrieve and fork the complete project from here : https://gitlab.com/ziggornif/monitoring-article

Do not hesitate to use the API dashboard if you need it : https://gitlab.com/ziggornif/monitoring-article/-/blob/main/monitoring/dashboards/api.json

Bonus #2 - other languages versions

Go : https://gitlab.com/ziggornif/go-api-monitoring
Java (Quarkus) : https://gitlab.com/ziggornif/java-api-monitoring

Forem: Matthieu Drouian

🧰 zsh-pkgmanager-switcher - A ZSH JavaScript package manager switcher plugin

Demo

Project link

How to use AI to migrate a legacy AngularJS app to VueJS without writing (a lot of) code

Ask for an AI!

My migration plan

AI conditioning

Init the VueJS app

Migrate a component

Request

Result

Migrate a service

Request

Response

Migrate a view

Request

Response

Migrate the router

Request

Response

Add application style

Let's run the new app

Sign in form

Sign up form

Home page

Facts !

Help, the code written by the AI is wrong! 😱

Conclusion

Project link

Hexagonal architecture as a solution to the obsolescence of UI frameworks

Presentation

Matthieu

Sebastián

Acknowledgements

Observations

Issues

Focus on AngularJS

How to avoid it?

Hexagonal architecture for the front end

Starting project

Goal

Organization of the new project

Identify your business requirements

Domain - API interfaces creation

Account API

Tweet API

Domain - SPI interfaces creation

Domain - Writing the business logic

Account logic

Tweets logic

Domain - setting up the stubs

Test your business logic domain

Writing adapters

Hexagon loading

Connecting the domain to the framework

React application example

VueJS application example

And the injection into our legacy AngularJS application?

How to use a business domain from within another business domain?

How to manage business events?

How to manage persistence (session, cookies …) ?

Use of web components

End-to-End Tests (E2E) with Playwright

E2E test example

Test report

Test integration in Gitlab CI

Final project

Conclusion

Links

Monitoring a Node.JS Typescript application with Prometheus and Grafana

Requirements

API prometheus metrics

Configuration

Collect API metrics

Setup Prometheus

Setup Grafana

Run services

Create API Dashboard

90th 95th 99th responses time panel