DEV Community: Thomas King

Easily create mock data for unit tests 🧪

Thomas King — Thu, 15 Feb 2024 12:37:36 +0000

Whenever you write unit tests, the time comes that you have to mock data. Mocking this data can become tedious in many ways. Either the data gets copied over and over again for each unit test, or there is a file (or multiple files) that will contain all the mock data. If that data's interface (or class) suddenly changes, you will have to update each occurrence. You can use the IDE for most heavy lifting if you're lucky.

With this guide, I will show you a way to easily create mock data for each interface or class you have. It is based on the builder design pattern, which will allow easily created instances that can still be overridden with custom data.

Note: I will be using Jest as testing framework throughout the examples.

As an example, let's start with two interfaces, Pet and Person.



export interface Pet {
  id: string;
  name: string;
}

export interface Person {
  id: string;
  firstName: string;
  lastName: string;
  pets: Pet[];
}

Creating mock data for these interfaces could look like this:



it('Person should have pets', () => {
  const pets: Pet[] = [{
    id: '1',
    name: 'Bella'
  }];

  const person: Person = {
    id: '1',
    firstName: 'John',
    lastName: 'Doe',
    pets,
  }
  expect(person.pets).toHaveLength(1);
});

Seems ok and not too much code, it could even be optimized more e.g., by using a for-loop. But, this is only for 1 unit test. If the Person interface will be used in another unit test (in another file), that same code will have to be recreated. The downsides of manually creating this data:

It is time-consuming
Prone to human errors (e.g., copy-pasting and forgetting to change something)
A large volume of mock data might become unscalable and hard to manage
It might add a lot of bloat to your unit testing code making it less readable

Time to build a PersonBuilder and PetBuilder that will do the heavy lifting for us by providing default mock data. Let's start by creating an abstract Builder class that other builders can extend.



export abstract class Builder<T> {
  private intermediate: Partial<T> = {};

  constructor() {
    this.reset();
  }

  private reset(): void {
    this.intermediate = { ...this.setDefaults() } ;
  }

  abstract setDefaults(): Partial<T>;

  with<K extends keyof T>(property: K, value: T[K]): Builder<T> {
    this.intermediate[property] = value;
    return this;
  }

  build(): T {
    let p: Partial<T> = {};
    for (let key in this.intermediate) {
      p[key] = this.intermediate[key];
    }
    this.reset();
    return p as T;
  }
}

The abstract Builder class contains four methods:

reset: to reset the internal object inside the builder back to the defaults. This is marked as private but can be marked as public as well if you prefer to use it outside your builder.
setDefaults: the abstract method that will be implemented in the child Builders and that will provide the defaults for the object.
with: the method that can provide overrides for your object. Returning this will make these methods chainable. Intellisense will be provided thanks to the K extends keyof T.
build: the method that will provide the final instance.

With this base Builder class, creating child Builder classes becomes easy. All you have to do is extend from Builder with the appropriate generic type and implement the abstract method setDefaults.

Creating a PetBuilder will look like this:



export class PetBuilder extends Builder<Pet> {
  setDefaults(): Pet {
    return { id: '1', name: 'Bella' };
  }
}

The Person interface contains a reference to Pet, so we can use the newly created PetBuilder to create a default pet for us inside the PersonBuilder.



export class PersonBuilder extends Builder<Person> {
  setDefaults(): Person {
    return {
      id: '1',
      firstName: 'John',
      lastName: 'Doe',
      pets: [new PetBuilder().build()],
    };
  }
}

Updating our previous unit test with these builders will look like this:



it('Person should have pets', () => {
  const pets: Pet[] = [new PetBuilder().build()];
  const person: Person = new PersonBuilder().with('pets', pets).build();
  expect(person.pets).toHaveLength(1);
});

We could even make it shorter by just removing the pets variable since the PersonBuilder already provides us with a default pets array containing 1 pet. But since this unit test tests for the presence of pets, we should include it as well.

Using the builder pattern, making overrides becomes easy:



describe('Given a person', () => {
  let builder: PersonBuilder;
  beforeEach(() => {
    builder = new PersonBuilder();
  });
  it('with the first name Tim should have that name', () => {
    const person: Person = builder.with('firstName', 'Tim').build();
    expect(person.firstName).toBe('Tim');
  });

  it('with the first name Thomas should have that name', () => {
    const person: Person = builder.with('firstName', 'Thomas').build();
    expect(person.firstName).toBe('Thomas');
  });

  it('with the last name Doe should have no pets', () => {
    const person: Person = builder.with('lastName', 'Doe').with('pets', []).build();
    expect(person.pets).toHaveLength(0);
  });
});

Note: I know these unit tests make no sense from a testing perspective, but it is purely an example of the builders.

Bonus: adding Faker

Instead of manually having to think of defaults for your interface properties, you could use Faker.



import { faker } from '@faker-js/faker';

export class PetBuilder extends Builder<Pet> {
  setDefaults(): Pet {
    return { 
      id: faker.string.uuid(), 
      name: faker.person.firstName() };
  }
}

export class PersonBuilder extends Builder<Person> {
  setDefaults(): Person {
    return {
      id: faker.string.uuid(),
      firstName: faker.person.firstName(),
      lastName: faker.person.lastName(),
      pets: [new PetBuilder().build()],
    };
  }
}

Using Faker in your unit tests will create randomly generated data, which is nice but during testing, you'll want reproducible results. Luckily Faker provides something precisely for that: faker.seed(123);. Using a seed will provide reproducible results when running your unit tests.

You can add this seed in your global setup or use a beforeAll.

I hope this guide will make your life of mocking data a bit easier. If you have any questions, feel free to reach out!

Which Angular components should you create? 🤔

Thomas King — Wed, 13 Dec 2023 23:00:00 +0000

When creating an Angular application, you probably already chose a UI library to handle the most rudimentary components, such as dropdowns, date pickers, etc. Also, have a look at my other blog post in which I compared several Angular UI libraries here.
Now, apart from all these components that are offered by a library, what are some components you can create in your web application? Let's go over a (non-exhaustive) list of possible components.

Tip: It is highly recommended to keep your component template small. That's why it's better to split it up into several (tiny) components.

List

Often, you'll end up having to display a list of something. Then it's obvious you create a list component for it. Next to the list component, you can further split this up into smaller components:

list item: create a list item component that you can reuse in your @for (or ngFor) of the parent list component. It will make the template of your list component a lot smaller and more readable. You can also create different types of list item components, depending on the needs, e.g., a list item for multimedia content and one for more textual content.
empty list: create a component that acts as a placeholder when the list component has no items.

Note: With a list component, I don't necessarily mean a generic one. E.g., for a list of products, you can create a product-list component.

Cards

You can do the same with cards as you do with lists. Create a cards component, further split up with the following:

card item
empty cards

The UI library often provides a card component that you can use in your cards component (or, a level below, in the card item).

Table

A table is often more complex than regular lists or cards. Depending on the library you use, it might already provide a full-blown table component. Nonetheless, it is recommended to create a separate table component, even if it uses the table component of the UI library inside of it.

If the library does not provide any table components, these are the components you can create:

table header
table row item
table footer
editable table row item in case of inline editing
table summary row item for totals at the end of the table
empty table

Form-related

Forms are almost always part of a web application. To increase reusability, you can create the following components:.

Form field

Some libraries offer a full form field component containing a label and a text field. If that's not the case, you could create one yourself.

To be included as options inside the form field component are:

label text
id (for accessibility)
is required (to show the "*")
helper text

The actual text field can be supplied by using content projection (ng-content). That way, you have the flexibility to add different kinds of content, e.g., text field, textarea, dropdown, etc.

The main benefit of having a dedicated form field component is that all form markup is in one single place. Possible changes could be floating labels instead of regular ones, instead of "*" you have to show "(required)", etc.

Form actions

If you have the same buttons for every form, you could create a form actions component for them. That clears up some space in your forms, and every form action is now part of a single component. Any changes to form actions now only have to be done in that component.

You could even supply short keys to the form actions. They can then be handled in that component, instead of implementing them everywhere a form is used.

Validation summary

Depending on the types of validation your web application needs, you might need to implement validation summaries. You can create a validation summary component that will handle this for you. You can even add functionality that, when made visible, scrolls to the validation summary.

The navigation menu of your web application can be created by a menu component of the UI library you're using. But it's worth creating a dedicated menu component yourself. Even if it only incorporates the menu component of the UI library. Sometimes changes have to be made that are perhaps not available in the UI library (e.g., an avatar). By creating your own menu component, you can easily add it yourself. It also makes the template of the component where your menu resides a bit smaller.

Skeleton

A skeleton component is often already provided by the UI library. But since a skeleton component has the same structural layout as the one it is loading for, you will have several. You can create template skeletons:

Skeleton for a table layout. Optionally with a configurable number of rows and columns.
Skeleton for a list layout. Configurable with the number of items, and how many rows per item.
Skeleton for a form layout. Configurable with the number of form fields. You can further split this skeleton into a regular form field skeleton component and a textarea field skeleton component that can be used in the general skeleton for the form layout.
Skeleton for card layout. Configurable with the number of cards and possible card template options.

Pickers

Other than the common date or time picker, your application often requires other types of pickers. Here are some ideas.

Language picker

When your web application needs to support multiple languages, the user needs to change the selected language. You could create two types of language pickers:

dropdown: pick a language from a dropdown list.
inline: all the languages are shown next to each other as links, with either the current language not being shown or the current language being highlighted.

If you need to support another language, you don't need to update any occurrences, but only the language picker.

Municipality picker

Often used in address forms, you might need the user to choose a municipality. Either by searching by postal code or by municipality. You can create a municipality picker component for this.

Most UI libraries provide an autocomplete (some call it typeahead) with which you can easily create the municipality picker. Your backend has to provide the search endpoint of course.

Country picker

Just like municipalities, a country can be chosen as well. Same idea as the municipality picker, but for countries. You can add extras like the country flag or abbreviations.

Gender picker

Usually, this is just a simple dropdown, but it could be that something more visual is needed, e.g., a dialog to ask questions like "Do you want to be addressed with they/them?". You can create a gender picker component to let the user select a gender.

Confirm dialog

Almost all UI libraries provide a dialog out-of-the-box, but often there is no built-in confirm dialog. You can create a custom confirm dialog component with options such as:

title
message
confirm button label
cancel button label
confirm callback
cancel callback

You can even go next level by providing a template instead of a regular text message.

Unauthenticated

It could be that your application uses some form of authentication but still allows unauthenticated users to see pages that need authentication. Instead of seeing the authenticated content, they will see content that encourages them to log in or sign up.

"You can only see chat messages when you're logged in. Please log in or sign up by using one of the buttons below."

In that case, you can create an unauthenticated component with configurable text to show to the user based on the page they are on.

Back button

When navigating through your pages, users need to have a way back to the previous page. It's worth creating a "back button" component. This is because it is often prefixed with an icon to indicate the "this goes back" functionality, e.g., by using a left arrow.

The functionality to go back to the previous page can all be incorporated into the back button component. So if a page needs a back button, you only need to include this component, and it is done.

An extra reason why it's worth creating a component for this is maintainability. If someone decides that the back button should be prefixed with a chevron instead of an arrow, then you only have to update that icon in the back button component.

Login

Create a login component containing only the fields required for logging (username or email, password, social logins, etc.). Not only will this make your login page template smaller, but you can also reuse it when you want the login functionality somewhere else, e.g., a dialog on some other page.

User menu

When a user is logged in, they can view some settings by clicking their avatar on the top right. This often pops up a list of options, such as account settings or logging out. You can create a user menu component to incorporate all these things.

Layout

Some layouts keep coming back in your application. E.g., a page with a title and back button, a page with a sidebar and right content, etc. Instead of copy-pasting the code for each of those pages, create layout components instead. Example layout components could be:

title with side navigation and content to the right
title with content but no navigation
full-screen layout

You can use the layout component directly inside another component or use Angular Routing. The latter comes with a bit more setup, as you have to add some configuration to your routes. Long story short, it's more or less this: place your existing routes as children underneath an empty route path in your route definition:

const routes: Routes = [
  { path: '', redirectTo: '/dashboard', pathMatch: 'full' },
  {
    path: '', 
    component: NavLayoutComponent, // your layout component
    children: [
      { path: 'dashboard', component: DashboardComponent },
      { path: 'detail/:id', component: HeroDetailComponent },
      { path: 'heroes', component: HeroesComponent }
    ]
  }
];

Then the template of the layout component will contain everything similar across the child components (e.g., titles, navigation, etc.). The router-outlet will load the component based on the route.

<!--nav-layout.component.html-->
<nav>
  <a routerLink="/dashboard">Dashboard</a>
  <a routerLink="/heroes">Heroes</a>
</nav>
<router-outlet></router-outlet>

Success

When dealing with many wizards in your web application, you might want the final step (after everything is completed) to be a success step with a call-to-action. You can create a success component with options such as:

optional image
title
message
call-to-action button text
callback for the call-to-action button

Counter

This could be for animated purposes or an actual countdown.
You see this on many websites when they're showing numbers; they are often animated to quickly animate from 0 to the number they want to show.
Or an actual countdown, where something happens when the countdown reaches zero.

In the first case, you can create an animated count component. You can create the range inside your component and calculate the total duration to display from start to end. Or by using CSS only. See an explanation here.

For the actual countdown, you can create a countdown component in which you do the actual countdown and provide a callback when the countdown reaches zero.

Conclusion

The types of components you need all depend on your web application, of course. The main takeaway here is to keep your component templates small, and the best way to do that is to create different components.

Do you have any more examples of possible components? Let me know in the comments.

The big Angular UI library comparison 📚

Thomas King — Mon, 11 Dec 2023 10:43:20 +0000

There are many UI libraries for Angular out there. Some provide the basics; others provide a whole arsenal of components. I went through the most-used Angular UI libraries and compared the components they provide. The libraries I took up in my comparison are:

Ng-bootstrap (MIT license)
PrimeNG (MIT license)
Kendo UI for Angular (subscription)
Ngx-bootstrap (MIT license)
Angular Material (MIT license)
Syncfusion Angular UI (subscription)
Devextreme Angular (subscription)
Ng-zorro (MIT license)
Nebular (MIT license)
Clarity (MIT license)
Ignite UI for Angular (subcription)

As you can see, four of these are subscription-based; the rest have an MIT license. A handy website to know what you can do with a license is tl;drLegal. The MIT license summarized:

Now off to the comparison! To make the comparison a bit easier for you, I've created a StackBlitz in which you can easily toggle between different UI libraries. You can even search the components. If the StackBlitz below does not work, I've added the entire sheet at the end of the blog as well.

There's more information about the individual components and what is meant by them below the StackBlitz.

List of components

Accordion

The accordion component allows the user to show and hide sections of related content on a page. Most commonly, when you expand a section, the previous section will collapse.

Alert

The alert component provides contextual feedback to the user. Often, you can choose between the types info, warning, error, success, or a color theme (e.g., primary).

Autocomplete (Typeahead)

An autocomplete (or typeahead) is a special kind of input in which the user can start typing, and while he is typing, some results are shown as a suggestion to autocomplete his current input. This can be either local data or data coming from a server.

Some libraries allow the results of the autocomplete to be grouped.

Avatar

The avatar component is used to display the profile image of a user. Depending on the UI library, it can be round, square, or rounded square.

Badge

The badge component visually shows the status of something or depicts the count on some element. E.g., the number of notifications. A badge is purely visual and not to be confused with a tag. You can interact with a tag, not with a badge.

Barcodes

A component not only to show or generate barcodes but sometimes QR codes (e.g., Ng-zorro uses QR codes).

Block UI

A component that will add an overlay to your page so you can no longer interact with it. It is often used when something is loading or submitting to prevent any user interaction.

Breadcrumb

The breadcrumb component shows the user where he is in the web application hierarchy. It allows him to navigate up the hierarchy.

Button

There is no need to explain what a button component does, as it speaks for itself. A component is used instead of the regular HTML button because it allows for more control and extensibility. The button component often comes in different color themes.

Some libraries provide additional options for their button component, such as loading behavior, ripples, etc.

Button group

Sometimes you wish to group buttons that are related. This can be to toggle between different states or even be purely visual to show the user these buttons are in fact related.

Some libraries allow the button group to behave as a radio button group (single selection) or as a multi-selection.

Calendar

The calendar component displays an entire calendar to the user. The library often provides the calendar as an inline variant of what is shown in the popup of the date picker.

Depending on the library, you can choose options such as the start day of the week, a button to select "today", changing globalization, etc.

Card

The card component displays some data as a card. Content is always required for the card. You can additionally (depending on the library's capabilities) add a title, image, avatar, call-to-action, etc.

The card component often distinguishes itself by showing a shadow around the card to display some form of depth.

Carousel

A carousel component, or slideshow component, is used to cycle through several elements. These can be images or even content. Some options depending on the library are autoplay, styling of the left and right arrows, adding pagination bullets, etc.

Chart

Some Angular UI libraries offer different types of charts; others are more limited. A chart component is used to display data in a visual way.

Chat

A chat component is used to visualize an entire chat.

Checkbox

A checkbox component is used to display true or false values. Some libraries even provide tri-state support (i.e., true, false, or null). A checkbox component is used in preference to the regular HTML input (type checkbox) to provide custom styling or additional options.

Chips

Chips are a special kind of input in which each input of the user is represented as a "chip" in the list. It allows the user to enter multiple things and clearly see each separate input. A library often allows each chip to be removed by adding a remove icon (a bin or an "x"). They can also be accompanied by another icon to depict the usage.

Sometimes the library allows direct interaction with the chips, even without any input field.

Collapse

A collapse component allows some content to be expanded or collapsed that is triggered by something else. An accordion is a special kind of collapse since each header collapses or expands the content beneath it. A collapse component can be any content and can often be triggered by any element (although good accessibility suggests a button).

With some additional styling, you could use an accordion component as a collapse. The accordion component would then only hold a single panel.

Color picker

A color picker component allows the user to select a color. Some libraries prefer to create their own color picker instead of the regular HTML input (type color) to provide additional styling or extra options, e.g., an inline variant. It also allows them to return a different format (rgba, hex, rgb, etc.).

Context menu

A context menu component is used when the user right-clicks a part of your page and you want to provide a different menu with different actions.

Data view

A data view is a component in which you can provide tabular data and, by means of a template, show it to the user in a specific way.

Date picker

With a date picker component, you can fill in an input field with a date selected from a calendar that pops up next to the input field. A library can provide its own date picker instead of the HTML input (type date), so it can have custom styling and more options, e.g., different views (year, month, day, time) or date formatting.

Some libraries allow for date range selection as well.

Diagram

A diagram component can show a diagram, such as an activity diagram or sequence diagram.

Divider

A divider component is used to clearly divide a list of items or sections. Most often, it is a single line to show the divider, but it can be accompanied by text.

Dock

A dock component is a special menu for navigation that is docked to one of the four sides of the pages: top, bottom, left, or right.

Drag & drop

A drag & drop component allows for drag & drop functionality. This can be used for sorting, allowing the user to set preferences in order, etc.

Dropdown (Select)

A dropdown component, or a select component, is used to make a selection from a list. When a selection is made, the selected item appears in the box. Some libraries allow for multiple selections by using checkboxes.

The library prefers to provide its own dropdown component in favor of the regular HTML select to have custom styling and/or extra options.

Dropdown button

A dropdown button allows the user to show multiple actions on a button. Much like a regular dropdown, but instead of showing the selection afterwards, an action is performed.

Some libraries have a "split button", in which not only can you have multiple actions on the dropdown, but the main button also has an action. So with the split button, you can have a main action or a side action.

Editor

Some libraries offer a basic editor component; others offer an entire WYSIWYG (What You See Is What You Get). The user can edit content and apply basic or advanced styling to it. Often, the component also allows for export or preview.

File upload

With a file upload component, users can upload one or multiple files. Some libraries allow for only one file per upload; others allow multiple uploads. You could use the regular HTML input (type file), but a file upload component provides much more options.

Filter

A filter component is used to create advanced filters. Often used for creating complex queries.

Floating button

A floating button component (also called FAB, or Floating Action Button) is a button that floats in a specific position on the page. When you scroll down, the floating button always stays in that position. It is most commonly used to execute a primary action for that page.

Floating label

A floating label component is used together with a text field. When the user focuses on that text field, the label (that looks like the placeholder) will simply float above the text field, making the user still aware of what that text field is about.

Gauge

A gauge component shows data in a gauge. Some libraries allow for high customization and nice animations.

Icon

Some libraries come with their own icon library. You can use the icon component to display an icon. Often, you have options like color and size.

Image editor

An image editor component allows for editing an image and saving or exporting it.

Image preview

An image preview component shows an image on which the user can interact so that the image is shown in a larger view (preview).

Input

The input component allows for user input. You can often choose between different colors, sizes, and other options, like a clear button. Some libraries include the label in the input component.

Input group

An input group component shows related things inside a single input. This could be a button next to the input or a prefix icon.

Input mask

The input mask component provides a mask to the user to which they must adhere. Good examples are phone numbers or credit card numbers.

Label

A label component is often a wrapper component for the regular label but provides additional styling and options, such as an icon or required markers.

List view

The list view component shows data in a list. The data is provided to the list view component, and by using a certain item template, it is shown as desired.

Listbox

A listbox component is used for showing several options and allowing the user to select multiple of them. The listbox options are all shown in a panel to the user immediately, which is different than a dropdown.

Map

A map component is used for showing a map to the user.

Modal (Dialog)

A modal (or dialog) component is used for displaying content above something else. Libraries often provide closing options such as click backdrop, a close button, or the escape key.

Multiselect

A multiselect component is like a dropdown (select) component but allows for multiple selections, and this is often done by using checkboxes.

Paginator

The paginator component is used for showing the pagination of something, e.g., a list or a table. It often contains options like go to the first or last page, go to the previous or next page, or separators when there are a lot of pages.

Pdf viewer

A pdf viewer component is used for showing pdf documents inside a page.

Pivot table

A pivot table component is used for analyzing a set of data. With it, you can create powerful summaries or calculations. E.g., based on a set of data in which people wear a hat or hoodie, extract how many people wear a hat, how many wear a hoodie, etc.

Popover

A popover component is used to display related, additional content. It is not to be confused with a tooltip. A tooltip is used for explaining the content, and a popover shows related, additional content. Often, a popover is shown by clicking the source. It also supports multiple forms of content, such as images or links.

Progress bar

The progress bar component is used to show progress to the user. You can often choose from several colors. Some also allow for indefinite progress bars.

Radio button

A radio button component is used together with other radio buttons to provide the user with a choice. A radio button component is used in preference to the regular HTML input (type radio) to provide custom styling or additional options.

Rating

A rating component is a special kind of slider component. The range is often small (e.g., 0 to 5, 0 to 10), starting from a certain number, and is represented by a set of icons (often a star icon). When you hover over the rating component, the icons will be filled to the point where your mouse is hovering. As soon as you click, that rating persists (until you choose a new rating).

Scheduler

The scheduler component represents scheduled data and allows a user to manage it by creating, updating, or deleting events from the schedule. A scheduler can display data on different views, e.g., months, days, etc.

Sidebar

A sidebar component is used for displaying navigation items on the side of a page.

Signature

A signature component allows the user to sign content by adding their signature.

Skeleton

A skeleton component is a special kind of loading component. It shows the rough structure of the content that is loading, e.g., 4 horizontal rectangles for a list component that is loading. It gives the user an idea of what kind of content will appear after the loading has finished.

Slider

A slider component is used for displaying a range between two numbers. You can also change the number of steps the slider increases. A good example for the slider component is a price range for a filter.

Sparkline

Sparkline charts are a special kind of chart. They are used for displaying data in a small space (e.g., inline usage).

Spinner

A spinner component is used as a placeholder or as an overlay for the content that is loading. It is often an icon that is animated by spinning it. Some libraries have spinner components that can be used inline.

Splitter

The splitter component creates layouts that split into panes that may be resized, expanded, and collapsed. A good example of a splitter component is on StackBlitz, where you can resize the editor and preview panel.

Spreadsheet

A spreadsheet component is used for displaying Excel-like spreadsheets. They often come with export functionality.

Steps

The steps component, or wizard component, is used for showing steps. It guides the user through a certain process.

Table

A table component is used for displaying tabular data. Some libraries offer a basic table component to show the tabular data. Others have advanced table components with options like sorting, filtering, or even exporting.

Tabs

Tabs is a container component that the user can navigate by means of tabs. Some libraries have extra options, like scrollable tabs.

Tag

A tag component is used to categorize content. They contain simple text and can be interactive. Common examples of tags are status, category, etc.

Terminal

A terminal component provides an entire terminal to the user.

Textarea

A textarea component is used to have multiline text input. A textarea component is sometimes preferred over the regular HTML textarea because it allows for extra options such as helper text or floating labels.

Timeline

The timeline component is used for showing a list of events over a period of time.

Time picker

What a date picker is for entire dates, the time picker is for time specifically. It allows you to pick a time.

Toast

A toast is a dismissible message. Some libraries allow toasts to be automatically dismissed after a period of time. They are most often set at the bottom right, but they have configurable positioning.

Toggle

A toggle or switch is used to show true or false values in the form of a visual switch.

Toggle button

Just like a regular toggle, the toggle button is used to show true or false values. But instead of a switch, it is a button that is either in the pressed state or not.

Toolbar

A toolbar is a set of buttons and/or actions all grouped in a bar that is fixed at a certain position (either top, bottom, left, or right) of a content panel. The buttons and actions on the toolbar often have an influence on the content of the content panel. E.g., a toolbar for a rich text editor.

Tooltip

A tooltip displays text to explain the content you're hovering over. You can often change the position it is displayed in (top, right, bottom, or left). Some libraries also allow you to trigger the tooltip with a click.

Tree

A tree component is used for showing nested data. Some libraries allow for nested tabular data; others are more basic and are nested lists.

Word (Document viewer)

A viewer component for showing a Word file or another document. Just like the pdf viewer, but for Word or other documents.

Conclusion

As you can see, there are many Angular UI libraries, but you should pick one that fits your needs. Also, think about the budget, because not every library here is free. You can always go for a free one and use other open-source libraries for the more detailed stuff, like charts. Just keep in mind to keep the number of libraries limited, because the more libraries you use, the more you will need to maintain when updating your Angular version.

To end this blog post, here's the entire comparison in a regular table (in case the StackBlitz fails to load). I hope you enjoyed this read! And as always, if you have any questions, feel free to contact me!

	Ng-bootstrap	PrimeNg	Kendo UI	Ngx-bootstrap	Angular Material	Syncfusion	DevExtreme Angular	Ng-zorro	Nebular	Clarity	Ignite UI
Accordion	x	x	x	x	x	x	x	x	x	x	x
Alert	x	x		x		x		x	x	x
Autocomplete (Typeahead)	x	x	x	x	x	x	x	x	x		x
Avatar		x	x			x		x	x		x
Badge		x	x		x	x		x	x	x	x
Barcodes			x			x		x
Block UI		x
Breadcrumb		x	x			x		x
Button		x	x	x	x	x	x	x	x	x	x
Button group		x	x	x	x	x	x	x	x	x	x
Calendar	x	x	x	x	x	x	x	x	x		x
Card		x	x		x	x		x	x	x	x
Carousel	x	x	x	x		x	x	x			x
Chart		x	x			x	x				x
Chat			x						x
Checkbox		x	x		x	x	x	x	x	x
Chips		x	x		x	x	x	x	x	x	x
Collapse	x	x	x	x				x
Color picker		x	x			x	x	x
Context menu		x	x			x	x	x	x
Data view		x	x			x	x			x	x
Date picker	x	x	x	x	x	x	x	x	x	x	x
Diagram						x	x
Divider		x			x			x			x
Dock		x
Drag & drop		x	x				x				x
Dropdown (Select)	x	x	x	x	x	x	x	x	x	x	x
Dropdown button		x	x			x	x	x
Editor		x	x			x	x
File upload		x	x			x	x	x
Filter			x			x	x				x
Floating button		x	x		x	x	x
Floating label		x	x		x	x	x				x
Gauge		x	x			x	x				x
Icon		x	x		x	x	x	x	x	x	x
Image editor						x
Image preview		x						x
Input		x	x		x	x	x	x	x	x	x
Input group		x	x			x	x	x	x		x
Input mask		x	x			x	x				x
Label			x				x	x			x
List view		x	x		x	x	x	x	x	x	x
Listbox		x	x			x	x			x
Map			x			x	x				x
Menu	x	x	x		x	x	x	x	x	x	x
Modal (Dialog)	x	x	x	x	x	x	x	x	x	x	x
Multiselect		x	x		x	x	x	x	x		x
Paginator	x	x	x	x	x			x			x
Pdf viewer			x			x
Pivot table			x			x	x				x
Popover	x	x	x	x		x	x	x	x
Preview image		x						x
Progressbar	x	x	x	x	x	x	x	x	x	x	x
Radiobutton		x	x		x	x	x	x	x	x	x
Rating	x	x	x	x		x		x			x
Scheduler			x			x	x
Sidebar	x	x	x		x	x	x	x	x	x	x
Signature			x			x
Skeleton		x	x			x		x
Slider		x	x		x	x	x	x		x	x
Sparkline			x			x	x				x
Spinner		x	x		x	x	x	x	x	x
Splitter		x	x			x					x
Spreadsheet			x			x					x
Steps		x	x		x			x	x	x	x
Table	x	x	x		x	x	x	x		x	x
Tabs		x	x	x	x	x	x	x	x	x	x
Tag		x	x					x		x
Terminal		x
Textarea		x	x		x	x	x	x	x	x	x
Timeline		x	x			x	x	x		x
Timepicker	x	x	x	x		x	x	x	x		x
Toast	x	x	x		x	x	x	x	x		x
Toggle		x	x		x	x	x	x	x	x	x
Toggle button		x	x	x	x	x
Toolbar		x	x		x	x	x	x	x		x
Tooltip	x	x	x	x	x	x	x	x	x	x	x
Tree		x	x		x	x	x	x	x	x	x
Word (Document viewer)						x

Why you should never use form.invalid 🙅‍♂️

Thomas King — Tue, 05 Dec 2023 07:00:00 +0000

When doing form validation in Angular, it's best practice to check the form's validity before posting it to the server or processing it. The form itself has a valid property but also an invalid property to check for validity. This might lead to this kind of code:

if (form.invalid) {
  // show errors
} else {
  // process form and continue
}

This will actually work in most cases, but it is deceiving as it might give false positives. And that's the case when using any async validation on the form.

Adding async validation to a form

So you have that same form, but now there's a change incoming that requires you to add some async validation to a form control: check whether the username is already taken.

The user starts typing, fills in an existing username, and immediately hits enter to submit the form. Hopefully the back-end gives you an error message to tell the user this username already exists because the front-end won't do it.

Why is that? Because next to valid and invalid, there is a third state called pending.

As soon as the async validation is triggered on that form control, the form properties valid and invalid will be false, but the pending property will be true. When the async validation has ended, the pending property will be false, and depending on the result of the async validation, the correct states are set on valid and invalid. But by using the existing logic, it will go to the else condition, process the form, and continue.

To be on the safe side, never use the invalid property but negate the valid property:

if (!form.valid) {
  // show errors
} else {
  // process form and continue
}

Even when using async validation, this will correctly interpret the form validation, i.e., the form is invalid as long as the async validation is not done.

I've created a form status emulator (embedded StackBlitz below) to check for the different statuses a form goes through when editing a form control. Use this playground to check the status of the form according to the update mode and attached validators. In this playground, you can:

change the update mode to change, blur, or submit.
add a required validator.
add a maxlength validator (the maximum length is fixed at 10 characters).
add an async validator (does an async validation for 4 seconds and checks whether the input starts with "server").
reset the form

TLDR;

When the form is going through async validation, both valid and invalid will be false, whereas the pending property will be true. This gives false positives because the async validation is not over and could potentially return validation error(s). Use the valid property to check for correct form validity.

If you have any questions, feel free to contact me!

RxJS mergeMap vs switchMap vs concatMap vs exhaustMap

Thomas King — Fri, 01 Dec 2023 07:00:00 +0000

First of all, I would like to start off by saying that this isn't the first blog post about this subject. But what I miss the most in other posts is visualizing these operators. This is the reason I created this blog post. So off we go!

mergeMap, switchMap, concatMap, and exhaustMap are all called higher-order mapping operators. Instead of mapping values to other values, they map them to Observables, on which you can pipe further.

One of the most used ones is probably the switchMap operator. Most commonly, it is used together with HTTP GET calls, something like this:



this.idParam$.pipe(
  switchMap((id: number) =>   
    this.productsService.getProduct(id)
  )
);

People know this operator because of its cancellation effect. But there's also the mergeMap, concatMap and even exhaustMap operators, of which many people are not aware of or don't know when to use them. Let's go through them one by one.

Note: In each example image down below, you can see "SOURCE" and "INNER". "SOURCE" means the source Observable (e.g., a click event, ActivatedRoute query params, etc.), and "INNER" is the inner Observable that is returned by one of the higher-order mapping operators.

MergeMap

The mergeMap operator is the easiest of them all. It will map each source value to an Observable, which is merged into the output Observable. Simply explained: whatever comes in, comes out, regardless of order.

In this example, you see that when the source (A) gets called, the inner source starts emitting its values. When the source gets called again while the inner source is still emitting its values, the new values will be emitted as well. So if the source is called multiple times, all inner sources will emit their values in parallel.

Use case

A good use case of the mergeMap is a list of items in a shopping cart. You have an overview of all items, and next to each item is a button to delete it from the cart. If you're in a hurry, you can delete several items at once by clicking each "delete" button quickly. As a customer, you expect that each item that you click to delete will effectively be deleted. And that is what the mergeMap will do; it will continue to delete each one, even if you already clicked one for deletion.

Now imagine you use switchMap instead: you hastily click each "delete" button. Since the first delete is still ongoing on the server while you click the second delete, the first delete will be cancelled, but while the second delete is ongoing, the third is clicked for deletion, canceling the second one, etc. This makes deleting items in your shopping cart quite unpredictable.

SwitchMap

switchMap will map each source value to an Observable, which is merged into the output Observable, but also cancel any previous inner Observable.

As you can see in the example, each time the source A gets called, the emitting of the previous inner source will get cancelled. The new values will be emitted instead, unless source A gets called again.

The cancellation effect is more visible when you call the source A multiple times after each other:

Use case

As stated before, the switchMap is most often used together with HTTP GET calls in order to cancel a previous call when a new one is requested soon after. For example, a "refresh" button that will refresh the data in a list. You could spam the button to refresh, but with switchMap that would keep canceling all previous clicks.

Another good use case is autocomplete. While typing, the results are being fetched for you. But when the first results come in, it might be that you have already typed some more, which might return a more narrow result. So in that case, it would be handy that the previous call was cancelled to go for the newest one. The best practice is to combine your switchMap with a debounceTime operator to further improve your autocomplete.

ConcatMap

concatMap will map each source value to an Observable, which is merged into the output Observable in a serialized fashion, waiting for each one to complete before merging the next. So, simply put, they emit values while maintaining order.

In the example, when the button is clicked for the first time, the inner source starts emitting its values. While it's still emitting, we call the source a second time. We can see that instead of emitting new values for the inner source, it waits until the values of the first time are all emitted. Hence, the order is maintained.

Use case

concatMap is used where order is of importance. A use case could be a character builder in a game where you can choose several options, but some options are dependent on each other. For example, you choose a red hair color and, at the same time, want to add a moustache. The order is important here because you want a red moustache to be added. So the first API call will be with the "red hair" filter, followed by a second API call with the "moustache" filter. Due to the first API call, the second one already knows the hair color is red and can send over a red moustache.

Source: https://www.icy-veins.com/forums/

Compare concatMap with customers at a pharmacy. They all get served in the order when they arrived. Even if some arrive at the same time, they are handled in a sequential manner.

ExhaustMap

exhaustMap will map each source value to an Observable, which is merged into the output observable only if the previous projected Observable has completed. In simpler terms, the new values are only emitted when the previous ones have all been emitted.
You can remember exhaustMap by thinking that you can't make any new calls because it's exhausted from still emitting.

In the example, you see that the source is called multiple times. Only for the first call are the inner source values emitted (the red ones). All subsequent source calls are ignored, except the last call, since all previous inner values have been emitted.

Use case

A good use case would be to prevent double submissions. If a user keeps spamming the submit button, each call will go through. Using exhaustMap will ignore any subsequent calls. You could use switchMap, but that would mean that the submission would only go through when the user stopped spamming that submit button.

You could compare it to a restaurant. You give your order to the waiter, and that will make the kitchen start preparing your order. If you call the waiter again with the same order while they're still busy with your current order in the kitchen, it will not make the kitchen start you on a new order. No, they will prepare it, and when it is ready, you can call the waiter again with that same order.

Airport luggage handling analogy

Let's compare all these operators with the handling of luggage at an airport. At this airport, there is only one conveyor belt to handle luggage. When an airplane arrives, all luggage is put on the conveyor belt so each traveler can retrieve their luggage.

With `mergeMap`

When an airplane arrives, the luggage is put on the conveyor belt, one after the other. When another airplane arrives as well, the luggage of that one is also put on the conveyor belt, merged with the luggage of the other airplane. So the conveyor belt will show a mix of luggage from the first and second airplane.

With `switchMap`

When an airplane arrives, the luggage is put on the conveyor belt, one after the other. But as soon as another airplane arrives, they stop putting any luggage from the previous airplane on the conveyor belt. They cancel any further luggage handling for that airplane and begin handling the luggage for the newly arrived airplane.

With `concatMap`

When an airplane arrives, the luggage is put on the conveyor belt, one after the other. When a new airplane arrives, all the luggage from the first airplane is put on the conveyor belt. Only when all that luggage is handled will the handling of the luggage on the second airplane start.

With `exhaustMap`

When an airplane arrives, the luggage is put on the conveyor belt, one after the other. When a new airplane arrives and the luggage of the first airplane is still handled, the luggage handling personnel simply ignores the second airplane. The luggage on the second airplane will not be handled.

TLDR;

mergeMap: come in, merge, come out.
switchMap: come in, merge, come out, but cancel when new ones come in.
concatMap: come in, merge, come out, but maintain order.
exhaustMap: come in, merge, come out, but while ongoing, ignore new ones when they come in.

If you're having trouble choosing the correct higher-order mapping operator, have a look at the following decision tree. It is based on the operator decision tree at RxJS.dev.

Please feel free to play around in the embedded StackBlitz down below. The example images on this blog are based on this StackBlitz.

If you have any questions, feel free to contact me!

What HTML to use for a read-only form?

Thomas King — Mon, 27 Nov 2023 08:33:07 +0000

Front-end developers will always have come to some point in their career where they have to deal with forms. Creating a registration form, a login form, a form to gather user information, etc. The examples are numerous. Creating such forms is often something that most developers know how to do. Using labels and inputs, applying the correct styling or classes, and woosh, there is a form that the user can fill in.

The challenge is when that same form needs to be displayed in a read-only way. Labels and inputs speak for themselves, but what should you choose to display them? A good example would be in a CRUD application (an acronym for Create, Read, Update, and Delete). What often happens is that the HTML of the "create" or "edit" form is taken, but the form controls are then replaced with span or p elements. Although this works, it's not the best practice when accessibility (a11y) comes to mind.

An example of how it is often done:

<div class="user-settings-form">
  <div class="user-data">
    <div class="form-field">
      <label for="firstName">First name</label>
      <span id="firstName">John</span>
    </div>
    <div class="form-field">
      <label for="lastName">Last name</label>
      <span id="lastName">John</span>
    </div>
  </div>
  <div class="user-address">
    <div class="form-field">
      <label for="addressLine1">Address line 1</label>
      <span id="addressLine1">123 Maple street</span>
    </div>
    <div class="form-field">
      <label for="addressLine2">Address line 2</label>
      <span id="addressLine2">Anytown, PA 17101</span>
    </div>
  </div>
</div>

One thing is that label elements are used to describe the corresponding form control (specifically label elements). This can be done either by using the for attribute or by putting the form control inside the label element itself. But since there is no longer a form control, the use of the label element should be discouraged.

Another thing is that you should strive for semantic HTML. Writing semantic HTML means using HTML elements to structure your content based on each element's meaning, not its appearance. And by keeping the structure of the existing "create" or "edit" form and replacing the form controls with span or p elements, that doesn't really fit. Especially div and span elements convey no meaning at all. It also makes your HTML quite bulky.

What would be a good HTML structure?

Let's keep the previous two things in mind and have a look at what a read-only form actually contains. In general terms, it's a list of questions and answers. E.g., the answer to the question "first name" is "John".
When digging through the (rather big) list of semantic HTML elements, we see the dl element ("description list"). The definition for a dl element according to mdn is the following:

The <dl> element encloses a list of groups of terms (specified using the <dt> element) and descriptions (provided by <dd> elements). Common uses for this element are to implement a glossary or to display metadata (a list of key-value pairs).

A "list of key-value pairs" is what we need here. Using a description list not only makes our form semantic but also makes it quite flat. This is a huge benefit when we want to keep style and template separate, because it will be the stylesheet that will tell how the form will look and not the other way around.

So coming from the bulky code we had for the form in the beginning, this can be transformed to:

<dl>
  <dt>First name</dt>
  <dd>John</dd>
  <dt>Last name</dt>
  <dd>Doe</dd>
  <dt>Address line 1</dt>
  <dd>123 Maple street</dd>
  <dt>Address line 2</dt>
  <dd>Anytown, PA 17101</dd>
</dl>

Much cleaner, flatter, and less bulky than the previous code. But I hear you say, "Now I should write more code in my stylesheet." That's true, but that's also where it belongs. The HTML now only conveys the meaning of the form; how it should look in the browser is a concern for the stylesheet.

Note: You can still use classes to make your styling more specific. In an Angular component, for example, I would leave those out and style the dl, dt, and dd elements directly due to ViewEncapsulation. Leaving out those classes makes it even cleaner.

To keep a 2-column layout for the form using the new HTML structure, we could harness the power of CSS grids, and the stylesheet could look like this (note: .user-form is the class given to the dl element):

.user-form {
  display: grid;
  gap: 0.5rem;
  grid-template-columns: 100px auto;
}

.user-form > dt,
.user-form > dd {
  margin: 0;
}

.user-form > dt {
  text-align: right;
  font-weight: bold;
}

In the original piece of code, there was also a difference between the "user data" and the "user address". That is no longer visible in the HTML now, but if you want to distinguish between them in the stylesheet, you can do so by using the :nth-of-type pseudo class:

.user-form > dt:nth-of-type(2),
.user-form > dd:nth-of-type(2) {
  margin-bottom: 1rem;
}

You have reached the end of this blog. I hope this guide will give you better insights into how to structure read-only forms in HTML.

If you have any questions, feel free to contact me!

How to code faster - VS Code edition

Thomas King — Fri, 24 Nov 2023 07:00:00 +0000

Pair programming can be very productive. But there's nothing so annoying as seeing your fellow programmer struggle with his coding. And with struggle, I don't necessarily mean that he lacks experience, but rather that he's coding so slowly. It almost feels like the scene with Flash from Zootopia (a must-see movie).

Source: Alphacoders.com

How to not be Flash? Here are some tips and tricks for coding in Visual Studio Code (VS Code).

Note: I do not own a Mac, so the short keys mentioned here are for Windows only. You can find a translation to Mac here, but since I can't reproduce them on a physical Mac, I did not include them in this guide.

Copy and paste smarter

I've seen people copy-pasting code by doing the following:

Move the cursor of the mouse to the beginning of the word.
Hold left-click.
Drag all the way to the end of the word.
Release left-click.
Right-click the selection.
Click "copy".
Scroll in the file explorer of VS Code to find the destination file.
Click the destination file.
Move the cursor to the desired location within the file.
Right-click in destination.
Click "paste".

This is a somewhat slow process to do. Especially if you need to apply this several times... Some ways to improve your copy-pasting are:

Use CTRL + C to copy and CTRL + V to paste.
Use CTRL + SHIFT + left/right arrow to increase/decrease selection by words.
Use SHIFT + left/right arrow to increase/decrease selection by character.
Clicking a line of code in VS Code and pressing CTRL + X will put that line in your clipboard. Using CTRL + V anywhere will insert that line of code there.
Use ALT + up/down arrow to move a line of code up/down a spot.

Copy-pasting smarter also means navigating smarter.

Navigate smarter

Instead of going through the explorer pane manually, use the key combination CTRL + P. With this, you can search files by name. This is a "smart" search, meaning that it will not only look for words containing your search text but also a combination, e.g., prodetcon will also find project-details-container.component.ts. Using CTRL + P is a lot faster than seeing someone struggle through their file explorer pane, which is a pain in itself (pun intended).

Instead of looking for some code inside a file by scrolling, use these key combinations:

CTRL + G: go to line
CTRL + F: search in file (using the ENTER key navigates to the next occurrence)
CTRL + click class/function/etc.: go to definition of said class/function/etc.

Use CTRL + TAB to switch between the last opened file and the current (or TAB further to switch to other opened files). This is a lot faster than moving your cursor to the taskbar, looking for the correct tab, and clicking it to open.

Note: switching between opened files is efficient this way in VS Code. Also, make use of ALT + TAB in Windows to switch between open windows.

Rename smarter

Do not rename every single occurrence of a variable yourself. It is time-consuming and prone to errors. Instead, go to the definition of that variable and press F2, rename it, and press ENTER. This will change every occurrence. Not only does this work on variables, but also on functions, classes, interfaces, etc. This also works across files.

Use Emmet

Emmet is a content/code assist tool to write code faster and more efficiently. It comes standard with VS Code so there is no need for any plugin. The concept is simple: you start typing an Emmet abbreviation, press TAB or 'ENTER', and a full Emmet snippet for that abbreviation will come out.

An example Emmet abbreviation could be .grid>.col*3. When you press TAB or ENTER, VS Code fills out the entire piece of code for you:

One of the cool things about Emmet is that you can generate "lorem ipsum" texts as well. E.g., ul>li*4>lorem4 will generate an unordered list of 4 elements, with each list item containing 4 random words.

Use a formatter

Use a code formatter inside VS Code to format your code. I highly recommend Prettier.
One of the benefits of using a code formatter is that it also "beautifies" your code. So if you copy-paste code from somewhere that has no layout at all, you can hit the format key combination (CTRL + ALT + F) et voilá, your code is now "beautified" and, more importantly, readable.

Note: a good tip is to apply formatting on save. You can change this in the settings (look for "Format on save").

Formatting is not only useful for yourself but for the whole team because it enforces the team's code to be more consistent. Have a look at my other post Enforcing front-end guidelines in an Angular project to read more about it.

Use code snippets

Code snippets are templates that will make it easier to write repeating pieces of code, e.g., for loops, while statements, etc.

By making use of code snippets, you can easily create blocks of code by typing in the bare minimum. You can use the built-in code snippets, use extensions that provide snippets, or even create your own!

The built-in snippets provide templates for a number of languages, such as TypeScript, JavaScript, HTML, CSS, etc. You can use it to easily create a switch statement, as seen above, for example.

The VS Code Marketplace has several extensions that provide snippets for you. Examples are Angular snippets, Tailwind UI snippets, Bootstrap snippets, etc.

Finally, you can create your own snippets. You can either create global snippets for a specific language or create snippets specific to a project. I won't go into any details here, but have a look at the documentation on how to create your own snippets.

Make use of "quantum typing"

I call it "quantum typing" because this really speeds up the way you type out code in VS Code. It's all about multi-selection. When you need to change or add text to multiple lines, VS Code allows you to do so by selecting those multiple lines and simply starting to type on those lines at the same time.

Hold SHIFT + ALT and drag across multiple lines to make a selection. You'll see that multiple typing cursors appear across those lines. Simply start typing, and the text will be added simultaneously.

If you want to add the same text to several places but they do not align, you can hold ALT while clicking all the places where you want to type the same text.

You can also hold ALT and select multiple words at the same time. Instead of clicking a position, simply drag for a selection and release left-click or double-click for a single word selection, all while holding that ALT key.

Quickly surround selection

Code often has to be surrounded by square, round, or curly brackets. Or something needs to be surrounded by quotes (single or double). To do this, people often go to the start position, type in the starting bracket, move the cursor to the end position, and type in the ending bracket. A more efficient way is to select the parts that need to be surrounded and simply type the starting bracket. VS Code will be smart enough to know that the whole part needs to be surrounded.

This works for (, {, [, <, ' and ".

Make use of VS Code refactoring skills

You can use VS Code to automatically refactor pieces of your code. E.g., instead of writing your own getters and setters, you could let VS Code generate them for you.
To refactor something, just select what needs to be refactored, right-click, and click Refactor... or even faster: use CTRL + SHIFT + R.

Depending on the file you're in, VS Code can offer you several kinds of refactoring. E.g., for TypeScript, you could use Extract function, Extract constant, or Generate get and set accessors. See the full list for TypeScript here.

Search and replace using RegEx

Regular expressions (RegEx) can be a very powerful tool in your developer toolkit, and it is worth your while to get better acquainted with them. Not only can you use it in your own code (e.g., validation patterns, string replacement, etc.), but you can also use it for an advanced search and replace in VS Code.

Example

You are in a project where some CSS selectors start with app- and end with -container. Due to new guidelines, they want you to change the suffix -container to -wrapper. You could try a simple search and replace by looking up -container and replacing it with -wrapper, but when you do the replacement, you see that some occurrences have been replaced, which should not have been the case (e.g., a CSS selector called .unit-container-highlight becomes .unit-wrapper-highlight).

With RegEx, we can search more fine-grained. Using a capturing group, we can extract the words we want to keep while replacing the rest. The RegEx can look like app-([a-z\-]+)-container. We want to replace the results so they end with -wrapper. The replacement string will look like app-$1-wrapper. Just make sure you checked the Use Regular Expression.

Caution: even though a RegEx allows for a more fine-grained search, check the results in the search pane before doing the actual replacement!

You can have even more control by allowing the search to be applied only to certain files. Examples could be only HTML files (*.html) or even an entire folder only (src/app/modules).

If you want to try out the RegEx before doing the search to be sure it's the correct one, use an online RegEx tester, such as Regex101. If you have no or little experience with RegEx, take a look at https://regexlearn.com/.

Use tools to automate monotonous work

Sometimes we have to do monotonous work like creating mock data, creating a function for each field in a class, creating HTML list items based on the properties of an interface, etc. Like the saying goes:

Work smarter, not harder!

Use tools to automate such kinds of monotonous work instead of doing all the tedious work yourself. Tools I often use are:

NimbleText: converts input as rows to a certain output based on a given format.
Mockaroo: generates mock data and outputs it in several formats (JSON, CSV, XML, etc.).
JSON Generator: also generates mock data, but for JSON specifically. It's a bit more complex, but it allows for tailor-made results.

A good example of using NimbleText would be creating an entire form in HTML based on a few fields. We have a list of fields that we want to show in a form. Each field will have a label and an input. Let's create some data for NimbleText to convert:



first name, text
last name, text
email, email
street, text
number, number
city, text
postal code, text

Here we have 7 rows and 2 columns. Each row represents the form field. The first column is the name of the label, and the second column is the type of HTML input.
Inside NimbleText, we leave the settings as is (column separator , and row separator \n).
Each form field should be in a div with the class .form-field, containing a label with the text and an input for the form field. The pattern for NimbleText will look like this:



<div class="form-field">
  <label for="<% $0.toCamelCase() %>"><% $0.toSentenceCase() %>:</label>
  <input id="<% $0.toCamelCase() %>" type="$1"/>
</div>

When we have a look at the output, we see that a lot of work has been done for us:



<div class="form-field">
  <label for="firstName">First name:</label>
  <input id="firstName" type="text"/>
</div>
<div class="form-field">
  <label for="lastName">Last name:</label>
  <input id="lastName" type="text"/>
</div>
<div class="form-field">
  <label for="email">Email:</label>
  <input id="email" type="email"/>
</div>
<div class="form-field">
  <label for="street">Street:</label>
  <input id="street" type="text"/>
</div>
<div class="form-field">
  <label for="number">Number:</label>
  <input id="number" type="number"/>
</div>
<div class="form-field">
  <label for="city">City:</label>
  <input id="city" type="text"/>
</div>
<div class="form-field">
  <label for="postalCode">Postal code:</label>
  <input id="postalCode" type="text"/>
</div>

So be creative and use these tools whenever you can.

Conclusion

Coding faster in VS Code comes down to knowing your short keys and using the power of the IDE to your advantage. Here's a quick round-up of what was mentioned:

Use short keys for copy-pasting.
Navigate more efficiently by searching instead of manually navigating.
Rename using F2 instead of doing it manually.
Use Emmet.
Use a formatter for neat outlining (and other advantages).
Use code snippets.
Quantum type, like there's no tomorrow.
Use VS Code refactoring.
RegEx to the rescue for search and replace.
Use tools such as NimbleText to automate monotonous work.

I hope you enjoyed reading this. If you know anyone who might need a little help with coding just a bit faster, feel free to share the article!

If you have any questions, don't hesitate to reach out! Thanks!

Coping with i18n

Thomas King — Fri, 17 Nov 2023 15:21:09 +0000

Coping with i18n makes it sound like it's some sort of autoimmune disease you have to learn how to live with. I18n (which stands for internationalization) is not a disease, but it is something you have to learn to live with. When we look up the meaning of "to cope with" in the dictionary, it says

to cope with: to deal with and attempt to overcome problems and difficulties

I18n does come with its challenges and difficulties. Especially in a project that started off small but is growing into something larger.

Fun fact: the 18 in i18n represents the 18 letters that stand between "i" and "n" in internationalization. So what would "accessibility" be?

Let's start with a use case:

A new project has started. It's not that big yet, but they do want translations for it. When adding internationalization, you just start using translation keys as you see fit. You have a label on one page that needs to be translated to "First name". You add a translation key to your translation file for this label:

{
    "firstName": "First name"
}

Then, you have to create another page that also has a label that needs to be translated to "First name". Great! You can reuse the same translation key.

But the UX designer decided that on the first page "First name" is okay, but on the other one, it should be "What is your first name?".

No problem; you can just add a new key.

{
    "firstName": "First name",
    "whatIsYourFirstName": "What is your first name?"
}

But then a new change in translation comes up... It should no longer be "What is your first name?" but "Your first name please?". Time to update to translation then?

{
    "firstName": "First name",
    "whatIsYourFirstName": "Your first name please?"
}

That would be really confusing. Can you imagine a whole translation file with such keys?

Let's go over a few guidelines for i18n so it's easier to cope with it in your project.

A clean home is a happy home

Make sure that your translation file is up-to-date. Remove any unused translation keys and make sure all translation keys used in code are actually included in your translation file.

Some libraries support ways to handle missing translations (e.g., TranslocoMissingHandler from Transloco or MissingTranslationHandler
from ngx-translate). So that's a way to find out any missing translations, but that's quite manual because you have to go over every part of the served application.

Another way is to extract the translations from your template. For Angular i18n, you can use the extract-i18n Angular CLI command to extract the marked text in the component into a source language file. For ngx-translate, you can use the plugin ngx-translate-extract. And for transloco, there is the transloco-keys-manager.

It's important to keep the translation file up-to-date. Any keys that are used there that are not in the template may cause confusion. Any key missing in the translation file that is used in the template will hopefully result in an untranslated label (in the worst case, it will throw an error).

Be consistent

Some libraries provide different ways to translate stuff in your application. Some of the possibilities are functions, pipes, or directives. Be consistent, and keep using the same ones.

For an Angular project, for example, use directives in the template for translations. Or pipes. Just don't start mixing, because that would be ... inconsistent.

Another thing to be consistent about is the translation keys. Choose a certain case (camelCase, PascalCase, etc.) from the beginning and stick with it. If you happen to work with people who are not that proficient in English, it might be worth going all lowercase. One of the benefits of using all lowercase is that there can be no mistake when a word is made up of several words. For example, lowercase "deadline" is easy for everyone to write. But when using camelCase, some people might think deadline is made up of two words, so they come up with "deadLine". Then some other team member wants to use that translation key and uses "deadline" in the template. The result is that the translation is not showing up.

Conventions

Introduce conventions when working with translation files. The casing is one thing I already mentioned. Here are some others:

Avoid abbreviations

Don't use abbreviations in your translation keys. Most of the time, not everyone is aware of what the abbreviation means. A good example would be when you see the abbreviation "CI". As someone in development, you would think this stands for "Continuous Integration". But you were wrong; the application they used this abbreviation for was for the police department and stands for "Confidential Informant". So use "language" instead of "lang", use "component" instead of "comp", etc.

Use unambiguous names

Unambiguous names have a clear intent and are easy to understand. When choosing a translation key, keep that in mind. E.g., instead of "address1", "address2", use "homeAddress" and "invoiceAddress".

Use namespacing

Namespacing your translation keys is a good way to group them into categories. Depending on the translation library used, you could use nesting (like an object structure) or you can use namespacing in the key name (separated with a dot, e.g., "common.buttons.login"). Namespacing your translation keys makes it easier to find a certain key as well.

Do not concatenate keys

It's tempting to reuse keys in the template so you can concatenate them to a newly translated value. This might work for the language you're working in, but what if you have to support a language where it does not? An example:

<button type="submit">{{'common.labels.please' | translate}} {{'common.buttons.login' | translate}}</button>

We want a button saying "Please login". This concatenation might work in English, but if you try it in Dutch for example, it gives "Alsjeblieft inloggen", which sounds not so Dutch.

Therefore, it's better to create a new key with its own dedicated translation and use that key instead.

Use pluralization

Don't implement pluralization yourself in an Angular project by using *ngIf or another implementation. Make use of NgPlural. Also, do not concatenate a number with the translation key, e.g., 5 {{ common.labels.days | translate }}, but pass it as a parameter to the translation key if the library you use allows it. It will provide much more flexibility when you start integrating multiple languages.

Namespacing

Namespacing your translation keys is not an easy task. Do you group in pages? Do you group in components? Do you group by type (labels, buttons, etc.)? This is something you should agree upon as early as possible. It will not always fit, but just be sure the team agrees on all categories. If you don't know how to begin, this structure works well most of the time:

{
  // common
  "common.buttons.test": "",
  "common.labels.test": "",
  "common.titles.test": "",
  "common.messages.test": "",

  // component specific
  "components.userList.buttons.test": "",
  "components.userList.labels.test": "",
  "components.userList.titles.test": "",
  "components.userList.messages.test": "",

  // page specific
  "pages.home.metadata.description": ""
}

Note: This is namespaced in the key, but it might as well be nested.

A common namespace is used for translations that are reused often, like "Save", "Cancel", "Ok",...

{
  "common.buttons.ok": "Ok",
  "common.buttons.cancel": "Cancel",
  "common.labels.createdBy": "Created by {{name}}",
  "common.titles.edit": "Edit",
  "common.messages.required": "This field is required"
}

The components namespace is used for translations per component. That way, translations are easily found. The downside of this approach is that when the component changes its name, the namespace should be renamed as well. It's easier to create component specific translation keys instead of keys for an entire page. This is because components can be reused, which can cause confusion when the component of a specific page is reused on another page (which page specific label would you use then?).

Note: If a translation can be reused over several components, put it in the common namespace and use that key instead. That way, there won't be duplicates of the same translation. Some people may say that according to UX, the translation should be different (e.g., instead of a generic "save", use "save user" and "save settings"), and they are right. In that case, it should be in the components namespace. But if that's not the case (even if it ever may be), just use the common namespace (principle of YAGNI).

{
  "components.confirmDeleteDialog.buttons.ok": "Ok, delete",
  "components.confirmDeleteDialog.buttons.cancel": "No, do not delete",
  "components.confirmDeleteDialog.titles.confirm": "About to delete {{name}}",
  "components.confirmDeleteDialog.messages.confirm": "Deleting the user will imply that he will no longer has access to the application. Do you want to continue?",
  "components.registerForm.labels.firstName": "What is your first name?",
  "components.registerForm.labels.lastName": "What is your last name?"
}

There is also the pages namespace. This namespace is used for page specific translations. What comes to mind is metadata, things like the page title, page description,... Anything that is truly specific to a page can fit under this namespace.

{
  "pages.home.metadata.description": "Building ecological homes with the future in mind.",
  "pages.home.titles.pageTitle": "Home",
  "pages.about.metadata.description": "Homes of the future is a new brand started in 2023 and available for all your ecological building needs.",
  "pages.about.titles.pageTitle": "About"
}

For the common and components namespaces, there is a subdivision of namespaces:

buttons are for button texts.
labels are for single-line labels (e.g., labels next to an input field).
titles are for headers (e.g., title of a dialog).
messages are for multiline texts (e.g., paragraphs, dialog text, helper text).

This being said, you have reached the end of this blog. Coping with i18n can be hard sometimes, especially because the needs of the projects can change. I hope this guide will alleviate some of the pain that comes with i18n.

If you have any questions, feel free to contact me!

Enforcing front-end guidelines in an Angular project

Thomas King — Tue, 14 Nov 2023 09:36:46 +0000

The title of this blog might be a little deceiving, because only a part of it can actually be seen as enforcing guidelines. It’s more about how to make team members work more in sync with each other, making sure everyone is coding more or less the same, like a tiny hive mind. Having those pull requests in which no one has to make comments like “no excessive empty lines”, “remove unused imports” or “clean up console.logs”.

To try to achieve this, we can set up the Angular project in such a way that team members are more or less forced to write and commit code as the project demands it. Here are a few tips and tricks for setting up an Angular project to help your team be more in sync.

1. Communication

It's actually a no-brainer, but I see a lack of communication too often; that's why it comes first. The first thing you should do is ask other team members. Especially if you're new to the team, ask:

where documentation can be found.
whether you need specific access.
if there are any guidelines to be followed.
whether someone can go through the project with you (project structure, special things, etc.).
what the rules and guidelines are for committing or pushing code.
…

2. Visual Studio code

You can’t force your team members to use a certain IDE, but Visual Studio Code is free and provides a good development experience. If your team members all share the same IDE, it’s better they share a common set of settings, extensions,...

Recommended extensions

Update or add extensions.json in the .vscode folder. This way, all team members are going to use the same set of extensions that are required for the project.

Note: VS Code only suggests downloading these recommended extensions; it is still up to the team member to install them (however recommended)!

{
  // For more information, visit: <https://go.microsoft.com/fwlink/?linkid=827846>
  "recommendations": [
    "angular.ng-template",
    "johnpapa.angular-essentials",
    "streetsidesoftware.code-spell-checker",
    "yzhang.markdown-all-in-one",
    "stylelint.vscode-stylelint"
  ]
}

These are my five recommended extensions:

Angular Language Service (angular.ng-template): provides a rich editing experience for Angular templates, both inline and external templates.
Angular Essentials (johnpapa.angular-essentials): all the essential extensions needed for Angular development.
Code Spell Checker (streetsidesoftware.code-spell-checker): make sure any spelling errors are visible and can be caught.
Markdown All in One (yzhang.markdown-all-in-one): for any markdown related matters. Especially useful for previewing those README.md’s!
Stylelint (stylelint.vscode-stylelint): immediately see stylelint errors in VS Code. If you're using SCSS files, be sure to add it to the language ids to be validated in the settings of the Stylelint extension.

Project settings

Add a settings.json file to the project (under the .vscode folder) that will use project specific settings in Visual Studio Code. This is the settings.json I usually use (depending on the project):

{
  "editor.codeActionsOnSave": {
    "source.organizeImports": true
  },
  "editor.defaultFormatter": "esbenp.prettier-vscode",
  "editor.formatOnSave": true,
  "editor.lineNumbers": "on",
  "editor.trimAutoWhitespace": true,
  "editor.tabSize": 2
}

These settings will:

sort imports and remove unused imports on save.
use the Prettier extension as the default formatter when formatting a file.
format the file on save.
show line numbers.
automatically trim whitespace.
set the editor tab size to 2 spaces.

Note: Prettier should be installed as part of the Angular Essentials extension pack.

Add project snippets

Add snippets to your project that help people write code faster and more efficiently, but in a specific way. You can do so by creating a snippets file in the .vscode folder. You can choose the name, as long as it ends with the extension .code-snippets. An example snippet may be a snippet for a Given-When-Then code block for unit tests:

{
  "Given-When-Then": {
  "scope": "typescript",
  "prefix": "gwt",
  "body": [
   "describe('$0', () => {",
      "\tbeforeEach(() => {",
   "\t}",
      "\tdescribe('$1', () => {",
      "\t\tit('$2', () => {",
   "\t\t});",
   "\t});",
   "});"
  ],
  "description": "Create a Given-When-Then block"
 }
}

There are many extensions that provide snippets out of the box. Have a look in the extensions store of VS Code and update each team member to make use of these snippets.

3. Prettier

Prettier is a code formatter that formats your code to a uniform, consistent style. That way, the code looks the same for everyone using the same Prettier settings.

As stated earlier, the Prettier extension for VS Code itself should already be installed by the Angular Essentials extension pack.

For formatting inside the project, install Prettier in the project via NPM:

npm install prettier -D

Create a .prettierrc.json file in the root of the project that will contain the Prettier configuration. You can use the default that came installed with Prettier or use this one (note: make sure the tabWidth is the same as the one you defined in the settings.json!):

{
  "tabWidth": 2,
  "useTabs": false,
  "singleQuote": true,
  "semi": true,
  "bracketSpacing": true,
  "arrowParens": "avoid",
  "trailingComma": "es5",
  "bracketSameLine": true,
  "printWidth": 80,
  "endOfLine": "auto"
}

What’s the difference with writing the configuration in here instead of in settings.json (e.g., “prettier.tabWidth”: 2)? It’s essentially the same; when you format the file, it will look for the Prettier configuration, but the .prettierrc.json will take precedence over the settings in settings.json. I like using a separate .prettierrc.json file because 1) it clearly shows the Prettier configuration in one file, and 2) if the team would step away from VS Code, the Prettier configuration can be reused.

Add a .prettierignore file (recommended by Prettier itself) that contains the same content as the .gitignore (unless you have some exceptions of your own).

4. Linting with ESlint

Linting is a process that will check your code for potential errors. Quite essential in my opinion! Not only can you check for potential errors, but you can also enforce a certain set of rules (guidelines) with linting.

Add linting for the Angular project:

ng add @angular-eslint/schematics

This will install the @angular-eslint/schematics package from NPM and will create an .eslintrc.json file that will contain the linting configuration. It will also update your angular.json with a new architect target “lint” and create a new script line in your package.json called “lint”.

With linting rules, you can enforce a common set of coding standards. When running the @angular-esling/schematics schematic, it will include a .eslintrc.json file in your project. It will already extend some rules for ts and html files from the recommended ones. For TypeScript files:

eslint:recommended is ESLint's inbuilt "recommended" configuration; it turns on a small, sensible set of rules that lint for well-known best practices. See https://eslint.org/docs/latest/rules/
plugin:@typescript-eslint/recommended is similar to eslint:recommended, except it turns on TypeScript-specific rules. See https://typescript-eslint.io/rules/
plugin:@angular-eslint/recommended, see https://github.com/angular-eslint/angular-eslint/blob/main/packages/eslint-plugin/src/configs/README.md#recommended
plugin:@angular-eslint/template/process-inline-templates

For HTML files:

plugin:@angular-eslint/template/recommended
plugin:@angular-eslint/template/accessibility

The template specific rules can be seen here: https://github.com/angular-eslint/angular-eslint/tree/main/packages/eslint-plugin-template#angular-eslinteslint-plugin-template

The schematic by default includes two rules for TS files:

"rules": {
"@angular-eslint/directive-selector": [
    "error",
    {
      "type": "attribute",
      "prefix": "app",
      "style": "camelCase"
    }
  ],
  "@angular-eslint/component-selector": [
    "error",
    {
      "type": "element",
      "prefix": "app",
      "style": "kebab-case"
    }
  ]
}

This will give a linting error when you apply a different prefix for a directive or component other than “app” (it will also check for the correct casing). It is recommended to use a prefix specific for your application (see https://angular.io/guide/styleguide#component-custom-prefix).

You are already using the recommended linting rules, which is good! Most of the time, I add some more specific rules for the project, such as:

allow no console.logs.
enforce no unused imports (if the developer has the organize imports on save action disabled for some reason). For this, I use the [eslint-plugin-unused-imports](<https://www.npmjs.com/package/eslint-plugin-unused-imports>) package.
use triple equals.
enforce naming conventions, such as making boolean variables sound more boolean-like by prefixing is, has, can, etc.
…

An example .eslintrc.json file looks like this:

{
  "root": true,
  "ignorePatterns": ["projects/**/*"],
  "plugins": ["unused-imports"],
  "overrides": [
    {
      "files": ["*.ts"],
      "extends": [
        "eslint:recommended",
        "plugin:@typescript-eslint/recommended",
        "plugin:@angular-eslint/recommended",
        "plugin:@angular-eslint/template/process-inline-templates"
      ],
      "rules": {
        "@angular-eslint/directive-selector": [
          "error",
          {
            "type": "attribute",
            "prefix": "toh",
            "style": "camelCase"
          }
        ],
        "@angular-eslint/component-selector": [
          "error",
          {
            "type": "element",
            "prefix": "toh",
            "style": "kebab-case"
          }
        ],
        "@typescript-eslint/explicit-function-return-type": "error",
    "@typescript-eslint/naming-convention": [
      "error",
          {
    "selector": "variable",
    "types": ["boolean"],
    "format": ["PascalCase"],
    "prefix": ["is", "should", "has", "can", "did", "will"]
      }
    ],
        "@angular-eslint/prefer-on-push-component-change-detection": "error",
        "@typescript-eslint/no-unused-vars": "off",
        "unused-imports/no-unused-imports": "error",
        "unused-imports/no-unused-vars": [
          "warn",
          {
            "vars": "all",
            "varsIgnorePattern": "^_",
            "args": "after-used",
            "argsIgnorePattern": "^_"
          }
        ],
        "brace-style": ["error", "1tbs"],
        "eqeqeq": "error",
        "no-else-return": "error",
        "no-trailing-spaces": "error",
        "no-var": "error",
        "object-shorthand": ["error", "properties"],
        "prefer-const": "error",
        "prefer-object-spread": "error",
        "prefer-template": "error",
        "no-console": ["error", { "allow": ["warn", "error"] }]
      }
    },
    {
      "files": ["*.html"],
      "extends": [
        "plugin:@angular-eslint/template/recommended",
        "plugin:@angular-eslint/template/accessibility"
      ],
      "rules": {}
    }
  ]
}

There are so many linting rules you can apply. Use the ones that work for your project and team. Caution though, because some linting has an impact on your code, so make sure you know what you’re doing! If you’re not certain about the impact of a certain rule, set the severity to “warn” instead of “error” and see how many lines it will impact by running the linter.

Also, have a look at all the Eslint plugins that already exist. They might have a set of rules that you can use for your project. Examples:

eslint-plugin-jest: https://www.npmjs.com/package/eslint-plugin-jest. Linting rules for your Jest unit tests.
@ngrx/eslint-plugin: https://www.npmjs.com/package/@ngrx/eslint-plugin. Linting rules when using NGRX.

Run ng lint --fix to run the linting for your project and potentially autofix all problems.

Linting (S)CSS files

Linting can be applied not only to TypeScript and HTML files but also to your stylesheets. To lint stylesheets, you can use Stylelint. Most of the time, the projects I work on are a bit more complex, so they use SCSS. This is possible with Stylelint by installing an SCSS configuration:

npm install --save-dev stylelint stylelint-config-standard-scss

Create a .stylelintrc.json file in the root of the project that will contain all the rules that will apply to your stylesheet. You can extend the recommended rules but also customize them. When extending the recommended rules, chances are all your existing stylesheets will contain errors. For starters, add the rules that give errors to the list of rules and set them to null to ignore them for now. This will give you the chance to evaluate the importance of that rule.

An example .stylelintrc.json file:

{
  "extends": "stylelint-config-standard-scss",
  "rules": {
    "no-empty-source": null
  }
}

You can take a look at the different rules here:

Stylelint rules: https://stylelint.io/user-guide/rules
SCSS rules (from the standard config): https://github.com/stylelint-scss/stylelint-config-standard-scss/blob/main/index.js

Next, update the script in your package.json that performs the linting, so it will also include the linting of stylesheets:

"lint": "ng lint && npx stylelint \"**/*.scss\""

Similar to Prettier, also create a .stylelintignore file in the root of the project to ignore specific files. It’s ok to copy the contents of the .gitignore file into this one.

5. Husky

Add Husky hooks to prevent team members from committing or pushing faulty code.

npx husky-init && npm install

Note: If you get the error The token '&&' is not a valid statement separator in this version., just run the commands separately.

This will create a pre-commit hook file from Husky. It will originally contain the command npm test. I suggest updating this with npm run lint. Running tests on a small project will be fast, but as the project grows, it will take longer. So committing code will get cumbersome. Therefore, I recommend linting the project before committing as a first check.

#!/usr/bin/env sh
. "$(dirname -- "$0")/_/husky.sh"


npm run lint

Create a pre-push hook file that will run the unit tests before pushing the code to Git.

npx husky add .husky/pre-push "npm run test"

This will be done only after a few commits, so it is ok that this takes a bit longer.

6. Use conventional Commits

Conventional Commits is a specification for writing standardized commit messages. This way, the changes throughout your code are documented in a more consistent and human-readable way. A Conventional Commit message looks like the following:

<type>[optional scope]: <description>


[optional body]


[optional footer(s)]

Example:

fix: loading spinner not working on home page

The benefits of using these types of commit messages are:

Semantic Versioning (SemVer) compatibility: Conventional Commits are designed to work well with Semantic Versioning. By following a specific format for commit messages, it becomes easier to automatically determine the version number based on the type of changes introduced (e.g., feature, fix, breaking change).
Automated release notes: since Conventional Commits provide a structured and standardized way of writing commit messages, tools can automatically generate release notes from the commit history. This makes it easier to communicate changes to users, contributors, and other stakeholders.
Clearer commit history: Conventional Commits encourage a consistent and clear commit message format. This helps in creating a more readable and understandable commit history, making it easier for team members to track changes and understand the evolution of the codebase.
Enables automation: many CI/CD (Continuous Integration/Continuous Deployment) and release management tools can take advantage of Conventional Commits to automate tasks such as versioning, changelog generation, and release workflows. This reduces the manual effort required for managing the release process. E.g., Jenkins and Azure DevOps provide such extensions and plugins.
Collaboration and communication: by using a common commit message format, team members can easily understand the nature of changes made in the codebase. This improves collaboration and communication among team members, as everyone follows a consistent style when documenting changes.
Facilitates maintenance: over time, projects can grow complex, and maintaining a clear history becomes crucial. Conventional Commits make it easier to navigate and understand the commit history, aiding in maintenance tasks such as bug tracking, troubleshooting, and identifying when specific features were introduced or bugs were fixed.
Integration with tooling: many development tools and services support Conventional Commits out of the box or through plugins. This includes version control systems, CI/CD pipelines, code review tools, and more. Utilizing Conventional Commits enhances integration with these tools.

Something important to keep in mind when working with commits is to keep them small. With small commits, it will be easier to come up with a good description for the Conventional Commit message.

commitlint

If you agree on using Conventional Commits throughout your project, that's great! Even greater would be that they could be enforced. This can be done by using commitlint and more specifically with the configuration for Angular: @commitlint/config-angular.

Commitlint checks if your commit messages meet the conventional commit format. This, in combination with Husky, will ensure that the team follows the Conventional Commits format.

Run the following in your terminal to install commitlint with the Angular configuration:

npm install --save-dev @commitlint/config-angular @commitlint/cli

Then create a .commitlintrc.json file in the root of your project which will contain the configuration for commitlint:

{ 
  "extends": ["@commitlint/config-angular"] 
}

This configuration file for commitlint will by default extend from @commitlint/config-angular.

Now to enforce this with Husky, let's add a hook:

npx husky add .husky/commit-msg "npx --no -- commitlint --edit ${1}"

A commit-msg hook will be created that will process your commitlint configuration to check for a valid commit message format. Now if you want to commit with a commit message that is not valid (e.g., "my faulty commit"), the commit will fail, and the output message would read:

⧗   input: my faulty commit
✖   subject may not be empty [subject-empty]
✖   type may not be empty [type-empty]


✖   found 2 problems, 0 warnings

With the .commitlintrc.json file, you could have your own rules for commit message formatting. For a full list of rules, see here.
E.g., you want to allow the type "hotfix" next to the existing types ("build", "feat",...). You could do so by adding the rule type-enum:

{
  "extends": ["@commitlint/config-angular"],
  "rules": {
    "type-enum": [
      2,
      "always",
      [
        "hotfix",
        "build",
        "chore",
        "ci",
        "docs",
        "feat",
        "fix",
        "perf",
        "refactor",
        "revert",
        "style",
        "test"
      ]
    ]
  }
}

Note: The "2" is the level. Possible values are 0 (hint), 1 (warning), and 2 (error).

It is however recommended to follow the Conventional Commit specification as closely as possible. If you do have any exceptions, make sure the team is aware of them (even new team members that recently joined).

7. Keep README.md up-to-date

Keep the README.md file of the project up-to-date. Use this as a starting point for every new team member starting with the project. Even better would be to add a README.md to each folder that might require additional information and point to the README in the base README of the project. You can link to other markdown files by using the hyperlink syntax, e.g., [a relative link](shared/README.md).

TLDR;

Communicate with your team members.
Add recommended extensions, project settings and snippets for VS Code.
Add Prettier.
Add linting.
Add Husky hooks to enforce rules on commit or push.
Use Conventional Commits.
Keep the README.md up-to-date.

If you have any questions, feel free to contact me!

DEV Community: Thomas King

Easily create mock data for unit tests 🧪

Bonus: adding Faker

Which Angular components should you create? 🤔

List

Cards

Table

Form-related

Form field

Form actions

Validation summary

Menu

Skeleton

Pickers

Language picker

Municipality picker

Country picker

Gender picker

Confirm dialog

Unauthenticated

Back button

Login

User menu

Layout

Success

Counter

Conclusion

The big Angular UI library comparison 📚

List of components

Accordion

Alert

Autocomplete (Typeahead)

Avatar

Badge

Barcodes

Block UI

Breadcrumb

Button

Button group

Calendar

Card

Carousel

Chart

Chat

Checkbox

Chips

Collapse

Color picker

Context menu

Data view

Date picker

Diagram

Divider

Dock

Drag & drop

Dropdown (Select)

Dropdown button

Editor

File upload

Filter

Floating button

Floating label

Gauge

Icon

Image editor

Image preview

Input

Input group

Input mask

Label

List view

Listbox

Map

Menu

Modal (Dialog)

Multiselect

Paginator

Pdf viewer

Pivot table

Popover

With `mergeMap`

With `switchMap`

With `concatMap`

With `exhaustMap`