We can build something like that using Angular directives. We’ll use all the latest features of Angular in this experiment.

Let's see how we can build this.

We can actually do this in multiple ways. We are going to build this using directives. The way we are going to do this is by taking a very generic approach. This way, we can reuse the logic for things like resizing elements or sidebars, etc.

Scrubber Directive - the core functionality

The main logic of the input can be extracted and encapsulated into a directive. The main objective is to listen to the mouse events and then translate the mouse movements into a usable value. To explain in a bit more detail:

1. When the user clicks the mouse (mousedown event).

2. We start listening to the mouse movements (mousemove events) and use that info to translate it into usable values.

3. When the user releases the click, we stop the listener (mouseup event).

We will use rxjs to simplify the logic a bit.

Here's how the pseudocode would look.

const mousedown$ = fromEvent<MouseEvent>(target, 'mousedown');
const mousemove$ = fromEvent<MouseEvent>(document, 'mousemove');
const mouseup$ = fromEvent<MouseEvent>(document, 'mouseup');

let startX = 0;
let step = 1;

mousedown$
  .pipe(
     tap((event) => {
       startX = event.clientX; // Initial x co-ordinate where the mouse down happened
    }),
    switchMap(() => mousemove$.pipe(takeUntil(mouseup$))))
  .subscribe((moveEvent) => {
    const delta = startX - moveEvent.clientX;
    const newValue = Math.round(startValueAtTheTimeOfDrag + delta);
  });

Looking at the above code, it should be pretty clear what is happening. We basically save the initial clientX value, which is the position of the click on the X axis. Once we have that info, when the user moves the mouse, we can calculate the delta from the initial start position and the current X position.

We can further add more customizations like:

1. Sensitivity - drag distance to final value will be decided by sensitivity. Higher sensitivity values mean the final value will be big even if the movement is not that much.

2. Step - sets the stepping interval when moving the mouse. If the step value is 1, the final value is incremented/decremented in steps of 1.

3. Min - minimum value that will be emitted.

4. Max - maximum value that will be emitted.

Here’s how the final directive would look:

@Directive({
  selector: "[scrubber]",
})
export class ScrubberDirective {
  public readonly scrubberTarget = input.required<HTMLDivElement>({
    alias: "scrubber",
  });

  public readonly step = model<number>(1);
  public readonly min = model<number>(0);
  public readonly max = model<number>(100);
  public readonly startValue = model(0);
  public readonly sensitivity = model(0.1);

  public readonly scrubbing = output<number>();

  private isDragging = signal(false);
  private startX = signal(0);
  private readonly startValueAtTheTimeOfDrag = signal(0);
  private readonly destroyRef = inject(DestroyRef);
  private subs?: Subscription;

  constructor() {
    effect(() => {
      this.subs?.unsubscribe();
      this.subs = this.setupMouseEventListener(this.scrubberTarget());
    });

    this.destroyRef.onDestroy(() => {
      document.body.classList.remove('resizing');
      this.subs?.unsubscribe();
    });
  }

  private setupMouseEventListener(target: HTMLDivElement): Subscription {
    const mousedown$ = fromEvent<MouseEvent>(target, "mousedown");
    const mousemove$ = fromEvent<MouseEvent>(document, "mousemove");
    const mouseup$ = fromEvent<MouseEvent>(document, "mouseup");

    return mousedown$
      .pipe(
        tap((event) => {
          this.isDragging.set(true);
          this.startX.set(event.clientX);
          this.startValueAtTheTimeOfDrag.set(this.startValue());
          document.body.classList.add("resizing");
        }),
        switchMap(() =>
          mousemove$.pipe(
            takeUntil(
              mouseup$.pipe(
                tap(() => {
                  this.isDragging.set(false);
                  document.body.classList.remove("resizing");
                })
              )
            )
          )
        )
      )
      .subscribe((moveEvent) => {
        const delta = moveEvent.clientX - this.startX();
        const deltaWithSensitivityCompensation = delta * this.sensitivity();

        const newValue =
          Math.round(
            (this.startValueAtTheTimeOfDrag() +
              deltaWithSensitivityCompensation) /
              this.step()
          ) * this.step();

        this.emitChange(newValue);
        this.startValue.set(newValue);
      });
  }

  private emitChange(newValue: number): void {
    const clampedValue = Math.min(Math.max(newValue, this.min()), this.max());
    this.scrubbing.emit(clampedValue);
  }
}

How to use the scrubber directive

Now that we have the directive ready, let’s see how we can actually start using it.

<div #scrubberTarget 
     [scrubber]="scrubberTarget"
     [startValue]="this.roundedNumericValue()"
     [min]="0"
     [max]="100"
     [step]="2"
     [sensitivity]="0.2"
     (scrubbing)="this.updateValue($event)">
</div>

Currently, we have marked the scrubberTarget input as input.required, but we can actually make it optional and automatically use the elementRef.nativeElement of the host of the directive, and it would work the same. The scrubberTarget is exposed as an input in case you want to set a different element as the target.

We also add a class resizing to the body so that we can set the resize cursor correctly.

.resizing {
  cursor: ew-resize;
  touch-action: none;
  -webkit-user-select: none;
  user-select: none;
}

We have used effect to start the listener, this would make sure that when in case target element changes, we set the listener on the new element.

See it in action

We have made a super simple Scrubber directive in Angular which can help us build input fields similar to what Figma has. Makes is super easy for user to interact with numeric inputs.

Code & Demo

https://stackblitz.com/edit/figma-like-number-input-angular?file=src%2Fscrubber.directive.ts

Connect with me

• Twitter

• Github

• Linkedin

Do add your thoughts in the comments section. Stay Safe ❤️

So today we are going to see exactly how I created a reusable calendar component in Angular.

Getting started

We are going to be using the latest and greatest Angular version 18.0.0 (at the time of writing this blog). We are going to use standalone component, along with signals. One important dependency that we are going to add is date-fns library, which is a modern JavaScript date utility library. It provides the most comprehensive, yet simple toolset for working with dates.

Let's start by creating the component. I'm just going to add the bare minimum template code. You can get the full template code from the source code link at the end of this blog.

Building the calendar component

@Component({
  selector: 'app-calendar',
  standalone: true,
  template:`
    <div>
      <header>
         <!---- Calendar month be displayed here -->
         <h1></h1>
         <div>
            <button>Today</button>
            <button>Previous</button>
            <button>Next</button>
         </div>
      </header>

      <div>

        <!---- Calendar days be displayed here -->
        <header class="grid grid-cols-7">
          @for (item of this.dayNamesEnriched; track item.dayName) {
              <div>
                {{ item.dayName }}
              </div>
          }
        </header>
      </div>
    </div>
  `
})
export class CalendarComponent {
  public markers = input<CalendarMarkerData[]>([]);
  public markerTpl = input<TemplateRef<{ $implicit: CalendarMarkerData[] }>>();

  readonly #dayNames = ['Sun', 'Mon', 'Tue', 'Wed', 'Thu', 'Fri', 'Sat'];
  protected readonly dayNamesEnriched = this.#dayNames.map((dayName) => ({
    dayName: dayName,
    isToday: dayName === format(startOfToday(), 'eee'),
  }));

  protected currentDate = signal(startOfToday());
  protected currentMonthWithYear = computed(() =>
    format(this.currentDate(), 'MMMM yyyy'),
  );

  protected readonly startDateOfSelectedMonth = computed(() => {
    return startOfMonth(this.currentDate());
  });
  protected readonly endDateOfSelectedMonth = computed(() => {
    return endOfMonth(this.currentDate());
  });

  protected readonly days = computed(() => {
    return eachDayOfInterval({
      start: this.startDateOfSelectedMonth(),
      end: this.endDateOfSelectedMonth(),
    });
  });

  protected readonly daysEnriched = computed(() => {
    return this.days().map((day, i) => {
      return {
        day: day,
        isToday: isEqual(day, startOfToday()),
        colStartClass: i === 0 ? this.#COL_START_CLASSES[day.getDay()] : '',
        markers: this.#markersMap().get(this.getMarkerMapKey(day)) || [],
      };
    });
  });

  readonly #COL_START_CLASSES = [
    '',
    'col-start-2',
    'col-start-3',
    'col-start-4',
    'col-start-5',
    'col-start-6',
    'col-start-7',
  ];
}

export interface CalendarMarkerData<Data = any> {
  date: Date;
  data: Data;
}

This is all the code that is required for the calendar component. We have a header section where we display the month and year, along with buttons to navigate to the previous and next month. We also have a section where we display the days of the week. We are using the date-fns library to get the days of the week.

Adding markers to the calendar

Now that we have the basic calendar component, we can add markers to the calendar. Markers are used to show some data on a specific date. For example, if you have a subscription on a specific date, you can show a marker on that date. The marker data is passed to the calendar component as an input. We are using the input signal to pass the marker data to the calendar component.

The consumer has full control of how the markers look, making the calendar component highly customizable.

@Component({
  selector: 'app-main',
  standalone: true,
  template: `
  <div class="p-6">
    <app-calendar [markers]="this.markers" [markerTpl]="markerTpl">
    </app-calendar>
  </div>

    <ng-template #markerTpl let-data>
      <div class="flex items-center justify-center">
        <ul class="flex flex-col gap-1">
          @for(marker of data; track marker){
            <li class="flex bg-blue-100 text-center text-xs rounded-md px-2 py-1 justify-center items-center">{{marker.data.title}}</li>
          }
        </ul>
      </div>
    </ng-template>
  `,
  imports: [CalendarComponent],
})
export class MainComponent {
  markers: CalendarMarkerData[] = [
    {
      date: addDays(new Date(), 1),
      data: {
        title: 'Netflix',
      },
    },
    {
      date: addDays(new Date(), 1),
      data: {
        title: 'Google One',
      },
    },
    {
      date: addDays(new Date(), 5),
      data: {
        title: 'Youtube Premium',
      },
    },
  ];
}

We defined the marker template in the consumer and passed it to the calendar component. The calendar component will render the markers using the template provided by the consumer.

You can further style it to your needs, here’s some screenshots of how I did it:

Demo

Stackblitz:

https://stackblitz.com/edit/angular-calendar-with-date-fns

Connect with me

• Twitter

• GitHub

• LinkedIn

• Portfolio

Read Here: Deploy Node.js applications on a VPS using Coolify

In this article, we are going to see how to deploy a similar Node.js application using Dockerfile. This is a common way to deploy applications. We create a Dockerfile, which can build an image and the image can be deployed to any server.

Deploy using Dockerfile

So, for this example, we are going to take another node application built using:

• Fast and low overhead web framework, for Node.js | Fastify

• TypeScript

• Prisma | Simplify working and interacting with databases

• PostgreSQL

The difference here is that we have to create a Dockerfile for our application.

Setting up the PostgreSQL database

Under Project > Environment > Resources > + New > Databases, you'll be able to see PostgreSQL. Start by adding a database into your project.

All the necessary information is prefilled, and we are good to go. Clicking on Start will spin up a docker container. Wait for the process to complete and once done, the status would say Running.

Deploying The Node Application

For deploying our node application, we start by adding a new resource to your project by going to Project > Environment > Resources > + New > Public Repository

https://github.com/adisreyaj/notes-api-fastify

Make sure you have selected Dockerfile under Build Pack option.

Here's the Dockerfile of our sample app:

FROM node:21-bullseye-slim

ENV DATABASE_URL=${DATABASE_URL}
ENV PORT=${PORT}

WORKDIR /

COPY package*.json ./
COPY . .
ADD prisma .

RUN npm ci
RUN npm run build
RUN npx prisma migrate deploy

EXPOSE ${PORT}

CMD ["npm", "start"]

Configure environment variables!

We need to configure the environment variables that are consumed by our application. Navigate the Environment Variables page and start adding the following variables.

Copy the Postgres URL (internal) from the database configuration page.

postgres://postgres:VrKrSbxvicsQR45w0XTt@e34ds48g44o:5432/postgres

Add the following variables: DATABASE_URL

The value provided in the Ports Exposes will be used by the application.

Deploy the application!

Once we have configured the env variables, we can go ahead a Deploy the application. Coolify shows the logs of the process, we can click on Show Debug Logs to see detailed logs.

Once the application is deployed successfully, we can view the logs of the application under the Logs tab.

Feel free to reach out to me if you are having trouble in deploying using above mentioned steps. Happy to help.

Troubleshoot

Prisma Migrate Failed

If you are getting the following error:

ERROR: failed to solve: process "/bin/sh -c npx prisma migrate deploy" did not complete successfully.

Make sure that you have provided the correct database URL and also Build Variable is checked.

Health Check Fail

Make sure the Health Checks configuration is correct. If you don't want to run health checks, make sure to turn it off.

Connect with me

• Twitter

• GitHub

• LinkedIn

• Portfolio

Managed offerings make it extremely easy to deploy applications on the Internet. They eliminate the hassle for us, but this convenience comes at a cost. Recently there has been a lot of noise around the self-hosting vs managed hosting.

My VPS configuration

I've been hosting all my APIs for applications like Flagsy, Flare, Compito, etc on a VPS with the following configuration:

1. 1 vCPU

2. 2GB RAM

3. 40GB Storage

4. Ubuntu

Worked well for my use case. The VPS cost me around $7 per month. I've now shifted to a new VPS from Oracle which provides a great config in their free tier.

1. 4 vCPU

2. 24GB RAM

3. ARM Based

4. Ubuntu

Deployment workflow before Coolify

For all these years, I've been using GitHub Actions with a custom workflow for deploying applications to the server. The GitHub Action workflow is as follows:

1. Build the Application.

2. Package the contents into an artifact (.tar file).

3. Send the artifact to the remote server using rsync (ref: How to use Rsync to Sync Local and Remote Directories)

4. SSH into the remote server.

5. Extract the contents of the .tar file.

6. Install Dependencies.

7. Run the application using PM2 (ref: Process manager for Node.js)

Deployment using Coolify

When I came across Coolify, I thought of giving it a try. I am aware of Dokku, but I never really tried it because it doesn't have a UI. I work primarily as a UI developer, so having a nice UI to work with is a plus for me.

Coolify is an open source & self-hostable Heroku / Netlify / Vercel alternative. Built by Andras Bacsai (@heyandras)

It's surprisingly good. I did feel a bit lost when I first started trying it out. Eventually, everything fell into place, and I've moved all my previously hosted node applications to use Coolify instead.

Getting started with Coolify

To get started, you need a server, it can be a VPS, a Raspberry Pi, or any other server that you have SSH access to.

Coolify comes with a pretty neat one-click installation script which makes the installation super easy.

Minimum requirements for Coolify

• 2 CPUs

• 2 GB memory

• 30+ GB of storage for the images.

VPS offerings that I found to be good:

• Hetzner

• OVH

I've used both of these and didn't have any issues with them.

Installing Coolify

The first step is to SSH into your server.

ssh <username>@<ip_address>

Once you are inside the VPS. Enter the below command to install Coolify

curl -fsSL https://cdn.coollabs.io/coolify/install.sh | bash

If you get an error saying: Please run as root using the command below:

curl -fsSL https://cdn.coollabs.io/coolify/install.sh | sudo bash

Once the installation is complete, you'll get a link to the Coolify dashboard. When you visit the link (Eg: http://<server_ip>:8000), you'll be asked to register yourself.

Localhost vs Remote Server

On completion of registration, we will come to this screen where we need to choose whether we want everything to be on one server or not.

I am using the Localhost mode. In the next step, server requirements are validated. Once validation is complete, we can get started by creating our first project.

Resources

We can host multiple resources in the server like Applications, Databases and Services. Each of these are called as a resource in Coolify.

Coolify supports deployment of applications from your private GitHub repo or any public repo. You can also deploy using Docker.

When it comes to databases, we have out of the box support for popular databases like PostgreSQL, MySQL, Mongo, Redis etc.

Deploy Node application using Coolify

There are couple of ways in which we can deploy a node.js application. We will be looking at how to deploy a node application on Coolify using Nixpacks.

Deploy using Nixpacks

This one will be the easiest way to deploy any node application using Coolify. The whole process is pretty straight forward.

Nixpacks takes a source directory and produces an OCI compliant image that can be deployed anywhere.

In simpler terms, Nixpacks will analyse the source folder and automatically create a Dockerfile for us. We don't have to know anything about docker.

We are going to be building a super simple Notes API using:

• Hono - Ultrafast web framework for the Edges

• TypeScript

• MySQL

Setting up the MySQL database

Under Project > Environment > Resources > + New > Databases, you'll be able to see MySQL. Start by adding a database into your project.

All the necessary information is prefilled, and we are good to go. Clicking on Start will spin up a docker container. Wait for the process to complete and once done, the status would say Running.

Deploying The Node Application

For deploying our node application, we start by adding a new resource to your project by going to Project > Environment > Resources > + New > Public Repository

Continue till we are asked to provide the URL of the repo:

https://github.com/adisreyaj/notes-api

Once Coolify loads the repo, we'll be asked to create a new application. We choose Nixpacks as the Build Pack and use 3000 for the port to run the app on.

Configure environment variables!

We need to configure the environment variables that are consumed by our application. Navigate the Environment Variables page and start adding the following variables.

Copy the MySQL URL(Public) in case you are using Prisma or copy the MySQL URL(Internal) URL in other cases.

mysql://mysql:BfwAmHtmTokbm70fUoFcsL7obNMPCFcW@vww348go4:3306/default

We can split the database URL into the below environment variables:

DATABASE_HOST=vww348go4
DATABASE_NAME=default
DATABASE_PASSWORD=BfwAmHtmTokbm70fUoFcsL7obNMPCFcW
DATABASE_PORT=3306
DATABASE_USER=mysql
PORT=3000

You can either add all of these variables at once using Developer View or create them individually.

Deploy the application!

Once we have configured the env variables, we can go ahead a Deploy the application. Coolify shows the logs of the process, we can click on Show Debug Logs to see detailed logs.

Once the application is deployed successfully, we can view the logs of the application under the Logs tab.

You should be able to visit the domain provided and see the app live.

Troubleshooting

Providing custom commands

If you think that Nixpacks picked wrong commands for install, build, or start, you can customize it in the Configuration > General section.

Database not reachable

If you see any errors related to database not reachable, make sure to double check the env variables and make sure they are correct.

Also, if you are using Prisma or other libraries which might access database at build time, make sure to mark the environment variables as Build Variable.

For Prisma with Nixpacks, we need to make the database publicly accessible over the internet.

Feel free to reach out to me if you are having trouble in deploying using above mentioned steps. Happy to help.

Follow up

If you want to deploy Node.js apps using Dockerfile instead, visit this blogpost:

Deploy Node.js applications on a VPS using Coolify with Dockerfile (sreyaj.dev)

Connect with me

• Twitter

• GitHub

• LinkedIn

• Portfolio

Dynamic Card List Component

The component should be dynamic enough to render different designs while maintaining a common structure. The consumer should be able to use the component and provide just the config and a data source, the rest is all gonna be taken care of by our dynamic card list component.

For table-like cards, if you want to render display different data in different designs; after a point, it becomes very difficult with dedicated card lists for each of the use cases. Having a single card list component that is dynamic enough to render a wide variety of designs would make things much easier.

Features

• Highly customizable 🧱

• Re-usable ♻️

• Easy to use 🔌

• Less boilerplate code to maintain 🛠️

• Consistency in design 📐

Concepts

There are a couple of concepts that we use to build this out. We also make good use of Angular's strong Dependency Injection (DI) system. We'll see how we can provide custom components and dynamically create and attach them to the view. We use concepts like Dynamic Component Creation, Injectors, Injection Tokens, etc.

Renderers

So if we consider the card like a table, then the columns are where we display the data. So each of these columns can display different types of information like text, images, buttons, etc. So we can have different renderers for each of these types. For example, we can have a text renderer that will render text, an image renderer that will render an image, etc.

Core Renderers

We will have some core renderers which will be used by default. For example,

• Text Renderer

• Badge Renderer

We can identify some common use cases for renderers and create components that become part of Core Renderers.

Custom Renderers

If there are use cases that are not covered by the core renderers, then we can create custom renderers. For example, we need to display a user's name with the profile picture. So we can create a custom renderer for this use case. Look at the NameWithAvatarColumnRendererComponent

Renderers Registry

So we need a way to keep track of the renderers that we will create and use in the application. Users can create a lot of custom renderers according to their use cases. We use a type to identify the renderer. So all the renders that are created should have a unique type. We can use this type type associated with them.

We use a Service as our registry (ColumnRenderersRegistryService). We expose a Map to store the type to renderer mapping. We expose two methods:

• registerRenderers to register renderers

• lookup to lookup a renderer by type

Registering Renderers

There are methods exposed to register default renderers and custom renderers. The default renderers are registered in the constructor of the sreyaj-exp-card-list.

export const registerDefaultRenderers = (): void => {
    registerCustomRenderers([
        TextColumnRendererComponent,
        BadgeColumnRendererComponent,
    ]);
};

export const registerCustomRenderers = (
    renderers: ListColumnRendererConstructor[]
): void => {
    const rendererLookupService = inject(ColumnRenderersRegistryService);
    rendererLookupService.registerRenderers(renderers);
};

We inject the ColumnRenderersRegistryService and use it to register the renderers.

Custom Decorator

We create a custom decorator called ListColumnRenderer to add some metadata information about the renderer component like its type which is the unique identifier of the renderer in the registry.

We could totally do this without a decorator, but we would have to manually set the type on each renderer component. It would look like this:

@Component()
export class TextColumnRendererComponent extends ListColumnRendererBase {
  public type = CoreListColumnRendererType.Text;
}

With the decorator, we just remove this explicit variable assignment. Also, the decorator helps us easily identify renderer components from normal components.

Class decorator is a function that receives the constructor as the argument. Since we want to pass in some arguments to the decorator itself we use a decorator factory.

export function ListColumnRenderer(
  metadata: ListColumnRendererMetadata
) {
  return (constructor: ListColumnRendererConstructor): void => {
    constructor.type = metadata.type;
  };
}

The default type of a Component is Type. For us, we have extra metadata so we say our components are of the type ListColumnRendererConstructor which is an extended Type with some additional properties like type (more can be added later).

export interface ListColumnRendererConstructor extends Type<unknown>,
    ListColumnRendererMetadata {}

export interface ListColumnRendererMetadata {
  type: string;
}

Implementation

Main Component

There is a main component sreyaj-exp-card-list which is the component the consumers will use. The component takes in two inputs:

1. columnConfig - An array of column config that is used to render each column.

2. dataSource - The data source which drives the component.

The column config is what drives the view part of the component. Here is how you define it:

[
  {
    id: "name",
    display: CustomRenderers.NameWithAvatar,
    width: 2
  },
  {
    id: "email",
    display: CoreListColumnRendererType.Text,
    width: 4
  }
]

The id is what connects the view and the data. The data source should contain an object with the keys mentioned id in the column config.

The display is the type of renderer. It can be a core renderer or a custom renderer. This key will be used to look up the corresponding renderer to be used for that particular column.

Inside the main component, it just loops through the columns:

<div>
  <sreyaj-exp-card-list-column-renderer [columnConfig]="column" [data]="item"></sreyaj-exp-card-list-column-renderer>
</div>

We pass the column information and the data for the column from the data source to a child component sreyaj-exp-card-list-column-renderer which takes care of dynamically creating and attaching the corresponding renderer to the view.

Attaching Renderers to the View

This magic happens in the sreyaj-exp-card-list-column-renderer component. This is how we do it:

if (!this.columnConfig || !this.data) {
  return;
}
// Get the corresponding renderer for the display type
const renderer = this.rendererLookupService.lookup(this.columnConfig?.display);
if (renderer) {
  // Dynamically create the component and pass the data with the help of Injection Token
  this.vcr.createComponent(renderer, {
    injector: Injector.create({
      providers: [
        {
          provide: COLUMN_RENDERER_DATA,
          useValue: this.data[this.columnConfig.id]
        }
      ],
      parent: this.parentInjector
    })
  });
}

If I were to breakdown what is happening inside the component:

1. Get the renderer corresponding to the type passed in the columnConfig.

2. Use ViewContainerRef to dynamically create the component using the createComponent method.

3. To the createComponent method, we pass the renderer class along with an injector that holds the data.

4. COLUMN_RENDERER_DATA injection token is provided the data for that particular column.

Inside a Renderer

Let's look at TextColumnRendererComponent which is part of the Core Renderers.

@Component({
  selector: "sreyaj-exp-text-column-renderer",
  template: `
    <div>
      {{ data }}
      <!-- Use the data here -->
    </div>
  `,
  standalone: true
})
@ListColumnRenderer({
  type: CoreListColumnRendererType.Text
})
export class TextColumnRendererComponent extends ListColumnRendererBase {}

The data property contains the data passed from the injector. Wondering how we get it? For that, let's look at ListColumnRendererBase :

export abstract class ListColumnRendererBase<ColumnDataType = unknown> {
  public static readonly type: CoreListColumnRendererType;
  // We inject the token here
  public readonly data: ColumnDataType =
    inject<ColumnDataType>(COLUMN_RENDERER_DATA);
}

We can see that the COLUMN_RENDERER_DATA InjectionToken is injected inside the class and so the component gets the value passed while creating the component. If we don't use the new inject method, it would look something like this:

@Component({
  selector: 'sreyaj-exp-text-column-renderer',
  template: `
    <div>
      {{ data }}
    </div>
  `,
  standalone: true,
})
export class TextColumnRendererComponent {
  constructor(@Inject(COLUMN_RENDERER_DATA) public data: unknown){}
}

References

The idea of this is taken from the OSS project called Hypertrace which is an Open source distributed tracing platform from Traceable (The company I'm currently working in).

The project has a table implementation that does exactly this. I've just used the same concept to create a card list instead of a table (also use standalone components).

The table is far more capable as it even takes care of sorting, pagination, etc. You can look at the codebase to get an idea of how the table is implemented.

Connect with me

• Twitter
• Github
• Linkedin
• Portfolio

Have any thoughts or questions? shoot'em below in the comments. Stay Safe ❤️

ments. Stay Safe ❤️

Angular CDK SelectionModel

Angular CDK comes with a lot of utilities and components that we can use to build our application. One such very useful utility is the SelectionModel utility that is part of the Collections utilities in Angular Material CDK.

SelectionModel is a utility for powering the selection of one or more options from a list. This model is used in components such as the selection list, table selections, and chip lists.

Understanding the API ℹ️

The Selection Model class comes with a lot of handy methods that make it super easy to maintain the state of selections. Here's how we can use it:

const selectionModel = new SelectionModel<string>();

The class constructor takes in these arguments:

1. multiple - whether we can select multiple items at a time (multi-select)
2. initiallySelectedValues - initial selection
3. emitChanges - Whether to emit changes (selectionModel.changed property)
4. compareWith - A method that can hold the logic for identifying if an item is selected.

Usage with all the arguments provided:

export interface Movie {
  id: number;
  name: string;
  year: string;
}
const selectionModel = new SelectionModel<Movie>(
  true, // <- multi-select
  [], // <- Initial selections
  true, // <- emit an event on selection change
  (otherValue, value) => otherValue.id === value.id // <- compare method which checks the id of the movie
);

We can provide a custom compareWith method to get if a checkbox is selected (selectionModel.isSelected() method). Here's how it's used internally:

  isSelected(value: T): boolean {
    if (this.compareWith) {
      for (const otherValue of this._selection) { // this._selection is a Set()
        if (this.compareWith(otherValue, value)) {
          return true;
        }
      }
      return false;
    }
    return this._selection.has(value);
  }

Building a Table with Selection 🛠️

Now let's use the selection model to build a table with ability to select a row and also have a global checkbox to Select All/Deselect All.

<section>
  <table>
    <thead>
      <tr>
        <th>
          <input type="checkbox" 
                  [checked]="selectionModel.selected.length > 0" 
                  [indeterminate]="selectionModel.selected.length > 0 &&
                  selectionModel.selected.length < tableData.length" 
                  (change)="onCheckAllChange($event)" />
        </th>
        <th>Name</th>
        <th>Year</th>
        <th>Rating</th>
      </tr>
    </thead>
    <tbody>
      <tr *ngFor="let row of tableData">
        <td>
          <input type="checkbox" 
                 [checked]="selectionModel.isSelected(row.id)" 
                 (change)="onCheckRowChange(row)" />
        </td>
        <td>{{ row.name }}</td>
        <td>{{ row.year | date : 'short' }}</td>
        <td>{{ row.rating | number }}</td>
      </tr>
    </tbody>
  </table>
  <footer>
    <button type="button" (click)="toggleSelectAll()">
      {{ isAllSelected ? 'Deselect All' : 'Select All' }}
    </button>
  </footer>
</section>

@Component({
  selector: 'sreyaj-exp-cdk-selection',
  template: `
    <!-- see code above >
  `,
  standalone: true,
  changeDetection: ChangeDetectionStrategy.OnPush,
  imports: [NgForOf, DatePipe, DecimalPipe],
})
export class CdkSelectionComponent {
    readonly tableData: MockData[];
  readonly selectionModel: SelectionModel<number>;

  constructor() {
    this.tableData = MOCK_TABLE_DATA;
    this.selectionModel = new SelectionModel<number>(true, []);
  }

  get isAllSelected(): boolean {
    return this.selectionModel.selected.length === this.tableData.length;
  }

  public onCheckAllChange(event: Event): void {
    const isChecked = (event.target as HTMLInputElement).checked;
    if (isChecked) {
      this.selectAll();
    } else {
      this.deselectAll();
    }
  }

  public onCheckRowChange(row: MockData): void {
    this.selectionModel.toggle(row.id);
  }

  public toggleSelectAll(): void {
    if (this.isAllSelected) {
      this.deselectAll();
    } else {
      this.selectAll();
    }
  }

  private selectAll(): void {
    this.selectionModel.select(...this.tableData.map((row) => row.id));
  }

  private deselectAll(): void {
    this.selectionModel.clear();
  }
}

Here I've used the id property to maintain the selection state, but we can use the full data also for the selection.

All selection and indeterminate state ✅

The way we check for all selection/intermediate state is:

<input type="checkbox" 
      [checked]="this.selectionModel.selected.length > 0" 
      [indeterminate]="this.selectionModel.selected.length > 0 &&
                  this.selectionModel.selected.length < this.tableData.length" 
      (change)="this.onCheckAllChange($event)" />

We mark checked by checking if at least one item is selected (by looking at the length of the selected items):

[checked]="this.selectionModel.selected.length > 0"

Next, we set the indeterminate state by checking if at least one is selected but not all.

 [indeterminate]="this.selectionModel.selected.length > 0 &&
                  this.selectionModel.selected.length < this.tableData.length"

Selection change event ⚡️

We can configure if the selection model should emit an event on change or not. This is specified using the emitChange argument in the constructor.

Here's what the event looks like:

/**
* export interface SelectionChange<T> {
*  source: SelectionModel<T>;
*  added: T[];
*  removed: T[];
* }
* */
selectionModel.changed.subscribe((change: SelectionChange) => {
   console.log(change); 
})

We'll be able to get the list of items added and removed and the model itself in case we want to do more when the selection changes.

The good thing about the selection model is that it's not coupled to any component (it's completely headless). It can be used with lists and other similar components. A small but really good utility that allows us to concentrate on the actual business logic instead of things like this.

Code and Demo 🔥

Connect with me

• Twitter
• Github
• Linkedin
• Portfolio

Have any thoughts or questions? shoot'em below in the comments. Stay Safe ❤️

Problem Statement

A lot of times, I stumble upon youtube videos or posts on Twitter and other social media where the person shares their setup and most of the comments below would be something like this:

• What IDE are you using?
• Which monitor do you use?
• What headphones/microphone is that in the background?
• Are you using a mac?

With show off, users can create a collection of what they have or use and share it with their friends and followers. This makes it easier for you and your followers and I bet you'll not have to reply to these comments anymore.

Features

With show off, the primary idea is to make it super easy to share things with your followers. Also, the user interface is designed in such a way that it's functional and super easy to use as well. Copy the collection link and pin it to your Twitter profile or Github Readme or Instagram or Youtube or wherever you get asked about your stuff.

1. Multiple Collections

You can create multiple collections for different use cases. So for example as a developer, you can have a collection to showcase your laptop, keyboard, monitor, etc in a list. Then create another list to showcase different software that you use.

2. Built for developers, designers, and content creators

Preset for common categories tailored for developers, designers, and content creators.

3. Share & Embed

With the unique link that you get for your collection, you can use it to share on social media. There is also a way to embed the collection into your personal website or portfolio.

Clicking on share, will give two more options, one to copy the collection link or to directly share to Twitter.

4. Private collections

Ability to mark a collection as private and when you are ready to add items, you can open up the visibility to make it public.

5. Like and Comments

Users can comment and like the collection giving it more flare. Interact with your followers within the collection. Be in the spotlight if your collection gets more likes.

6. Recommendation Meter

Love or hate a product that you use personally? Let your followers know how much you would recommend it. With the recommendation meter, you can do just that. This gives them the idea of how good the gadget/software/item is.

7. Affiliate Links

With each item, there is an option to add multiple links. Which includes affiliate links as well. Those who have affiliate accounts with a marketplace like Amazon, Flipkart, etc can add the affiliate links for the item. This helps you earn additional income when someone purchases the item using your affiliate link.

You can always use a normal link type and add an affiliate link instead, but it's always a good practice to let the user know that the link you add is an affiliate link. If you choose the right type, they will be able to see that its affiliate link gives the user full disclosure.

Other features in the pipeline

• Custome item types
• Image uploads where users can share their setup images and others

Tech Stack

Front-end

The UI is built using the latest and greatest Angular v14. And the best thing is that all the components, directives, pipes, etc are standalone.

Standalone components were one of the most hyped features of v14 and I really enjoyed my time without modules in Angular.

Since the concept of standalone components is fairly new, I am pretty confident that this application will serve as an example for folks trying out standalone components as there aren't many open source angular applications at the time of writing this article.

As always styling is TaliwindCSS all the way. I have created a UI library called ZigZag that is built with TailwindCSS that I used in this project. I had a chance to migrate most of the components in zigzag to standalone as well.

Back-end

My back-end framework of choice is NestJs as it goes very well with Angular. Especially when you work in an Nx monorepo. Things are so inline that you have very less context switching between the UI and Server code.

GraphQL is used which makes things even better. And for the database, Planetscale is used obviously paired with Prisma. More about it in a dedicated section as there are a few things I noticed when working with Planetscale and Prisma that I would like to elaborate on.

Planetscale + Prisma = 🔥

Deployment

My go-to for deploying the UI is Vercel. When it comes to the server, the repo has Github Actions integrated which automatically builds the server and sends the code to a remote Ubuntu instance.

In Depth: UI

When it comes to the UI, as I have mentioned, all the components are standalone. With standalone components, we don't have to declare them in a NgModule. All the dependencies are imported inside the @Component itself.

@Component({
  selector: 'show-off-login',
  template: ``,
  styles: [],
  standalone: true, // <-- Mark as standalone
  changeDetection: ChangeDetectionStrategy.OnPush,
  imports: [ButtonComponent, ...FORM_COMPONENTS], // <-- Import deps
})
export class LoginComponent {}

The main thing that I noticed when working with standalone components is that the amount of boilerplate has reduced considerably. Also, I feel that it's more convenient at times. I'm not against modules though.

Another thing that is a rather big change was that I don't have an AppModule for the application. With standalone components, Angular introduced a new method that can bootstrap the application using a standalone component.

// main.ts
bootstrapApplication(AppComponent, {
  providers: [
    {
      provide: AUTH_CONFIG,
      useValue: {
        authURL: `${environment.apiURL}/api/auth`,
      },
    },
    {
      provide: CURRENT_USER,
      useFactory: (auth: AuthService) => auth.me(),
      deps: [AuthService],
    },
    importProvidersFrom(HttpClientModule), // <-- import from existing modules
   ]
});

And a look at my AppComponent

@Component({
  selector: 'show-off-root',
  template: `<router-outlet></router-outlet>`,
  standalone: true, // <-- standalone component
  imports: [RouterModule],
})
export class AppComponent {
  constructor(private readonly authService: AuthService) {
    authService.init().pipe(take(1)).subscribe();
  }
}

Another change to note is the way we do lazy loading in routes.

export const COLLECTION_ROUTES: Routes = [
  {
    path: '',
    pathMatch: 'full',
    title: 'Home | Show Off', // <-- directly update title
    data: {
      context: CollectionPageContext.Home,
      header: {
        text: 'Home',
      },
    },
    loadComponent: () => // <-- new `loadComponent` method
      import('./components/collections.component').then(
        (m) => m.CollectionsComponent
      ),
  }
]

What are the major changes I noticed when working with Angular v14 (w/ standalone components).

Attaching lighthouse report run on the deployed app:

Embed Feature

One of the most striking features of Show Off is the embed feature where users can embed a collection into their website or portfolio by just copy-pasting the snippet generated from the application.

This was something that I haven't done before, so was really interesting to get this functionality working. The below section is actually what an embedded collection would look like.

It renders an iframe under the hood. You can inspect the below section and see that it's just an iframe:

<iframe width="100%" height="600px" src="https://show-off.adi.so/embed/cl5dx3okz0003aixcvomcbbcf"></iframe>

Here how the embed script looks like:

function showOff(collectionId, opts) {
  if (!collectionId) {
    throw new Error('showOff: collectionId is required');
  }
  const iframe = document.createElement('iframe');
  iframe.src = constructIframeSrc(collectionId, opts);
  iframe.width = opts?.width ?? '100%';
  iframe.height = opts?.height ?? '500px';
  iframe.frameBorder = '0';
  iframe.scrolling = '0';
  iframe.style.border = 'none';
  document.getElementById('show-off-embed').appendChild(iframe);
}

function constructIframeSrc(collectionId, opts) {
  const queryParams = {
    showTitle: opts?.showTitle ?? 'true',
    showDescription: opts?.showDescription ?? 'true',
    showOwner: opts?.showOwner ?? 'true',
    padding: opts?.padding ?? '16',
  };
  let baseUrl = new URL(`https://show-off.adi.so/embed/${collectionId}`);
  Object.keys(queryParams).forEach((key) => {
    baseUrl.searchParams.append(key, queryParams[key]);
  });

  return baseUrl.href;
}

What the script does is that it creates an iframe and then loads the /embed/<collection_id> route.

Embed Code Display

Embed code that is displayed on the application has syntax highlighting for the embed snippet. The syntax highlighting is powered by Shiki

Here's what the code looks like in UI:

shiki.setCDN('https://unpkg.com/shiki/'); // <-- Don't miss this
this.highlighter = await shiki.getHighlighter({
   theme: 'material-palenight', // <-- Load a theme
   langs: ['html'], // <-- Load only HTML lang
});
this.code.nativeElement.innerHTML = this.highlighter.codeToHtml(script ?? '', {
        lang: 'html',
})

Zigzag - UI library

Zigzag is a very small UI component library that I built with Angular and TailwindCSS. It contains a few basic sets of components:

• Button
• Modal
• Dropdown
• Tooltip
• Form Components

It's not packaged as an npm library yet, so I use Git Submodule to load the repo into the main project repo.

More about zigzag and how to use it here:

In Depth: Back-end

NestJs is a back-end framework for building server-side applications. It plays very well with Angular as it shares a lot of concepts. And everything inside an Nx monorepo makes it even better.

I've been using GraphQL lately and totally love it. Mainly because I get instant documentation of my queries and mutations. Setting up GraphQL is a bit of a pain, but once you set it up, things are easy. NestJs has support for GraphQL using the official plugins.

NestJs supports both schema-first and code-first approaches. I've used the Schema first approach here. For querying and testing everything, Apollo Sandbox provides a great interface. You'll be able to see the schema and all the queries and mutations and test them with ease.

You can enable Apollo sandbox in NestJs by making these changes:

// app.module.ts
import { ApolloServerPluginLandingPageLocalDefault } from 'apollo-server-core';

@Module({
  imports: [
    GraphQLModule.forRootAsync<ApolloDriverConfig>({
      driver: ApolloDriver,
      useFactory: (configService: ConfigService) => {
        const isProd = configService.get('NODE_ENV') === 'production';
        return {
         ...
          playground: false, // <-- default playground disabled
          plugins: [
            ApolloServerPluginLandingPageLocalDefault({ // <-- use apollo sandbox plugin
              embed: true,
            }),
          ],
        };
      },
    }),
  ],
})
export class AppModule {}

Once this is done, I faced some issues because of the Content Security Policies as I was using helmet, so I had to update them in the main.ts file:

// main.ts
  const devContentSecurityPolicy: ContentSecurityPolicyOptions = {
    directives: {
      manifestSrc: ["'self'", '*.cdn.apollographql.com'],
      scriptSrc: ["'self'", "'unsafe-inline'", '*.cdn.apollographql.com'],
      frameSrc: ["'self'", '*.embed.apollographql.com'],
      imgSrc: ["'self'", 'data:', '*.cdn.apollographql.com'],
    },
  };

  app.use(
    helmet({
      // when undefined it will load the default option: https://github.com/graphql/graphql-playground/issues/1283#issuecomment-723705276
      contentSecurityPolicy: isProd ? undefined : devContentSecurityPolicy,
      crossOriginEmbedderPolicy: false,
    })
  );

Authentication is done using Google and Github OAuth right now. Username & password based auth is not set up right now. Authentication flow is taken care of by Passport.

Auth-related code can be found: https://github.com/adisreyaj/show-off/tree/main/libs/api/auth

Here's what the entities look like:

In Depth: Database

For databases, my primary choice is always Postgres or MySQL mainly because I love Prisma so much. So my go-to for ORM is Prisma. PlanetScale is a MySQL-compatible database platform. I've been following PlanetScale for a long time and was really impressed with what they do.

Databases are always difficult to architect, scaling, backups, etc are always crucial for any application. I used to set up Postgres or MySQL in a docker container on my Ubuntu instance and pray to god that nothing goes wrong.

With Planetscale you leave everything related to a database like scaling, downtimes, backups, etc. One of the most interesting features that you get is database branching 🤯

I have to admit that I really liked how you can test out schema changes to your table in a separate branch. And once you are comfortable with the changes, you can merge them into the main branch.

I've used the Prisma Full-text Search for searching with collections.

To set it up we make the following changes in schema.prisma file:

generator client {
  provider        = "prisma-client-js"
  // add `fullTextSearch` and  `fullTextIndex`
  previewFeatures = ["referentialIntegrity", "fullTextSearch", "fullTextIndex"]
}

datasource db {
  provider             = "mysql"
  url                  = env("DATABASE_URL")
  referentialIntegrity = "prisma"
}

model Collection {
  id          String    @id @default(cuid())
  name        String
  description String
  user        User      @relation(fields: [userId], references: [id])
  userId      String
  likes       Like[]
  shares      Share[]
  comments    Comment[]
  items       Item[]
  published   Boolean   @default(true)
  private     Boolean   @default(false)
  deleted     Boolean   @default(false)
  createdAt   DateTime  @default(now())
  updatedAt   DateTime  @updatedAt

  @@index([userId])
  @@fulltext([name]) // <-- add index
}

Prisma x PlanetScale

PlanetScale and Prisma work very well. I still remember the time when people started asking to support Prisma and PlanetScale finally did it. They made it really easy to use it with Prisma.

1. Create an account on PlanetScale.

They provide a free account to start with generous limits.

2. Create a new Database

You can create a database from the web console or using their CLI which is a nice little tool to have. You can setup PlanetScale CLI by referring to the docs here: https://planetscale.com/docs/concepts/planetscale-environment-setup

Once you have the CLI you need to authenticate:

pscale auth login

and then create a database

pscale database create <name>

Note: When selecting the location, make sure to select a region near to where your server is hosted. In my case, I did a mistake in one of my previous projects where I selected a region very far from where my server was hosted. This caused latency issues as it takes time for the communication between the server and the DB itself.

3. Connecting to Database

PlanetScale gives a list of options that you can use to connect to the database. In our case, we need to connect with Prisma, so we select Prisma from the dropdown. This gives us the connection string, that we can use with Prisma.

We can then add the DATABASE_URL in the .env file:

DATABASE_URL=mysql://<username>:<password>@<subdomain>.psdb.cloud/show-off?sslaccept=strict

You can set this environment variable for when the server is deployed. For local workflow, the easiest way to set up the connection is using the PlanetScale CLI.

pscale connect <databast-name> <branch-name> --port 3309

This will create a tunnel to your localhost, so you can use the following connection string:

DATABASE_URL=mysql://localhost:3309/<db-name>

Note: The --port 3309 is not required, by default it will run on 3306

4. Prisma configuration

There is a slight change in the way we configure Prisma when using PlanetScale:

generator client {
  provider        = "prisma-client-js"
  previewFeatures = ["referentialIntegrity"]
}

datasource db {
  provider             = "mysql"
  url                  = env("DATABASE_URL")
  referentialIntegrity = "prisma"
}

The main thing to note here is that we add the referentialIntegrity under preview features and also set the referentialIntegrity type to prisma

Here's the official documentation on how to get started with PlanetScale and Prisma

Read more about referential integrity.

Note: With PlanetScale, the way we handle migrations is different. Prisma has a prisma migrate command that does the schema diff and generates the corresponding migration scripts. But with PlanetScale, the way we do this is different.

Migrations and PlanetScale

When we make a change to the schema, we start by creating a development branch in PlanetScale:

pscale branch create <db-name> <branch-name>

Once the branch is connected, go ahead and close the connection and connect to the new branch that we created:

pscale connect <databast-name> <branch-name> --port 3309

Note: You can also create a branch from the web console. Once the branch is created you'll have to copy the connection string and use that instead of the main branch connection string in the .env file. This is why I would recommend using the PlanetScale CLI as you don't have to keep on updating your .env file with a new connection string when working on big changes to the schema. What you do is just stop the connection to the main branch and instead connect to the new branch we created.

Once changes are made we push the changes to the DB using the following command:

prisma db push

This pushes the latest changes to the dev branch. When you are ready, we can create a Deploy Request to the production branch.

In the deploy request, we'll be able to see the schema changes. Once we are happy with the changes, the changes can be merged into the prod branch.

This is a really cool feature that gives you more power to prototype and makes changes to the schema with confidence. They also provide Rollback functionality as well which gives you peace of mind.

In Depth: Deployment

Deployment of the UI is very straightforward. Just push the code to git and it gets deployed to Vercel. So nothing to do there. Here's what the deployment setting in Vercel looks like for those who wonder.

When it comes to back-end deployment, Here's how things are done.

1. Code pushed to GitHub.
2. Github Actions run the build script.
3. Copy the .graphql files to the dist directory.
4. Dist artifacts are then packaged into a .tar.gz file.
5. The .tar.gz file is sent to a remote server using rsync
6. SSH into the remote server
7. The packaged bundle is extracted into a folder.
8. Install all the dependencies
9. PM2 is used to run the server

The server port is then pointed to a subdomain using Nginx. I always refer to my article on setting up Nginx and port forwarding to a subdomain with SSL.

You can see that the API calls for the app are made to https://show-off-api.adi.so

Monitoring the server is easy, thanks to PM2:

Coding Practices

• ✅ Linting: ESLint

• ✅ Code formatting: Prettier

• ✅ And commit messages are following Conventional Commits enforced using Husky

• ✅ Code Quality: SonarCloud See Project

• ✅ Code Vulnerabilities: Snyk

Running Locally 💻

#1. Clone the repo

git clone https://github.com/adisreyaj/show-off.git

#2. Initialize the submodule (zigzag)

git submodule update --init

#3. Install the dependencies

npm install

#4. Install Peer deps for zigzag

npm i @floating-ui/dom

#5. Setup the environment variables

Set up all the required environment variables required for the back-end:

DATABASE_URL=mysql://localhost:3309/show-off

NODE_ENV=development
FRONT_END_CALLBACK_URL=http://localhost:4200/auth/callback

# JWT sign secret
JWT_SECRET=very_very_strong_secret_key
JWT_EXPIRY="3d"
COOKIE_SECRET=very_very_strong_secret_session_key

# Google OAuth Details
GOOGLE_CLIENT_ID=xxxxx.googleusercontent.com
GOOGLE_CLIENT_SECRET=xxxxxxx
GOOGLE_CALLBACK_URI=http://localhost:3333/api/auth/google/callback

# Github OAuth Details
GITHUB_CLIENT_ID=Iv1.xxxxxxxxxx
GITHUB_CLIENT_SECRET=xxxxxx
GITHUB_CALLBACK_URI=http://localhost:3333/api/auth/github/callback

#6. Set up the Database

Run the command to populate the DB with tables:

npm run prisma:push

#7. Start up the UI and Back-end

For UI:

npm start show-off

For Back-end

npm start api

UI: http://localhost:4200 & GQL: http://localhost:3333

Links and References 🔗

Code and Demo 💫

Link: https://show-off.adi.so

Github: https://github.com/adisreyaj/show-off

Connect with me

• Twitter
• Github
• Linkedin
• Portfolio

Do add your thoughts or if you have any questions, shoot'em below in the comments. Stay Safe ❤️

Learning to code has changed my life. I'm really proud of myself and the state I'm in right now. I feel empowered. And being a self-taught developer, I can say that it can change your life too.

Studies

Photo by Philippe Bout

Timeline: 2012 - 2016

I did my Engineering in Electronics and Communications. It was in my 3rd year, I really got interested in robotics. There was a workshop on building things with Arduino which triggered something in me.

I got myself an Arduino and started learning to code. I created multiple small projects like Smartphone controlled robocar, and a full home automation system with the support of gestures and voice control. Went on to win a few prizes at the college and national levels.

The thing I noticed is that, even while I was working on all these projects, it was the software side of it that excited me and I knew that I would be better off working with code.

I along with a few of my friends applied for startup incubation at our University to create a company called MakeLabs. We used to build projects for other students and also did R&D on so many interesting ideas.

Change of Plans

Timeline: 2016

After I did my bachelor's, I decided to go for my master's. It was not my plan, my family persuaded me into making this decision. So when I say family, it's not always my mom and dad, but other relatives because mom and dad had always been supportive.

I had two small offers as part of the Campus placements which I rejected because of the Master's plan.

Things went wrong just before a week of my Master's classes started. A bunch of us (Roll numbers 1 to 14) got a back paper in the 7th semester. I still wonder why all 14 of us failed at the same time.

But since I had grace marks as part of the entrepreneurship program. But luckily, my Master's admission got canceled due to the back-paper even though I cleared it thanks to the grace marks.

It was a relief for me to know that I won't be doing something I didn't like. And I think one of the best things happened to me because I really love what I do now.

Getting into tech support

Photo by Petr Macháček

Timeline: 2017

So now since life took a different turn, I was put in a situation with no job and not knowing what to do next.

I struggled for nearly a year to get a job in the software domain. It was very hard during that time to get calls for interviews and most of them really didn't hire freshers. For most of the jobs that I interviewed for I got a really low package.

I came to Bangalore and started looking for a software developer role. I also wanted to do something till I could find a job. That is when one day, one of my friends was going for an interview for a tech support role. I just tagged along. I who went with him just for giving him company ended up giving an interview and getting the job as well.

The job wasn't exciting and I knew that its not for me. But I had to work so that I can pay my bills without having to trouble my parents.

Blogging about computers and smartphones

The one thing that I did during that time is writing blogs, mainly about computer tips and tricks. You can see that latest iteration of the blog here at sreyaj.com. Before that I use to own other domains.

I wrote a lot of detailed articles about things related to computers that I encountered or I found will be useful to others. I even had AdSense enabled after some time and used to get very small amounts as ad revenue.

I used WordPress for the blogs and also learned a little bit of PhP, just enough to be able to tweak themes and create small applications at that time.

I could really use some money to pay for rent and food. I ended up working there for almost 6 months. I used to work on my blog and also learn HTML, and CSS to make the blog look good. WordPress had limitations in what can be done.

We are limited by the design of the theme that we use. I am really picky about the design of the blog and that's what pushed me to learn HTML, CSS, and JavaScript.

While working in the Tech support role, I spent a lot of time doing UI changes to my blog. I spent more time learning how HTML, CSS, and JavaScript, all to make my blog look better.

I also did some logo designing and website development for my friends and family at that time. I really enjoyed creating designs.

I later started creating small web applications using PhP like Instagram Photo and Video downloader and a few others which could be a nice addition to the blog.

I was pretty successful in creating a blog that generated a good amount of views and so made a few dollars from it. But the interest in writing articles related to computer tips and tricks slowly faded as I got my first job as a Software Developer.

First job as a Software Engineer

Photo by John Schnobrich

Timeline: Nov 2018

While being in the tech support role, I was pulled into the job completely and I thought I'll be stuck there If I don't do something. That's when I started to apply for software jobs, mainly web development. Got a couple of offers, but the pay was way lesser than what I got from the tech support job.

I was pretty confident that once I get a chance, I can prove myself and go from there. But getting that initial break was a real struggle for me.

One fine afternoon, I got a call from an HR who asked me If I could go in for an interview. I was having an off that day and so I decided to go. Went there and gave the interview. I was able to show my blogs and a few smaller projects that I built during that time.

The company asked me to go to their office for 2 days where they would evaluate me and then offer a job. I was given the task of redoing the company website using Angular. That is the first time I came to know about Angular and what Single Page Applications are.

I was able to complete the task given by the company before the given time and was offered a job with less salary than what I was getting in my tech support role. I decided to just take the job eventually. The pay was just around 12,000 INR or ~150 USD per month.

I undervalued myself because my confidence level went down because of all that happened after college and I was jobless for more than a year.

Angular and Me

Angular version 7 just got released at the time I joined for my first-ever software role.

Angular opened up a whole lot of opportunities for me. I never knew frameworks like these existed and you can build impactful products with them. I realized how powerful the whole web ecosystem was. I was just working with WordPress and had a narrow vision of the web before. But that got changed when I was introduced to Angular.

I started reading the docs and also started going through the Udemy course by Max. I started off with the Udemy course at first, but the pace didn't work well for me. I switched to the official documentation and relied more on blogs.

If someone has told me about Angular or the exciting world of web applications before, I would've been in a far better place by now.

I started out with Angular 7 in the company and I was the only front-end developer. I learned everything on my own. Self-learning helped me in many ways. Whenever I come across a new pattern or feature, I try to read more about it and also practice it in a sandbox. I believe in learning by doing.

I was able to pick up things faster and I started working on NodeJS as well after a short while. Since it's a startup and when you don't have a lot of people, you do a lot of things. I really liked having that flexibility and control.

Also having a manager who really knows all the best practices when it comes to architecting software really came as a blessing. I was able to learn a lot from him. I'm grateful for having a mentor like him during the start itself.

Learn to say NO

Worked really hard for almost 2 years. I spent a lot of time at the office working really hard and learning as much as I can. Even spent almost 12 hours in the office for a month straight. I didn't complain as I was learning something every day. I realize it's a mistake that I did because I didn't know to say "No".

Saying NO was and is very hard for me. I am still trying to do this. It's really important for someone to say no to things at times. Otherwise, you'll just end up doing more work without much to gain.

I really am grateful to my first company for believing in me and giving me that opportunity. I was able to work on multiple projects and also lay the foundation for many projects which really helped me learn a lot.

From there I focused on getting more and more knowledge in Angular and NodeJs. I started feeling more confident about what I can do. I started experimenting and working on small side projects to further solidify my learnings.

Another thing that I loved doing is sharing my knowledge with my peers as well. Whenever I come across something interesting, I ping them and let them know about it.

Being part of the community

Photo by John Cameron

The one thing that I really enjoyed is sharing knowledge and that is what brought me into a lot of communities. Twitter was really one of the best places for sharing and networking with a lot of developers.

Twitter had a lot of awesome Angular developers who share good stuff all the time. I followed any Angular developer I could on Twitter at that time. Once I really got a good grasp of Angular and Web development in general, I shifted to writing blogs focusing on web development mainly using Angular.

I got a chance to sync with a lot of great people on Twitter like Santosh, Chau, Trung, Bram, and many more.

Another community that I wanted to give a shout-out to is Angular Nation which is a really nice community of people who loves Angular. I didn't know that such a community existed before I got an invitation from Connie to join Angular Nation.

I met a lot of cool folks there and also had a chance to interact with Bonnie Brennan. She gave me a lot of support and motivation. I went on to give multiple talks on different channels in Angular Nation. There are a lot of people that I interacted with in Angular Nation like Sander, Stephen, Rob, Ankita, Valentine, Oyemade, Debmallya, etc.

I am also thankful to all of my supporters on Buymeacoffee for their support.

Blogs on web development

Covid really changed a lot of things for me. Working from home gave me a lot of time that I can use to invest in learning more advanced topics and also blog about my learnings. This definitely has been a turning point for me.

I put my old blog into maintenance mode and started writing blogs related to web development. You can find my blogs here:

• sreyaj.dev
• dev.to

I realized that I learned and researched more while I write blog posts. I was not just helping others by sharing these articles but was helping myself by researching a lot about topics I write about. So If you are someone who likes to learn and if you want to learn better, I would suggest documenting them as blog posts.

I mostly consider my blogs as documentation that I can go back and refer to just in case. I became a contributor to the Official Angular Org on dev.to as well, Thanks to Wassim Chegham.

Projects & Wins

Photo by Sean Lim

I also worked on a bunch of side projects, most of them built using Angular and a few with React. When it comes to the back-end frameworks, I started out with ExpressJS and then shifted to NestJs for its similarities with Angular.

Being able to write the back-end and front-end means, I don't want to rely on others If I had an idea in mind. I can execute it on my own.

I've participated in multiple hackathons during Covid times and won two of them.

• Auth0 x Hashnode Hackthon
• Netlify x Hashnode Hackthon

Hackathons came with cash prizes and swags and on top of that people started recognizing my work which gave a confidence boost and motivation to do more.

I've also built up my portfolio during this time. You can check it out here: adi.so

If you want to have a look at the code, here is the link to the repo:

Check out some of my projects:

• Flare
• Compito
• Cartella
• Cardify
• Md Resume
• more...

Fast forward to 2022

I have started my Angular journey from v7 and now we are at v13. It's been a really good journey so far. The amount of learnings that I accumulated is so much and I'm still learning. That's a really interesting thing about the software domain, you need to be up to date with what's happening. And that is something that I really like about the whole software development field.

Fast forward to 2022, I now work as a Software Engineer at Traceable. I work with a really good team of experienced engineers whom I can learn from. I really got to know how culture makes a really big difference. It's not always about the money. Finding a job where you have peace of mind is really important.

Tech Stack

I primarily work with Angular in my day-to-day job. Since I am working as a UI developer, I don't have to work with back-end technologies or databases in general. But since I do work on side projects and do like having control over both front-end and back-end, I keep myself up to date with back-end and database technologies as well.

I really like TypeScript and use it in every project that I start. So whether it's back-end or front-end, TS is my go-to.

Front-end technologies

Apart from Angular, I've learned React. Haven't really gotten a chance to learn Vue or other newer frameworks. I like Angular more because it's opinionated and is more comfortable working with it.

I'm not saying React is bad, I enjoy working in React as well. Especially when working on smaller projects, React makes it really easy to get-go. One thing I didn't like much in React was how we have to set up routing. But with Next.js, I don't have any complaints about routing anymore.

I really like working with Next.js because it has a really good Dx.

For styling, I used SCSS a lot, and lately, it's Tailwind CSS all the way. I just love it so much. I can write styes and iterate over them very fast.

For state management in Angular, I use NGXS and Ngrx Component store.

Back-end technologies

Since I only know JavaScript, Node.js is the way to go. I started off with Express.js and then later started using Nest.js because of its similarities with Angular. There is no context switching required when writing the back-end as both Angular and Nest.js shares a lot of concepts.

I am leaning towards learning Fastify these days for its simplicity.

The majority of my back-ends are all Restful APIs, but recently started using GraphQL and really love how good it is. I'll probably stick with GQL for my future projects.

When it comes to databases, I prefer MongoDB, Postgres, or MySQL. Since I am not that well versed with SQL, I always use an ORM like Prisma which has served me well so far. For Mongo, the obvious choice is mongoose for me. It just works.

For deployments, I use a simple Ubuntu based instance from OVH and run a container in it, connect to domains using Nginx and Let's Encrypt for SSL and that's pretty much it.

I use Nx for all of my projects as it makes it so easier to work on both the front-end and back-end with ease. They take care of all the tooling while we can concentrate on getting the things done.

Going forward

I aspire of being a GDE in Angular at some point in time. I want to continue writing more blogs and sharing my knowledge.

I am also thankful to a whole bunch of people from the Angular community that helped me reach where I am today.

Finally special thanks to all who have supported me on buymeacoffee:

• Saurabh Gangamwar
• Amal GTA
• Haroon Ansari
• Santosh Yadav
• Sampson Orson Jackson
• Joseph Raj
• Bram Borggreve
• Hashnode

Feel free to reach out to me if you want to chat about something or if you just want to say hi.

Connect with me

• Twitter
• Github
• Linkedin

TL;DR: Flare is a new kind of social networking site made especially for software developers. Twitter is a really great place where developers hang out and share insightful tweets. But there is something that is lacking there.

That's where Flare would fit in. It has more options for the developers to share their knowledge with the community. Like a dedicated code snippet editor, a terminal command editor, etc. No need to convert your code into a screenshot to share it. Just share it as is so that people can copy the code.

What is Flare?

Flare is a dedicated social networking platform for developers to share and learn about new things. With a primary focus of helping the creators share better content to their uses and making it easier for the community to benefit from these contents, Flare has a lot to offer.

Features ✨

Here are some features that I planned for Flare. The ones implemented right now are marked. The fundamental idea is to support writing small posts within Flare. So the concept of blocks came. Blocks are used to create a flare, you can have text, code, images, etc in a single flare. Each of these smaller items that make up a flare is called a block.

• Markdown for creating flares
• Share Code snippets ✅
• Share terminal scripts ✅
• Share Images ✅
• Polls ◻️
• Attach Github Repos
• Share tech stack used
• Share libraries used
• Reorder blocks
• A code sandbox within a flare
• Comments ✅
• Bookmarks ✅
• Show Spotify last played songs ✅
• Tips and Sponsors
• Header Image promotions ✅
• Kudos ✅
• Connect Hashnode blog ✅

Now that the base setup is done, all the other features could be done. The only thing needed is time. So for the sake of this hackathon, I need to focus on what's doable within a few weeks.

Design 🎨

Since it's all about the community and growing with the community, I thought of having a plant as the logo for flare. The developer community is a great place to share and learn and grow. That is what Flare is wanting to be.

Tech Stack 🛠️

Flare uses a lot of cool open-source frameworks and tools. Here is a non-exhaustive list of the main ones.

Front-end

The client application for flare is built using Angular and is styled using Tailwind CSS. There is no complicated state management at the moment, just relying on GraphQL caching. The common components are coming from a small UI library I'm building which is based on Tailwind.

Apollo GrapQL is used for all things GQL in the UI.

Back-end

Most of the exciting stuff happens in the back-end. The most exciting one for me is GraphQL. It's the first time I am building a GraphQL backend. The backend framework of choice for me is NestJs. It provides support for a lot of different patterns in a very well-structured manner.

For the NestJs - GraphQL implementation, Schema First approach is followed.

For database, there is MySQL as the primary data store driven using Prisma. Then there is Redis for the queue and a few other purposes.

The whole project is a monorepo managed by Nx.

Deployment

For the front-end, it's deployed on Netlify. Again there isn't anything special that you have to do. Just put the code in git and connect it with Netlify. Baam, you get a CICD pipeline ready for your UI.

When it comes to the back-end things are not that easy. I used Github Actions to build and deploy the back-end code to a remote VPS running Ubuntu. The code is built and zipped and sent to the remote server. The code once is received by the remote server, unzips it, and starts the server.

PM2 is used to manage the server, detect failures and automatically restart if required. The APIs are then port forwarded through Nginx to a domain that is used by the UI.

Ref: Deployment yaml file

Flare Deep Dive 🔍

Now let's dive deeper into how Flare is actually built and what are the features it currently has to offer.

Composing a Flare

The flare below contains multiple text blocks, an image block, a terminal script block, and a code snippet block. It shows how the posted flare is later rendered.

The composer component (left side) looks very simple but is the most complex part of the whole application. There are a couple of interesting things happening around how the flare is composed. Will share them below.

Technical Details

The text field is not markdown right now, but I want to at least highlight the automatically link the URLs and also highlight the hashtags. Had to play around a bit till I could come up with something that works. Here's how the component is build:

@Component({
  selector: 'flare-block-text-input',
  template: ` <div
    class="relative mt-[1px] flex flex-1 overflow-y-auto rounded-md bg-slate-100 ring-primary focus-within:ring-2"
    style="min-height: 100px; max-height: 200px;"
  >
    <div
      #editor
      class="absolute top-0 left-0 z-10 h-full w-full border-slate-100 font-medium text-transparent caret-slate-800"
    ></div>
    <div
      class="flare-block-text-input-rendered pointer-events-none z-20 h-full w-full border-slate-100 p-4 font-medium"
      [innerHTML]="content"
    ></div>
  </div>`,
})
export class FlareBlockTextInputComponent {}

So it's basically two divs overlapping each other. The bottom div is a rich text editor which spits out the HTML of the text. The text is then passed through autolinker which converts the URLs to anchor tags.

The text is then regex'd to find and highlight the hashtags. The final HTML is then sanitized and passed to the upper div.

const linkified = this.convertLinksToAnchorTags(html);
const hashtagified = extractHashTags(linkified).content;
this.content =
  this.sanitizer.sanitize(SecurityContext.HTML, hashtagified) ?? '';

The bottom editor text is transparent so only the content in the top div will be visible. This way we get the caret and select functionality working.

Feed

The home page is the feed page where you can see all the flares from the people you follow. Users will be able to like and comment on the flares. Flares can also be bookmarked so that you don't miss an interesting flare just because you didn't have time to read it.

Users can click on the flare to add comments.

Comments are single-level right now, meaning no nested comments.

Profile Page

The profile page is the most exciting page of all. It's the most happening page in the application after the feeds page.

Users can set custom header images and also add a good bio. The social handles provided will be shown on the page as well.

Hashnode Blogs

If the users have provided their Hashnode profile URL during onboarding, Flare will automatically fetch and display their latest blogs on the profile page. It's a nice way to showcase your blogs to the users.

Header Promos (Personal Billboard)

This is a really interesting idea that came to me one day. What if we could let people advertise on our profile. So the header image acts as a billboard that can be rented out to show adverts. This way, devs, and creators can earn some money.

Submitting a Header Promo

Promos are basically ads proposals that can be submitted to someone by visiting their profile. The person submitting the promo can add a title, description, compensation, and the header image that needs to be posted as well.

Applying a Promo

Users can see all the proposals they have received by clicking on the Promo Proposals button which opens up a modal like below.

The receiver can then choose to set the image as a header by clicking on the Apply Header button. This automatically updates the header of the user. A notification can then be sent to the advertiser.

Give and Recieve Kudos

If you find someone who is really doing a great job in helping the community and sharing knowledge all the time, you can give them kudos for their contributions.

What a developer or a content creator needs is appreciation. Show them you appreciate them for their contributions. It'll be the biggest motivator for any developer out there.

Spotify Integration

A great way to share your taste in music with others. Hopefully, find other folks with the same likes in music. Just another way to make connections on Flare.

Users will be able to integrate Spotify to show the last played songs on their profile.

Note: Due to the limitation of Spotify API in development mode, new users are not able to integrate their spotify. Quote extension is required!

Discover

Discover page lets you find top accounts and popular flares.

Notifications

Your regular notifications page where you get notifications when someone follows you or posts a new flare. Nothing fancy going on in here.

Onboarding screens

On the first login, users are taken through a series of pages to complete their profile and follow users

A few basic questions are asked and on the next page, the social handles can be added.

To build the feed, the users are asked to follow a few existing users.

Responsiveness

It's not a proper application in 2022 if it's not responsive and so I've put in a bit of effort to try and make Flare as responsive as possible.

Recipes 🍳

Here are some functionalities worth mentioning.

Authentication

Flare currently allows users to signup/login via Google or Github. This is implemented using passport in the backend.

The authentication token is securely set on the front-end as a httpOnly cookie. This way the client itself cannot access the token via code.

res.cookie('token', accessToken, {
  expires: new Date(Date.now() + 24 * 60 * 60 * 1000),
  httpOnly: true,
  secure: true,
  signed: true,
  maxAge: 24 * 60 * 60 * 1000,
  sameSite: 'strict',
});

So how does a user log out from the system? Since the client can't remove the cookie while logging out, the user gets logged back automatically as the token is present as is valid.

To fix this issue, we introduce a new normal cookie:

/**
 * Set a non http cookie which can be removed by the client on logout
 */
res.cookie("token-sync", accessToken, {
  expires: new Date(Date.now() + 24 * 60 * 60 * 1000),
  httpOnly: false,
  secure: true,
  signed: true,
  maxAge: 24 * 60 * 60 * 1000,
  sameSite: "strict"
});

So now the front-end can clear out the non-http cookie.

The server expects both the cookies to be present to validate a session:

// jwt.strategy.ts
export class JwtStrategy extends PassportStrategy(Strategy) {
  constructor(private config: ConfigService) {
    super({
      jwtFromRequest: (req) => {
        /**
         * Get both the http and non http tokens from cookies
         * and match them.
         *
         * For logged-out user, the `token-sync` cookie will not be present.
         */
        const token = req.signedCookies['token'];
        const tokenSync = req.signedCookies['token-sync'];
        if (token && tokenSync && token === tokenSync) {
          return token;
        } else {
          return null;
        }
      },
      ignoreExpiration: false,
      secretOrKey: config.get('JWT_SECRET'),
    });
  }
}

Problem solved ✅

File Uploads

Files uploaded in GraphQL are not that straightforward. With REST, we just create a FormData and then append the file to it and send a POST request to the server.

Strategy

I investigated how Twitter is handling media uploads for tweets. Opened up the Network tab and started looking for clues. That is when I found something interesting. I tried to think about something like that and implement it for flare.

Here's what I did.

1. User adds an image to the flare.
2. Immediately the image is uploaded to the server via a REST API.
3. Server handles the file and saves it locally.
4. A job is added to the queue as well for the image to be removed if it's not used in the flare. There is a set expiration time. The job id is sent back to the UI.
5. So if the user cancels or decides to remove the image from the flare. The job will run after the specified expiration time and remove the image from the server.
6. If the user finally posts the flare, the image is then uploaded to an S3 server and removed from the local server.

Queue

Bull is the most popular library for setting up Queue in a Node application. NestJs has official support for Bull and so setting up things was pretty easy.

Bull uses Redis as the data store. I used UpStash which provides a free Redis instance. A queue is basically a "queue", I mean you can put things in the queue and run them one by one as configured.

Setting up Queue in NestJS:

// app.module.ts
import { BullModule } from '@nestjs/bull';
import { Module } from '@nestjs/common';
import { ConfigModule, ConfigService } from '@nestjs/config';

@Module({
  imports: [
    BullModule.forRootAsync({
      imports: [ConfigModule],
      useFactory: async (configService: ConfigService) => ({
        redis: {
          host: configService.get('REDIS_HOST'),
          port: +configService.get('REDIS_PORT'),
          password: configService.get('REDIS_PASSWORD'),
          maxRetriesPerRequest: 5,
          tls: {
            host: configService.get('REDIS_HOST'),
          },
        },
        prefix: 'flare',
      }),
      inject: [ConfigService],
    }),
  ],
})
export class AppModule {}

Cloud Storage

The files are uploaded to Backblaze which provides Object storage with an S3 compatible API. Backblaze has a generous free plan. There is something interesting about Backblaze. So under the Bandwidth Allianze program data transferred between Backblaze and Cloudflare is free. Meaning I will only have to worry about uploads.

Uploading files to Backblaze

Files are uploaded from the server to cloud using the AWS SDK. Here's how the NestJs service for uploads will look like:

@Injectable()
export class S3Service {
  s3: S3Client;
  constructor(private readonly config: ConfigService) {
    this.s3 = new S3Client({
      endpoint: config.get('S3_ENDPOINT'),
      region: config.get('S3_REGION'),
      credentials: {
        accessKeyId: config.get('S3_ACCESS_KEY_ID'),
        secretAccessKey: config.get('S3_SECRET_ACCESS_KEY'),
      },
    });
  }

  async upload(file: FileWithMeta) {
    return this.s3.send(
      new PutObjectCommand({
        Bucket: this.config.get('S3_BUCKET'),
        Key: file.filename,
        Body: file.buffer,
        ContentType: file.mimetype,
      })
    );
  }

  async delete(file: string) {
    return this.s3.send(
      new DeleteObjectCommand({
        Bucket: this.config.get('S3_BUCKET'),
        Key: file,
      })
    );
  }
}

You might have noticed that there is no function written for getting the file from the cloud. Because we don't need it.

Cloudflare sits in between Backblaze and the web app. So we can directly query the files via Cloudflare without any data transfer charges. And on top of that add additional headers to the request to cache images.

How cool is that?

That is if the image URL in Backblaze is:

https://f004.backblazeb2.com/file/flare-media/ckzvelloy0000z8xchry323ng.jpeg

It becomes:

https://flare-cdn.adi.so/file/flare-media/ckzvelloy0000z8xchry323ng.jpeg

Here is a details tutorial for setting up the connection between Cloudflare and Backblaze: https://help.backblaze.com/hc/en-us/articles/217666928-Using-Backblaze-B2-with-the-Cloudflare-CDN

Retrieving the Images in Web App

So when an image is uploaded the image name is the identifier and that is what gets stored in the DB. The image name will be sent to the web app as well. We use a simple Pipe to construct the full media URL from the image name:

@Pipe({
  name: 'mediaUrl',
})
export class MediaUrlPipe implements PipeTransform {
  constructor(@Inject(API_CONFIG) private apiConfig: ApiConfig) {}

  transform(value: string): string {
    return `${this.apiConfig.mediaURL}/${value}`; // <-- cloudflare connected domain
  }
}

The benefit here is that we don't have to write APIs to fetch images from the cloud and then stream it back to the web app. This puts load onto our server and we have to do exception handling and caching-related stuff on our side. This just eliminates everything.

Spotify Integration

Users can choose to show their last played songs from Spotify by connecting their Spotify account with Flare.

Technical Details

The whole feature is implemented using Netlify Functions which is their serverless offering. Setting up this using Netlify functions was pretty easy once I figured out the logic.

1. Getting the user's refresh token from Spotify

• The user clicks on Connect Spotify button.
• A new window is opened and the spotify-authorize Netlify function endpoint is called inside.
• User can log in to their Spotify account.
• Spotify redirects to spotify-callback on successful authorization.
• Callback encrypts the refresh token and saves it in Redis with the user's username.
• Once this is done, the popup window is closed.

1. Using the token to get the last played songs

• The spotify-last-played Netlify function endpoint is then called to get the user's songs.
• Refresh token is retrieved from Redis and then decrypted.
• An new auth token is generated for calling the Spotify API.
• The Recently Played API endpoint is called to get the list of songs.
• The songs are then saved to Redis for a day.
• Response is then sent back to UI with required Cache headers.

Cache working

When the API is called again, the cache will be checked first to see if the user's songs are already retrieved or not. If it exists, they are returned back.

Code references:

1. Authorization Function - spotify-authorize.ts
2. Authorization Callback - spotify-callback.ts
3. Get Last Played Songs - spotify-last-played.ts

Challenges ⏳

There were lots of challenges along the way. Firstly, GraphQL is very new to me. So learning and doing it all in a few weeks was definitely challenging. But worth it as now I know why people chose GraphQL these days.

How I spent hours debugging a silly issue 😫

The introduction of queues was not as easy for me as I made it sound. I made a stupid mistake at first which caused my server to consume a crazy amount of resources and was causing crashes.

This is a screenshot of my PM2 dashboard when the server was idling.

What could have gone wrong?

My first hunch was its because I used RxJs for some of the queries. I used it queries which need to get some information from one DB call and then do another DB call based on it. I could have used multiple async-awaits to get it done. But I thought RxJs made such code better. Here's an example:

findAllFlaresFromFollowingUsers(user: CurrentUser) {
  const currentUsersFollowing$ = from(
    this.prisma.user.findUnique({
      where: {
        id: user.id,
      },
      select: {
        following: {
          select: {
            id: true,
          },
        },
      },
    })
  );

  const getFlaresByAuthorIds$ = (userIds: string[]) =>
    from(
      this.prisma.flare.findMany({
        where: {
          deleted: false,
          authorId: {
            in: userIds,
          },
        },
        include: getFlareFieldsToInclude(user.id),
        orderBy: { createdAt: 'desc' },
      })
    );

  return currentUsersFollowing$.pipe(
    switchMap(({ following }) => {
      if (isNil(following)) {
        return of([]);
      }

      return getFlaresByAuthorIds$(
        following.map(({ id }) => id).concat(user.id)
      );
    }),
    take(1)
  );
}

So I suspected that there is some memory leak because of the subscriptions. I knew that NestJs handles the subscription and subscription for us. But silly me thought RxJs is to blame here.

I converted all the RxJs code to promise based like any sane man would've done in the first place.

After countless hours of debugging, turns out it was the flipping queue that was causing the issue and not RxJs. The bull was trying to connect to the Redis, but it failed and crashed. The reason was that for the TLS connection, there is a special configuration that needs to be passed while configuring the queue.

What helped me find the issue? Logging. Loggin is very important to any application. It can help you find and fix problems fast. I've used NestJs-Pino for logging purposes.

Outcome

While creating the Redis DB in Upstash, it gives an option to enable TLS or not. So if you are trying to connect to a TLS enabled Redis DB in Bull. Make sure to add this to your queue config:

{
  redis: {
    host: configService.get('REDIS_HOST'),
    port: +configService.get('REDIS_PORT'),
    password: configService.get('REDIS_PASSWORD'),
    maxRetriesPerRequest: 5,
    tls: { //<-- TLS config
      host: configService.get('REDIS_HOST'), 
    },
  },
  prefix: 'flare',
}

Here's the SO thread that helped me fix the issue: https://stackoverflow.com/a/57896863/10781739

After all this, I later switched back to local Redis install in a docker container 😅

Coding Practices

• ✅ Linting is taken care of by ESLint (Thanks to Nx, no work to be done for setting up linting).

• ✅ Code formatting is taken care of by Prettier ( Don't know what I would do without it).

• ✅ And commit messages are following Conventional Commits enforced using Husky

• ✅ Logging is thanks to NestJs-Pino. I can't stress how important logging is for any application out there. Proper logs make debugging easier.

• ✅ Code Comments are added "only" when required. Not a fan of polluting the codebase with irrelevant code comments.

• ✅ Custom exception handling for Prisma related errors using NestJs Exception Filters:

const PRISMA_ERROR_CODE_TO_STATUS = {
  P2025: {
    code: 404,
    message: 'Resource not found',
  },
};

@Catch(PrismaClientKnownRequestError)
export class PrismaExceptionFilter implements GqlExceptionFilter {
  logger = new Logger(PrismaExceptionFilter.name);
  catch(exception: PrismaClientKnownRequestError, host: ArgumentsHost) {
    const { code, message } = PRISMA_ERROR_CODE_TO_STATUS[exception.code] ?? {
      code: 500,
      message: 'Internal server error',
    };
    this.logger.error({
      code,
      message,
      exception,
    });
    return new HttpException(message, code);
  }
}

Code and Demo 💫

Demo: https://flare-api.adi.so/api/demo For those who just want to test drive and not sign in with their accounts, Try the above link 👆🏻

Link: https://flare.adi.so

Note: Please don't spam 🙏🏻. Respect others 😊 Its' not a production app right now, still in a very early stage and there will be unforeseen bugs. Please don't try to break it 🥺

Attaching the GitHub repo for the project.

Right now only Google and Github based logins are enabled. Demo env will be flushed out regularly so don't worry about your personal data.

Running Locally 💻

#1. Clone the repo

git clone https://github.com/adisreyaj/flare.git

#2. Initialize the submodule (UI components)

I created a small UI component library called Zigzag that is used in the project as a submodule.

git submodule update --init

#3. Install the dependencies

npm install

#4. Setup the environment variables

Set up all the required environment variables required for the back-end:

NODE_ENV=development
DATABASE_URL=mysql://root:root@localhost:3307/flare
FRONT_END_CALLBACK_URL=http://localhost:4200/auth/callback

# JWT sign secret
JWT_SECRET=veryverysecretkey
JWT_EXPIRY="3d"
COOKIE_SECRET=veryverysecretsessionkey

# Google OAuth Details
GOOGLE_CLIENT_ID=
GOOGLE_CLIENT_SECRET=
GOOGLE_CALLBACK_URI=http://localhost:3333/api/auth/google/callback

# Github OAuth Details
GITHUB_CLIENT_ID=
GITHUB_CLIENT_SECRET=
GITHUB_CALLBACK_URI=http://localhost:3333/api/auth/github/callback

# Queue
REDIS_HOST=localhost
REDIS_PORT=6379
REDIS_PASSWORD=

# Object Storage
S3_ENDPOINT=
S3_REGION=
S3_BUCKET=
S3_ACCESS_KEY_ID=
S3_SECRET_ACCESS_KEY=

#5. Prepare the Database

Use docker-compose to spin up MySQL and Redis databases.

version: '3.1'
services:
  db:
    image: mariadb
    restart: always
    environment:
      MYSQL_ROOT_PASSWORD: root
      MYSQL_DATABASE: flare
    ports:
      - '3307:3306'
    volumes:
      - /Users/<username>/Desktop/code/db:/var/lib/mysql
  cache:
    image: redis
    restart: always
    ports:
      - '6379:6379'
    volumes:
      - /Users/<username>/Desktop/code/cache:/var/lib/redis

#6. Set up the Database

Run the command to populate the DB with tables:

npm run prisma:migrate

#7. Generate the GraphQL interfaces from the schema

Run the command to generate the required types:

npm run generate:gql

#8. Start up the UI and Back-end

For UI:

npm start

For Back-end

npm start api

UI: http://localhost:4200 & GQL: http://localhost:3333

You are all set for exploring Flare locally.

Links and References 🔗

Connect with me

• Twitter
• Github
• Linkedin
• Cardify - Dynamic SVG Images for Github Readmes

Do add your thoughts or if you have any questions, shoot'em below in the comments. Stay Safe ❤️

What is Libshare?

You can think of Libshare as a curator for JavaScript libraries. How often do you come across a library and then when you need to use it, you forget the name of the library?

Happens to me every time. Libshare solves that problem.

Another great use-case for Libshare is to bring visibility to the open-source packages that are used in your projects. Don't let them hide in your package.json file. Let people know about the libraries that are used in building amazing products.

Curate all the libraries used in your project and add them to a list. You can get a public shareable link to it which can be added in Github Readme or blog posts. This makes it easier for people to find out more about the libraries.

Tech Stack

If you look at the subtitle for the blog post, it says "Powered by Angular and HarperDB". Notice that there is a front-end framework and then there is a Database. You might be wondering What is the back-end used for?

The interesting thing about the project is that I didn't have to develop a separate back-end, I didn't have to deploy it, set up SSL, or do any of the things I usually do when I'm building a side project.

The whole back-end is written as Custom Functions in HarperDB. It's crazy, I know right? I didn't think that it could do so much when I was first introduced to HarperDB. But once I used it, I can say that it has great potential.

I'll make sure to link to the list of all the libraries that are used in making this project.

Setting up the Back-end

So there are two parts to the Back-end.

1. Setting up Database
2. API Server which talks to the DB

Let's start by setting up the DB for the application.

We are going to be using a functionality called Custom Functions.

HarperDB Custom Functions

Custom functions are one of the most interesting features of HarperDB. It's so versatile and makes life easy for a developer.

• Custom functions allow us to create API routes inside of HarperDB. Yes, you heard me. No need to create a separate API server.

• You can directly interact with HarperDB from within the custom functions. What this means for you is that no more configuration or initialization is required.

• You can write the whole server in the Integrate IDE in HarperDB Studio or if you are like me who prefers to do things locally, you can write your functions locally and then deploy it once it's ready.

I'll be setting up a local instance of HarperDB to write the custom functions and then once everything is ready, will deploy it to a cloud instance. In this way, I can code faster, test it out better, and once everything is ready, deploying it is easy-peasy.

Note: If you like to write your functions inside the Harper Studio, you can skip setting up the local instance and write your functions directly in the cloud instance.

Setting up a HarperDB

There are two ways to setup HarperDB:

1. Use their cloud offering
2. Self-host

Installing HarperDB using Docker.

There are different ways to install a local instance. You can read more about them here. I'll be using docker to create a container using the harperdb/harperdb image.

Create a file called docker-compose.yml and copy over the content below into that file:

version: '3.3'
services:
    harperdb:
        volumes:
            - /Users/admin/Desktop/libshare:/opt/harperdb/hdb
        environment:
            - HDB_ADMIN_USERNAME=admin
            - HDB_ADMIN_PASSWORD=password
            - CUSTOM_FUNCTIONS=true
        ports:
            - '9925:9925'
            - '9926:9926'
        image: harperdb/harperdb

Note: Provide a valid path for volumes (left-hand side of :). That's where we will be setting up the custom functions.

You can then start the container by running:

docker-compose up

Run this command in a separate terminal and keep this open, so you can watch the logs.

Registering the User Installed Instance

Go ahead and sign up for an account in HarperDB if you haven't already.

• Once you are logged in, create an Organization.

• Once you are inside the newly created Org, you can click on the Add button, which gives you two options. Choose the second option which is Register User-Installed Instance and fill in the details.

• You should now be taken to the studio page.

Setting up tables

Now we set up the tables required. For that create a new schema first, and then add tables. Schema is nothing but for grouping tables. I've just named the schema as data.

Setup 3 tables like so:

1. users
2. lists
3. libraries

Note: The hash_attr is kind of the primary key. Just use id in our case.

Here's how my setup looks:

Setting up custom functions

Going to the Functions tab will land you on a page where you can create the routes for your API.

Start by creating a new project first. I named it api. The project name can be used to namespace your APIs. So in this case, the endpoint will look like: http://localhost:9926/api.

We are all done setting up the instance and the table. The only thing that is left is to go to the Config page and copy the Instance API Auth Header which we need to use.

Creating the APIs

If you navigate to the folder that is mentioned under the volumes in the docker-compose.yml file, you can see there are a couple of folders that got created.

We will be working in the custom_functions directory. Navigate into the custom_functions folder and open your favorite IDE.

The first thing that you will notice, there is an api folder. So each project that you create on the custom functions page, will have its folders. The folders would have the following folders/files:

├── helpers
├── routes
└── static

The names are self-explanatory.

Let's start by initializing git in the custom_functions folder so that we can save it to a repo.

git init

also, initialize npm so that we can install packages

npm init

You can see a few boilerplate files inside these folders, just delete them so we can start fresh.

Setting up first route

You can create multiple files inside the route to organize things better. So we'll few files:

├── auth.js
├── general.js
├── libraries.js
├── lists.js
└── users.js

Here's what a route file would look like:

'use strict';

module.exports = async (server) => {
  server.route({
    url: '/',
    method: 'GET',
    handler: (request, reply) => {
      return {
        status: 'OK',
      };
    },
  });
};

The best thing about HarperDB custom functions is that they are powered by Fastify which is fantastic. The route files contain basic Fastify route declarations.

For maintainability and a better overall structure of code, You can extract the handler into a separate file and add it to the helpers folder. It's not necessary, but doable and I would highly recommend it. I've split my code into multiple handlers and helper files:

├── auth-handler.js
├── auth-helper.js
├── errors-helper.js
├── libraries-handler.js
├── libraries-helper.js
├── list-handler.js
├── list-helper.js
├── query-builder-helper.js
├── users-handler.js
└── users-helper.js

Let's see a complete implementation of how to set up a signup route and its handler:

// users-handler.js

const createUserHandler =
  ({ hdbCore }) =>
  async (request) => {
    const { firstName, lastName, email, password } = request.body;
    const hashedPass = await hashPassword(password);

    const sqlReq = {
      ...request,
      body: {
        operation: 'sql',
        sql: qb.buildInsertQuery('data.users', {
          firstName,
          lastName,
          email,
          password: hashedPass,
        }),
      },
    };

    return hdbCore.requestWithoutAuthentication(sqlReq);
  };

module.exports = { createUserHandler }

and the route:

'use strict';

const userHelpers = require('../helpers/users-helper');
const userHandlers = require('../helpers/users-handler');

module.exports = async (server, hdb) => {
  server.route({
    url: '/signup',
    method: 'POST',
    preValidation: [userHelpers.validateUser(hdb.logger), userHelpers.existingUserValidation(hdb)],
    handler: userHandlers.createUserHandler(hdb),
  });
};

Note: You can also add Validation methods where the authentication can be checked or the request body can be validated.

// users-helper.js

'use strict';

const joi = require('joi');
const errors = require('./errors-helper');

const USER_VALIDATION_SCHEMA = joi.object({
  firstName: joi.string().required(),
  lastName: joi.string().required(),
  email: joi.string().email().required(),
  password: joi.string().required(),
});

const validateUser = (logger) => async (request, reply) => {
  try {
    await USER_VALIDATION_SCHEMA.validate(request.body);
    return true;
  } catch (error) {
    logger.error('Bad Request');
    errors.badRequest(reply);
  }
};

module.exports = {
  validateUser
};

See how I've used joi for validating the request body. You can install and use different libraries like this inside the helpers/routes. Joi can be installed with the following command:

npm install joi

Head over to the documentation website of Joi for more info: https://joi.dev/

Once all the endpoints are set up. We can now deploy the functions to a cloud instance.

Development Tips

Here are a few recipes that could come in handy when working with HarperDB.

Automatically restart the functions on changes

When working with custom functions, whenever you make changes to the files, you need to restart the Custom Functions server every time for those changes to take effect.

So to speed up the process, I created a file watcher which listens to changes in any of the routes or helpers folders and auto-magically restarts the custom functions server. It's a very simple script that makes an API call to restart API when you save a file.

Getting Auth Token

Step into HDB studio and go to the config page. Under the heading of Instance API Auth Header (this user) you can see the token. Copy the token using the icon on the left.

Add a .env file in the root folder of custom_functions where you can mention the copied token which is needed to call the HarperDB API.

HDB_AUTH=

Create a file watcher

Create a file file-watcher.js under the custom_functions/scripts folder. We don't want this to be part of the project so it is kept outside the project folder.

const fetch = require('node-fetch');
const chokidar = require('chokidar');
require('dotenv').config(); // <-- to read the env variables
const updateFunctions = async () => {
  try {
    fetch('http://localhost:9925', {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json',
        authorization: `Basic ${process.env.HDB_AUTH}`,
      },
      body: JSON.stringify({ operation: 'restart_service', service: 'custom_functions' }),
    });
    console.log('Custom functions server restarted');
  } catch (error) {
    console.error('Failed to restart custom functions',error);
  }
};

// Make sure the path is correct
chokidar.watch('./api/**/*.js').on('change', () => {
  updateFunctions();
});

You can then open a terminal and run the script:

node file-watcher.js

Note: Make sure the path to your custom functions is correct.

How to use env variables in HarperDB Custom Functions

I needed to save a private key for signing the JWT when the user logs in. For this purpose, the keys should be saved as environment variables.

We use a popular library called dotenv to implement this. dotenv will automatically read the variables in our .env file and inject it to process.env The only gotcha is that the .env file for each project should be placed inside the project folder. In this case, the .env file path is:

custom_functions/api/.env

And for using it, specify the path to the .env file:

require('dotenv').config({
  path: `${__dirname}/../.env`, // <-- relative url
});

console.log(process.env.JWT_SECRET) // <-- access it

Here is the content of the .env file:

JWT_SECRET=

JWT_SECRET is used for signing and verifying the access tokens. You can see the usage in the auth-helper.js file.

Note: There are .env.example files kept in certain places in the repo which is where the actual .env files should be.

Repo

Here is the Github repo with all the routes, helpers written for Libshare.

Testing the custom functions

All the API endpoints can be validated locally using apps like Postman or Insomnia. The URL will be http://localhost:9926/api with your route specified in the routing files. Eg: The signup route will be http://localhost:9926/api.

Here's an example cURL command:

`curl --request POST \
  --url http://localhost:9926/api/signup \
  --header 'Content-Type: application/json' \
  --data '{
    "firstName": "Adithya",
    "lastName": "Sreyaj",
    "email": "hi@adi.so",
    "password": "mysecretpassword"
}'

Final files and folders

Here's what the whole project now looks like:

Deploying the custom functions

There are two different ways to deploy the custom functions to a cloud instance. One involves us zipping the custom_functions folders and making an API call for packaging the functions and then another call to deploy the packaged functions. This is really cumbersome and I'm not a fan of it.

The other one is to deploy it using the HarperDB Studio, which deploys the local custom functions to the chosen cloud instance with a button click.

1. Go to the functions tab.
2. Select the project in the left sidebar.
3. Click on the deploy button on the top right of the editor.
4. Select the cloud instance to deploy to and press that green deploy button.

Woohoo. We have successfully deployed a whole back-end. You can now visit the cloud instance functions URL to see the API.

Setting up the UI

The Libshare UI is built using Angular and styles are handled using Tailwind CSS. Here's how you can set up the UI to run locally.

1. Clone or download the repo:

   git clone https://github.com/adisreyaj/libshare.git
   

2. Navigate to the folder

   cd libshare
   

3. Initialize the submodule

   git submodule  update --init
   

4. Install the dependencies

   npm install
   

5. Serve the UI

   npm start
   

Now you can visit http://localhost:4200 in your browser to see the application running.

Note: The UI components come from another repo called zigzag which is added as a submodule in the repo. We need to initialize the submodule before installing dependencies. It's a set of common components that I use in my projects.

Make sure the HarperDB docker image is running as in the local environment the UI is going to be calling the API at http://localhost:9926.

Pages in UI

So the UI is actually quite simple, there are like 4 pages in the application at the moment:

1. Login
2. Signup
3. Libraries
4. Lists

Libraries Page

This is where you can add the NPM libraries that you have used or you found useful. You can then add a new library by just entering the name and searching for it.

If the API is able to find the library, all the details are pre-filled by the application. If not the user can simply enter them manually.

Lists Page

Lists are a way to group the libraries that are added. So let's say you can think of them as folders. So if you worked on a project, you can create a list for that project and add all the libraries that are used.

The list can then be made public, which produces a public link that can be shared. If not the list is only visible to the owner.

Here's the link to Libshare's list page: https://libshare.adi.so/view/libshare-api-libraries-i95t9kib9a

Public Lists

Here's what a public list page looks like.

You get a nice list of libraries used with some useful info about it. There is a title and description along with the last update date.

Have you worked on something interesting? Try Libshare! You can showcase all the cool packages that made your application great.

Connect with me

• Twitter
• Github
• Linkedin
• Cardify - Dynamic SVG Images for Github Readmes

Do add your thoughts or if you have any questions, shoot'em below in the comments. Stay Safe ❤️

HttpContext in Angular

HttpContext is used to store additional metadata that can be accessed from HTTP Interceptors. Before this, there was no proper way to configure interceptors on a per request basis. This feature was introduced by Angular v12.

If you had use cases where you need to treat a particular request differently or override some logic in an HTTP Interceptor, this is what you need to use.

I came to know about it only recently and actually started using it in one of my recent projects - Libshare.

How to use HttpContext in Angular?

Let's take a practical use case for understanding how to use HttpContext.

I was working on a small application that can be used to curate and share the libraries. Most of the APIs are authenticated, meaning we need to add Authorization header with all the API requests.

For pages like Login and Signup, we don't need to pass the token in the headers. Let's see how we can skip certain APIs and only add Bearer tokens to the other API requests.

The way we use it is pretty straightforward. There are two parts to it:

1. Create a new HttpContextToken

const IS_PUBLIC_API = new HttpContextToken<boolean>(() => false);

2. Passing the context while making http calls.

When using the HttpClient to make requests, you can pass the context along with other options. We create an instance of HttpContext class and use the set method to pass the value to the token we created above.

getSomeData(slug: string) {
    return this.http
      .get(<URL>, {
        context: new HttpContext().set(IS_PUBLIC_API, true),
      })
  }

3. Retrieve the data inside an Interceptor.

We can now retrieve the context data from the interceptor by accessing the request.context:

@Injectable()
export class AuthInterceptor implements HttpInterceptor {
  intercept(req: HttpRequest<any>, next: HttpHandler): Observable<HttpEvent<any>> {
    if (req.context.get(IS_PUBLIC_API)) {
      return next.handle(req);
    }
   // Add token to other requests
  }
}

You can check a practical usage here: Libshare Repo

Addtional Info

HttpContext is backed by a Map and so has methods like:

class HttpContext {
  set<T>(token: HttpContextToken<T>, value: T): HttpContext
  get<T>(token: HttpContextToken<T>): T
  delete(token: HttpContextToken<unknown>): HttpContext
  has(token: HttpContextToken<unknown>): boolean
  keys(): IterableIterator<HttpContextToken<unknown>>
}

The context is also type-safe, which is a good thing. Also, keep in mind that the context is mutable and is shared between cloned requests unless explicitly specified.

There are a lot of ways this could prove useful like if you want to cache only particular requests, or maybe add some additional headers conditionally.

Documentation: https://angular.io/api/common/http/HttpContext

Connect with me

• Twitter
• Github
• Linkedin
• Cardify - Dynamic SVG Images for Github Readmes

Do add your thoughts in the comments section. Stay Safe ❤️

I recently worked on a small project which is a small e-commerce application built using Angular and NestJs. Auth0 is used for authenticating the users. I had a very interesting thought of adding notifications when a new user signs up. The easiest way for me was to use Auth0 Actions.

Auth0 Actions

Actions are one of the coolest features of Auth0. I love it and have used it for multiple scenarios. Actions are custom Node.js functions that get executed during certain points like User Login, Registration, etc.

Here's a definition from the docs:

Actions are functional services that fire during specific events across multiple identity flows.

Auth0 hooks allowed us to add custom logic that gets triggered when certain events happen. Actions are a more advanced version of hooks that provides more extensibility.

Official docs: https://auth0.com/docs/customize/actions

Action Triggers

The custom functions that we write are called by certain events. Here are the supported triggers:

Here are more details of when exactly these actions are triggered: https://auth0.com/docs/customize/actions/triggers

Implementing the Action

For our use case, we need the notification to be sent when a new user signs up. So we could use the Post User Registration trigger for our action.

1. Create a custom action

The first step is to create a new custom Action. We do that by navigating to Actions > Custom and then clicking on the Build Custom button.

We get a modal asking to give the Action a name and also select a Trigger and the Environment.

You can fill the form up with the following details:

• Name: New User Notifications
• Trigger: Post User Registration
• Runtime: Node 16 (Recommended)

2. Setting up pre-requisites

Once the action is created, you can see the list of the Actions under Custom tab on the Actions Library page.

There are a few things that we need to do before we can start writing the actual logic.

Creating a Telegram Bot

Telegram is a really powerful messaging platform that can do a lot of stuff. One of the best things about it is that we can create bots and also send messages using the Telegram Bot API .

Put a message to BotFather on Telegram

/newbot

It will prompt to you give a name. Give a name and then you'll be given the Bot Token.

Now that we have the bot token, we can make API calls using the Telegram Bot API.

Ref: https://core.telegram.org/bots#3-how-do-i-create-a-bot

Before we can send a message to the Bot, we need to get the Channel Id. For that send a message to the bot and then just paste the following URL in the browser (replace the with yours):

https://api.telegram.org/bot<bot-token>/getUpdates

You will be able to see the message details that was sent to the bot:

{
  "ok": true,
  "result": [
    {
      "update_id": 723563447,
      "message": {
        "message_id": 7,
        "from": {
          "id": 627445600, // <-- Copy this Id
          "is_bot": false,
          "first_name": "John Doe",
          "username": "johndoe",
          "language_code": "en"
        },
        "chat": {
          "id": 627445600,
          "first_name": "Jane Doe",
          "username": "janedoe",
          "type": "private"
        },
        "date": 1642266764,
        "text": "Test"
      }
    }
  ]
}

The id is the channel_id that we are going to use for sending messages.

3. Writing the Action Logic

Now that we have the things needed, let's start writing the logic. So here are the things that need to be set up in the actions.

Installing Dependencies

Actions allow us to install packages that we can use inside the function, in our case we need to make API requests to the Telegram Bot API to send messages. For that, we can install a library called node-fetch.

To do so, go to your newly created action and click on the Modules section.

Note: We install node-fetch@2 explicitly because we want the CommonJs version of the library.

Adding Env Variables

Actions also have a way to keep our environment variables a secret. This is where we are going to save the Bot Token and the Channel id that we will use in the code. It's not a good idea to put them in the code as they are sensitive information.

There is a Secrets section under which we can save them. Create a secret for the token and the channel id.

Writing the actual logic

Now you can use node-fetch to make a post request to the /sendMessage API endpoint.

const request = require('node-fetch'); // <-- require the library

/**
* Handler that will be called during the execution of a PostUserRegistration flow.
*
* @param {Event} event - Details about the context and user that has registered.
*/
exports.onExecutePostUserRegistration = async (event) => {
  try{
    const {family_name, given_name} = event.user;
    await request(`https://api.telegram.org/bot${event.secrets.BOT_TOKEN}/sendMessage`, 
      {
        method:'POST',
        body: JSON.stringify({
          "chat_id": event.secrets.TELEGRAM_CHAT_ID,
          "text":`New User Signed up: ${given_name} ${family_name}`
        }),
        headers: {
          'content-type': 'application/json'
        }
      }
    );
  } catch(err){
    console.log('Failed to notify');
  }
};

Now the action can be deployed.

Ref: https://core.telegram.org/bots/api#sendmessage

4. Using the Action

Once the action is deployed, we can use it in a flow. To do so, navigate to the Actions > Flows Page and select Post User Registration flow from the cards.

We can find the action that we built under that Custom tab. Dragging and dropping the action to the flow does the job of activating it. The only thing left now is to just Apply the flow.

We are done setting up.

So now whenever someone signs up, you get a message in Telegram.

There are tons of cool use-cases for Actions. If you would like to see more blogs on it, do let me know.

Connect with me

• Twitter
• Github
• Linkedin
• Cardify - Dynamic SVG Images for Github Readmes

Do add your thoughts in the comments section. Stay Safe ❤️

Using validators in angular forms

Validators can be set up in different ways to validate user inputs in form elements. Angular provides a lot of validators that are commonly needed for any form.

If we special validation requirements or if we are dealing with custom components, the default validators might not just cut it. We can always create custom validators for these cases.

In-built validators of angular

Angular ships with different validators out of the box, both for use with Template forms as well as Reactive forms.

• In-built Validator Directives.
• A set of validator functions exported via the Validators class.

Both the directives and Validators class use the same function under the hood. We can provide multiple validators for an element. What Angular does is stack up the validators in an array and call them one by one.

Validator Directives

Native HTML form has inbuilt validation attributes like required, min, max, etc. Angular has created directives to match each of these native validation attributes. So when we place these attributes on an input, Angular can get access to the element and call a validation function whenever the value changes.

Here's how you would use a validator directive:

<input type="email" required minlength [(ngModel)]="email"/>

The attributes required and minlength are selectors for the RequiredValidator( ref ) and MinLengthValidator ( ref ) directives respectively. These can be used with both Template drive forms and Reactive Forms.

Here's how the requireddirective looks like:

@Directive({
  ...
  providers: [{
  provide: NG_VALIDATORS,
  useExisting: forwardRef(() => RequiredValidator),
  multi: true
}],
  ...
})
export class RequiredValidator implements Validator {
   // .....

   validate(control: AbstractControl): ValidationErrors|null {
    return this.required ? requiredValidator(control) : null;
  }

   // .....
}

Let's break down the code:

1. The class RequiredValidator implements an interface called Validator.
2. The Validator interface forces the class to implement a validate() method.
3. The method will be called for validation of the value.
4. The validation logic can be performed in the method and just have to return an object if there is an error or null if there is no error.
5. Now, we need to let Angular know about this custom validation that we've set up.
6. We use the NG_VALIDATORS Injection token for this.
7. We ask Angular to use our same RequiredValidator class by using the useExisitng property.

So when the user places required on a form control, the RequiredValidator directive gets instantiated and the validator also gets attached to the element.

Take a look into the source code for Required Validator( ref ).

Validators class

Validators class exposes a set of static methods that can be used when dealing with Reactive Forms like so:

import { FormControl, Validators } from '@angular/forms';

export class AppComponent{
  email = new FormControl('', [Validators.required, Validators.minLength(5)]);
}

Here's the list of all the function inside the class:

class Validators {
  static min(min: number): ValidatorFn
  static max(max: number): ValidatorFn
  static required(control: AbstractControl): ValidationErrors | null
  static requiredTrue(control: AbstractControl): ValidationErrors | null
  static email(control: AbstractControl): ValidationErrors | null
  static minLength(minLength: number): ValidatorFn
  static maxLength(maxLength: number): ValidatorFn
  static pattern(pattern: string | RegExp): ValidatorFn
  static nullValidator(control: AbstractControl): ValidationErrors | null
  static compose(validators: ValidatorFn[]): ValidatorFn | null
  static composeAsync(validators: AsyncValidatorFn[]): AsyncValidatorFn | null
}

Custom Sync Validators

We can also create custom validators in Angular which are tailored to our particular use case. You can't just always rely on the built-in capabilities of Angular.

Validators are just functions of the below type:

export interface ValidatorFn {
  (control: AbstractControl): ValidationErrors|null;
}

Let's create a custom validator function that checks if a domain is secure (https) or not.

export const ProtocolValidator: ValidatorFn = (control) => {
  const { value } = control;
  const isSecure = (value as string).startsWith("https://");
  return isSecure ? null : { protocol: `Should be https URI` };
};

Custom validator with parameters

If we want our custom validator to be more configurable and re-use in multiple places, we can pass parameters to our validator function to create a validator based on the provided parameters.

For example, if the Secure validator needs to validate Websocket URIs also, we can modify the ProtocolValidator to accommodate this change:

export const ProtocolValidator = (protocol: string): ValidatorFn => (control) => {
  const { value } = control;
  const isSecure = (value as string).startsWith(protocol);
  return isSecure ? null : { protocol: `Should be ${protocol} URI` };
};

Use custom validators in Reactive Forms

We can directly use the function in the reactive forms like so:

const urlControl = new FormControl('', [Validators.required, ProtocolValidator('https://')]);

and the template will be something like this:

<input type="text" [formControl]="urlControl" />

Use custom validator in Template-driven Forms

If we want to use these validators with Template-drive forms, we need to create a directive.

@Directive({
  selector: "[protocol]",
  providers: [{
      provide: NG_VALIDATORS,
      useExisting: forwardRef(() => ProtocolValidatorDirective),
      multi: true
    }]
})
export class ProtocolValidatorDirective implements Validator {
  @Input() protocol!: string;

  validate(control: AbstractControl): ValidationErrors|null {
    return ProtocolValidator(this.protocol)(control);
  }
}

and we use it like this:

<input type="text" protocol="wss://" [(ngModel)]="url" />

Note: For the directive selector, it's always a good idea to also look for whether there is a valid form connector added to the element:

@Directive({
   selector: '[protocol][formControlName],[protocol][formControl],[protocol][ngModel]'
})

What this translates to is that the element where our protocol directive is placed should also have either of these attributes:

1. formControlName
2. formControl
3. ngModel

This makes sure that the directive is not activated on non-form elements and you won't get any unwanted errors.

Custom async validators

The process of creating async validators in angular is exactly the same, except this time we are doing our validation in an async way (by calling an API for example).

Here is the type of async validator function:

interface AsyncValidatorFn {
  (control: AbstractControl): Promise<ValidationErrors | null> | Observable<ValidationErrors | null>
}

The only thing that is different here is that the method now returns either an Observable or a Promise.

Let's create an async validator by modifying the above validator that we wrote. Ideally, we will be using async validation for meaningful validations like:

1. Check username availability
2. Whether a user is blocked
3. If the user's phone number is part of a blocklist.

Let's create an async validator to check if a username is available.

We are gonna be creating 3 things:

1. Username Service - which makes the API call to see if the username is available
2. Validator Service - which contains the validation logic
3. Validator Directive - for using template-driven forms

Username Service

We'll mock the logic for this:

@Injectable({
  providedIn: "root"
})
export class UsernameService {
  constructor(private http: HttpClient) {}

  isUsernameAvailable(username: string) {
    return this.http.get("https://jsonplaceholder.typicode.com/users").pipe(
      map((users: any[]) => users.map((user) => user?.username?.toLowerCase())),
      map(
        (existingUsernames: string[]) => !existingUsernames.includes(username)
      ),
      startWith(true),
      delay(1000)
    );
  }
}

Async Validator Service

This is the main part of our validation process.

@Injectable({
  providedIn: "root"
})
export class UsernameValidatorService implements Validator {
  constructor(private usernameService: UsernameService) {}

  validatorFunction: AsyncValidatorFn = (control) =>
    control?.value !== ""
      ? this.usernameService
          .isUsernameAvailable(control.value)
          .pipe(
            map((isUsernameAvailable) =>
              isUsernameAvailable
                ? null
                : { username: "Username not available" }
            )
          )
      : of(null);

  validate(control: AbstractControl) {
    return this.validatorFunction(control);
  }
}

Why did we create a separate validatorFunction()? Why can't the logic be placed inside the validate() method itself?

This is done so that, we can use the validatorFunction() when we are using Reactive Forms:

export class AppComponent {
  constructor(private usernameValidator: UsernameValidatorService) {}
  username = new FormControl("", {
    asyncValidators: this.usernameValidator.validatorFunction
  });
}

Now to use the validator with Template-driven forms, we need to create a Directive to bind the validator to the element.

Async Validator Directive

@Directive({
  selector: "[username][ngModel]",
  providers: [
    {
      provide: NG_ASYNC_VALIDATORS,
      useExisting: UsernameValidatorService,
      multi: true
    }
  ]
})
export class UsernameValidatorDirective {}

We provide NG_ASYNC_VALIDATORS instead of NG_VALIDATORS in this case. And since we already have the UsernameValidatorService (which implements the Validator interface).

Note: UsernameValidatorService is providedIn: 'root', which means the Injector has the service instance with it. So we just say use that same instance of UsernameValidatorService by using the useExisitng property.

Angular takes care of subscriptions of these validators so we don't have to worry about cleaning the subscriptions later.

Code and Demo

Code: https://codesandbox.io/s/angular-async-validator-5idsm

Make sure to not just use the code as-is. For the scope of this post, things are kept simple and straightforward. Take some time to see if you can improve something in the code before you use it.

Connect with me

• Twitter
• Github
• Linkedin
• Cardify - Dynamic SVG Images for Github Readmes

Do add your thoughts in the comments section. Stay Safe ❤️

I can't emphasize more the power of directives in Angular. I've written a couple of articles showcasing how one can actually use it to implement really cool stuff. You can check some use-cases for directives here: Angular Directive Showcase.

Tables with sticky columns

We make use of the position: sticky CSS property to make an element sticky. Read more about sticky positioning at MDN.

.sticky {
  position: sticky;
  left: 0;
}

For the sticky position to work properly, at least one of top, right, bottom, or left should be specified.

The problem

Making the first column in a table sticky is super simple, you basically add the sticky class to the column.

When two columns need to stick to the left, we can't just add the sticky class to both of the columns. This is how it looks if you did so:

Here you can see the Manager column overlapping with the Company column. This is because we gave both the columns left:0.

To make it work as expected, the styles should be like this:

.company {
  position: sticky;
  left: 0px;
}

.manager {
  position: sticky;
  left: 120px; // <-- width of the company column
}

What we did here is we added the offset of the Manager column as the left property value.

Sticky Calculations

For calculating the left value, we need to find the x value of the column. If we look at the first column Company and get its offset from the left side.

We expect the x value to be 0 but we get 85 here. This is because the x value is calculated from the left side of the window to the column. For getting the left threshold of the column with respect to the table, we need to find the x value of the table. Once we get the table's offset, we can subtract it from the offset of the column.

Example of the calculation:

• Position of Table = (100, 200) // <-- x = 100
• Position of Company = (100, 200) // <-- x with respect to table = 100 - 100 = 0
• Position of Manager = (300, 200) // <-- x with respect to table = 300 - 100 = 200

Sticky Directive

We are going to create a directive to do just that. The directive can then be placed on the columns which need to be sticky. If you are thinking about why a directive for this particular use case, the calculation of the sticky thresholds can be done easily. Creating a directive makes it easy to re-use the functionality for different elements.

import { CommonModule } from '@angular/common';
import {
  AfterViewInit,
  Directive,
  ElementRef,
  NgModule,
  Optional,
} from '@angular/core';

@Directive({
  selector: '[stickyTable]',
})
export class StickyTableDirective {
  constructor(private el: ElementRef) {}

  get x() {
    return (this.el.nativeElement as HTMLElement)?.getBoundingClientRect()?.x;
  }
}

@Directive({
  selector: '[sticky]',
})
export class StickyDirective implements AfterViewInit {
  constructor(
    private el: ElementRef,
    @Optional() private table: StickyTableDirective
  ) {}

  ngAfterViewInit() {
    const el = this.el.nativeElement as HTMLElement;
    const { x } = el.getBoundingClientRect();
    el.style.position = 'sticky';
    el.style.left = this.table ? `${x - this.table.x}px` : '0px';
  }
}

@NgModule({
  declarations: [StickyDirective, StickyTableDirective],
  imports: [CommonModule],
  exports: [StickyDirective, StickyTableDirective],
})
export class StickyDirectiveModule {}

If you look at the code above, we have two directives:

1. StickyDirective
2. StickyTableDirective

The second directive is really interesting here. Why do we need a second directive? We have a separate directive that can be placed on the table to get the offset of the table. The directive can then be injected inside the main StickyDirective.

  constructor(
    private el: ElementRef,
    @Optional() private table: StickyTableDirective
  ) {}

We mark the StickyTableDirective as @Optional() so that we can add the StickyDirective directive on other elements and it can automatically be sticky with the default value.

Ref: https://angular.io/guide/hierarchical-dependency-injection#optional

Here is how we use it in HTML.

<table stickyTable>
  <tr>
    <th sticky>Company</th>
    <th sticky>Manager</th>
    <th>Employees</th>
    <th>Contractors</th>
    <th>Jobs</th>
    <th>Contracts</th>
    <th>Vacancy</th>
    <th>Offices</th>
  </tr>
  <ng-container *ngFor="let item of data">
    <tr>
      <td sticky style="min-width:200px">{{ item.company }}</td>
      <td sticky>{{ item?.manager }}</td>
      <td> {{ item?.employees }} </td>
      <td> {{ item?.contractors }} </td>
      <td> {{ item?.employees }} </td>
      <td> {{ item?.contractors }} </td>
      <td> {{ item?.employees }} </td>
      <td> {{ item?.contractors }} </td>
    </tr>
  </ng-container>
</table>

We add the stickyTable directive to the table and the sticky directive to the column.

Demo and Code

Stackblitz Link

Improvements

A lot of improvements can be made to this directive to make it more re-usable like:

• Add support for other directions.
• Generalize the StickyTableDirective to be able to use it on other elements as well.

For the sake of keeping the example here simple, I've kept it simple.

Similar Reads

1. Implement Heatmaps in a table using directives
2. Highlight text in paragraphs with a simple directive in Angular
3. Fullscreen toggle functionality in Angular using Directives.

Connect with me

• Twitter
• Github
• Linkedin
• Cardify - Dynamic SVG Images for Github Readmes

Do add your thoughts in the comments section. Stay Safe ❤️

As I always say, Directives are a really powerful feature of Angular. It can be used as an elegant solution to implement a lot of cool functionalities. You can clearly see why the directive approach makes more sense when you reach the end of the post.

Heatmaps in table

Even though it's not that often we see heatmaps in tables, but heatmaps can really add some value in terms of visualization. It would make sense in data sets where there is some kind of comparison or range.

Why Directives?

If you have this question in mind, here are some reasons which justify why creating a directive for implementing this feature will make sense. The logic can be completely moved outside of the component, making it simpler and leaner. If the logic is separated from the component, that means it's more reusable. When something is built in a re-usable manner, it will be easy to scale and maintain.

Heatmap Logic

For implementing this functionality let's look at what exactly needs to be done here. So basically, heatmaps give the user idea of the magnitude of something by variation in color or hue.

So If we have a set of numbers:

[1,2,3,4,5,6,7,8,9,10]

Here based on the value we can manipulate the intensity of a color. Meaning 1 will be the lightest shade of the color and 10 will be the color itself. So we just need to map the values to the intensity of the colors here. We can also have the opposite condition as well.

There are different ways to implement this.

Using Alpha Channel

We can easily implement heatmaps using RGBA or HSLA by just changing the alpha channel meaning the transparency of the color.

I am not going with this approach as we are also trying to generate accessible text colors based on the background color. This will ensure the text will remain readable for all the color stops.

Using HSL Color Expression

Here I am gonna be using HSL color expression to easily get the right color for each value by manipulating the L (Lightness) parameter. HSL is a really good way to express colors and manipulating the colors is very easy with it.

HSL stands for Hue Saturation Lightness and it can also have an Alpha channel with HSLA

So the idea here is to find the Lightness factor for each value. Here's how we can do it.

So here the original color value is first parsed to HSLA:

hsla(234, 77%, 46%, 1) --> Lightness = 46%

We have the min possible value for Lightness ie 0.46. So the highest value will have a lightness of 46% and for other values, it will be higher. When lightness increases it moves nearer to White.

Here is the formula:

const color = '#1b2dd0';
const [h,s,l,a] = parseHSLA(color); // <-- [234, 0.77,0.46,1]
const highestValue = 10;
const maxLightness = 1 - l; // <-- 1 - 0.46 = 0.54

const lightness = 1 - (value * maxLightness / highestValue);

// 1 --> 1 - (1 * 0.54 / 10) = (1 - 0.05) ~ 95% 
// 5 --> 1 - (5 * 0.46 / 10) = (1 - 0.23) ~ 77%
// 10 -> 1 - (10 * 0.54 / 10) = (1 - 0.54) ~ 46%

Here 10 will be the lowest number and hence we need a very light color so 95% will make it very light. Lightness % as it increases makes the color whiter. So now we have the logic in place, let's start with the directives!

Creating Heatmap Directives

So I mentioned "Directives" (plural) as we will be creating multiple directives for this functionality. To be specific 3 of them. Out of the 3, two of them are just for tagging the element and setting some metadata:

1. Heatmap Table
2. Heatmap Column
3. Heatmap Cell

Here is how we will use the directives in the template:

<table heatMapTable>
  <tr>
    <th>Company</th>
    <th>Manager</th>
    <th [heatMapColumn]="options.employees"  id="employees">
        Employees
    </th>
    <th [heatMapColumn]="options.contractors" id="contractors">
        Contractors
    </th>
  </tr>
  <ng-container *ngFor="let item of data">
    <tr>
      <td>{{ item.company }}</td>
      <td>{{ item?.manager }}</td>
      <td [heatMapCell]="item.employees" id="employees">
         {{ item?.employees }}
      </td>
      <td [heatMapCell]="item.contractors" id="contractors">
        {{ item?.contractors }}
      </td>
    </tr>
  </ng-container>
</table>

Heatmap Cell Directive

@Directive({
  selector: '[heatMapCell]',
})
export class HeatmapCellDirective {
  @Input('heatMapCell')
  heatMap = 0;

  @Input('id')
  colId = null;

  constructor(public el: ElementRef<HTMLElement>) {}
}

We have an input to pass the value into the directive and also accept the id of the column to which the cell belongs in the table. We inject the ElementRef so that we can manipulate the element later.

Heatmap Column Directive

@Directive({
  selector: '[heatMapColumn]',
})
export class HeatmapColumnDirective {
  @Input('id')
  colId = null;

  @Input('heatMapColumn')
  options = {};
}

Here we can pass options for styling like the color etc and also the id of the column.

Heatmap Table Directive

This is the main directive where all the work is done. This directive is placed on the table. And the other directives are placed on the column and the cells.

Here we can see how we can access child directives from the parent directive using ContentChildren.

@Directive({
  selector: '[heatMapTable]',
})
export class HeatmapTableDirective implements AfterViewInit {
  @ContentChildren(HeatmapCellDirective, { descendants: true })
  heatMapCells: QueryList<HeatmapCellDirective>; // <-- Get all the cells
  @ContentChildren(HeatmapColumnDirective, { descendants: true })
  heatMapColumns: QueryList<HeatmapColumnDirective>; // <-- Get all the columns

  highestValues = {};
  cells: HeatmapCellDirective[] = [];
  columns: HeatmapColumnDirective[] = [];
  config = {};

  ngAfterViewInit() {
    this.cells = this.heatMapCells.toArray();
    this.columns = this.heatMapColumns.toArray();
    this.setOptions();
    this.calculateHighestValues();
    this.applyHeatMap();
  }

  private setOptions() {
    this.columns.forEach((col) => {
      this.config = {
        ...this.config,
        [col.colId]: col.options,
      };
    });
  }

  private calculateHighestValues() {
    return this.cells.forEach(({ colId, heatMap }) => {
      if (!Object.prototype.hasOwnProperty.call(this.highestValues, colId)) {
        this.highestValues[colId] = 0;
      }
      if (heatMap > this.highestValues?.[colId])
        this.highestValues[colId] = heatMap;
    });
  }

  private applyHeatMap() {
    this.cells.forEach((cell) => {
      const { bgColor, color } = this.getColor(cell.colId, cell.heatMap);
      if (bgColor) cell.el.nativeElement.style.backgroundColor = bgColor;
      if (color) cell.el.nativeElement.style.color = color;
    });
  }

  private getColor(id: string, value: number) {
    const color = this.config[id].color;
    let textColor = null;
    let bgColor = null;
    if (color != null) {
      const [h, s, l, a] = parseToHsla(color);
      const maxLightness = 1 - l;
      const percentage = (value * maxLightness) / this.highestValues[id];
      const lightness = +percentage.toFixed(3);
      bgColor = hsla(h, s, 1 - lightness, a);
      textColor = readableColor(bgColor);
    }
    return {
      bgColor,
      color: textColor,
    };
  }

Let me break down the code.

Get access to the cells and columns

We get access to the cells to which the heatmap needs to be applied:

@ContentChildren(HeatmapCellDirective, { descendants: true })
  heatMapCells: QueryList<HeatmapCellDirective>;

This heatMapCells variable will have the list of td to which the heatMapCell was applied. Make sure to set { descendants: true }.

Note: If true include all descendants of the element. If false then only query direct children of the element.

Save the options for each column

We can save the options provided for each column in an object. Currently, we are only configuring the color, but this object can be used for all kinds of different options for customizing the heatmap for each column.

config = {
    "employees": {
        "color": "#000fff"
    },
    "contractors": {
        "color": "#309c39"
    }
}

Calculate the Highest Value for each column

We can now calculate the highest value for each column and save it in an object with the colId as the key.

highestValues = {
   employees: 1239,
   contractors: 453
}

Applying the Heatmap styles

We can now loop through the cells and then apply backgroundColor and color to the cell. Since we have injected the ElementRef in the cell, we can use the el property to modify styles:

cell.el.nativeElement.style.backgroundColor = 'blue';

We have a helper function which finds the color for each cell based on the logic we have discussed above:

  private getColor(id: string, value: number) {
    const color = this.config[id].color;
    let textColor = null;
    let bgColor = null;
    if (color != null) {
      const [h, s, l, a] = parseToHsla(color);
      const maxLightness = 1 - l;
      const percentage = (value * maxLightness) / this.highestValues[id];
      const lightness = +percentage.toFixed(3);
      bgColor = hsla(h, s, 1 - lightness, a);
      textColor = readableColor(bgColor);
    }
    return {
      bgColor,
      color: textColor,
    };
  }

The color manipulation is done using a super simple library color2k which provides a lot of utilities to mess with colors.

We have used something called readableColor() which returns black or white for best contrast depending on the luminosity of the given color. This will make our heatmap more accessible.

Demo and Code

Stackblitz Link

Final Thoughts

As you can see, there is not much code in the component. All the logic is beautifully handled inside the directive. The only complex stuff going on in the directive is finding the colors. Everything else is straightforward.

This is a very basic implementation and not perfect too. To make it better, we might have to add some validation and error handling as well. Also, this can be extended by providing more options like Ascending/Descending heatmaps, color ranges, positive and negative heatmaps, and more.

The whole idea of the blog post is to showcase how a directive can be used for implementing this feature.

Connect with me

• Twitter
• Github
• Linkedin
• Cardify - Dynamic SVG Images for Github Readmes

Do add your thoughts in the comments section. Stay Safe ❤️

Self-hosted vs Managed DB

There can be a lot of problems when you are new to this whole deployment scene. I recently faced an issue with Cartella, where all the data was lost somehow. I hosted a Postgres database in a docker container which was used by the node application running in another docker container.

One day, I realized I was not able to log in to Cartella, I checked the PM2 dashboard to see if the server is running fine or not. The API which is a node application was running fine. So next I checked the DB, and to my surprise, there was no data.

With managed DB services, we don't have to worry about anything. Everything is already taken care of for us, backups in time, restoration, guaranteed uptime, etc. The only downside is that it can be expensive. For instance, DO provides managed Postgres DB for $15/month while you can self host a Postgres DB in one of their droplets for $5/month.

The need for backup

That day I realized how important it is to have backups. Even if you don't have all the data, there is at least some data which is much better If you ask me. The application was just running as a demo and so I didn't bother much to set up backups and DB properly.

I didn't bother much as I was experimenting with deployments and stuff. Backing up of data is still important though. So once I get hold of how to deploy DB and set up connections, it's finally time to learn how to backup data.

How to create local Postgres backups

There are quite a few ways to create Postgres backups. Out of them, one of the most common methods that I could find is using pg_dump. pg_dump is a small utility for backing up Postgres databases. It can be used to back up a single DB at a time. What the utility does is that it creates an SQL query with the data in the database. So if we want to restore the backup, we could simply run the query.

pg_dump -U <DB_USER> <DB_NAME> -h <DB_HOST> -p <DB_PORT> > backup.sql

Replace the arguments like below. You can omit the host and port if its the default(localhost:5432)

pg_dump -U postgres mydb  > backup.sql

Now that we have the backup ready, It's safe to upload it elsewhere so that we don't lose the backup in case something goes wrong with our server.

Save the Postgres credentials

We need to save the Postgres DB credentials locally so that we can use pg_dump without having to enter the credentials.

1. Create a file named .pgpass in the root folder of the user( Eg: /home/ubuntu/)
2. Use an editor and add the following data (replace with your credentials) in the file

   hostname:port:database:username:password
   

3. Save the file and update the file permissions :

   chmod 600 .pgpass
   

Uploading the backup file to Cloud Storage

I'm gonna be using Object storage from Oracle Cloud (Similar to AWS S3). Oracle cloud object storage has S3 compatibility and so we can easily use any S3 compatible client to access it. For interacting with our bucket, we can use the Min.io client. Min.io client provides us with a CLI that can be used to do all kinds of operations in our object storage.

1. Install the Min.io Client:

   wget https://dl.min.io/client/mc/release/linux-amd64/mcli_20210902092127.0.0_amd64.deb
   dpkg -i mcli_20210902092127.0.0_amd64.deb
   

   Check the official docs for other OS: https://min.io/download
2. Verify the installation:

   mcli version
   

3. Connect to the storage

   mcli alias set <ALIAS> <YOUR-S3-ENDPOINT> <YOUR-ACCESS-KEY> <YOUR-SECRET-KEY>
   

4. Verify the connection by running the command to list the available buckets

   mcli ls <ALIAS>
   

   This should list all the buckets in the storage.

Ref: Minio Client Docs

Creating the backup script

We'll create a script that can create the backup and upload the same to the object storage. A very small bash script can do this:

#!/bin/bash

# Constants
USER="postgres"
DATABASE="compito"
HOST="localhost"
BACKUP_DIRECTORY="/home/ubuntu/backups"

# Date stamp (formated YYYYMMDD)
CURRENT_DATE=$(date "+%Y%m%d")

# Create the backup and then zip it
pg_dump -U $USER $DATABASE -h $HOST | gzip - > $BACKUP_DIRECTORY/$DATABASE\_$CURRENT_DATE.sql.gz

# Upload to cloud
mcli cp $BACKUP_DIRECTORY/$DATABASE\_$CURRENT_DATE.sql.gz oracle/compito-backup

You can save the code as a bash file --> backup.sh

What the script does is self-explanatory.

1. Setup the constants like the user name, database name, etc
2. Get the current time so that we can use it for tagging the backup files.
3. Create the backup using the pg_dump command and use gzip to compress it.
4. Use the minio CLI to copy the file to the cloud bucket

   mcli cp <FILE> <BUCKET>/<FOLDER>
   

Setup a CRON job to automate the backup process

It's very easy to set up a cronjob. Follow the steps and create a cronjob for our backup script.

Use any crontab string generator to create the desired frequency of the job. I plan on backing up the DB daily. Here's how the cron schedule expression looks like:

0 0 * * *

It runs the script daily at 12.00 AM.

In Linux, the cron daemon is inbuilt and looks at the Cron Tables for the scheduled jobs. We need to add a new entry in the crontab like so:

1. In the terminal, run the below command to edit the cron-table:

   crontab -e
   

2. Append the line at the end and save.

   0 0 * * * /home/ubuntu/backup.sh
   

You are all set now! You can sit back and relax now.

If you go to the object storage and check the folder, you'll be able to see the backups saved.

Note: This script is just a starter and intended to be used with demo or side projects. In a production setup, you would have to consider a lot more stuff like error handling, backup rotation, and more. Thanks to Andreas for bringing this up.

Connect with me

• Twitter
• Github
• Linkedin
• Compito - open source project management application

Do add your thoughts in the comments section. Stay Safe ❤️

It's my submission towards the Auth0 x Hashnode hackthon. It was a great experience building something within such a short span of 3 weeks. After more than 300 commits, I feel the app is having all the basic functionality that I planned.

Thought

There are a lot of ways to manage tasks on the internet from simple to really complex project management applications. I always wanted a simple and aesthetic application that should be dead simple without a lot of features. Only the essentials. And also there should be a simple way to separate projects and share them with different users without a hassle.

And for someone with a lot of side projects, I could see myself building a side project to manage my other side projects, and here we are!

Features

The basic idea is to create a simple kanban board but later came up with more features and finally decided to go with a Multi-Org project management application.

Home Page

The home page gives you an overview of the tasks and projects the user has access to. The user can see tasks that were recently created and the high-priority tasks as well.

There are quick links to get to projects and boards from the home page.

Board Page

With a simple Kanban board, you can easily track your tasks and assign it to different users within the project. You can create new tasks with ease. Cards can be dragged and dropped as you progress.

Attachments

Attachments can be added to the tasks by simply dragging and dropping them into the modal. It will be automatically uploaded and attached to the task. Multiple files with different formats are supported as well.

Orgs Page

Users can be part of multiple orgs. User can view all the orgs he/she is part of. The user can only access the data of an org. When the user logs in, If they are part of multiple orgs, they will be asked to select an org to log in to.

Projects Page

Shows the list of projects in the org the user has access to. Clicking on the project would take you to the detail page where the boards and members within the project can be seen. Users with admin access will be able to update the project details and add/remove members to/from the project.

Users

List the members in the org/project based on the role. Admin users can invite new users to the org. The list of pending user invites is also shown on the users page.

One can signup for the application using the signup page. The user will be asked to create an org when he/she first signs up. The user will be assigned the Admin role for the org.

Once the user signs up, they can invite new users to the org. The invite will be stored in the DB and whenever the user signup/login to the system, they will be able to see invites. The user can then choose to Accept/Reject the invitation.

This is how users can be added to a new org. User's with the most restrictive role User will be added to a Project and everything will be scoped to within the Project. The role hierarchy diagram explains it better.

Tech Stack

Front-end

With this idea in mind, it was time to decide the stack. I choose frameworks that I have already worked with in the past. I am most comfortable with Angular when it comes to front-end framework and the choice was very easy for me.

I have tried Tailwind a few months back, and since then It's my go-to when it comes to CSS framework. I have stopped using UI frameworks like Material, NgBootstrap, etc and it's all Tailwind.

Back-end

Next up for the back-end, I am familiar with express and NestJs. NestJs was the obvious choice here as we are dealing with TypeScript here. I love TypeScript and prefer it over JavaScript at any given time. Nest is a really good framework and is super structured which I like. So for the back-end, I decided to go with NestJs.

Next up, I decided to go with Postgres and Prisma. They work great. Prisma is the best ORM that I've used so far. I have worked with MongoDB, but I thought Prisma would better fit the whole stack. Prisma works really well with TypeScript.

One of the most important parts of the whole application is authentication. Since there is this concept of multi-org, there is a need for RBAC. Even if it wasn't for the hackathon, the first obvious choice I had in mind is Auth0. Everything you could think of when it comes to authentication and authorization, Auth0 has it all covered.

So here we are with the final Tech Stack:

• Angular
• TailwindCSS
• NGXS
• NestJs
• Prisma
• Postgres
• Auth0
• TypeScript

Deployment

Front-end is deployed to Vercel. The back-end is deployed to a VPS (ubuntu w/ Nginx) using Github Actions. The build artifacts are pushed to the server using rsync and then run using pm2. The database is also running in the same instance for reduced latency.

Refs:

• Github Action
• rsync
• pm2

Misc

Code formatting is handled by prettier and lining is taken care of by eslint. All the commits are validated using husky and commitlint. Commits follow the Conventional commits structure.

Refs:

• EsLint
• Prettier
• Commit Lint
• Husky

Folder Structure

The whole project is in a monorepo managed by Nx. The API and the Front-end are the two base apps.

All the other pages in the UI are libs. And the UI components and shared items are in the UI lib.

├── apps
│   ├── api
│   └── compito
└── libs
   ├── api-interfaces
   └── web
       ├── auth
       ├── boards
       ├── home
       ├── orgs
       ├── profile
       ├── projects
       ├── settings
       ├── tasks
       ├── users
       └── ui
            ├── components
            ├── directives
            ├── index.ts
            ├── interceptors
            ├── pipes
            ├── test-setup.ts
            ├── tokens
            └── util

Data Modelling

Here are the main models in the application. Everything revolves around an Organization aka Org.

• Org
• User
• Project
• Board
• Task
• Role
• Invite An org is the root where everything will be associated to. Inside an org, there can be multiple projects. Each project can have multiple boards. And boards can have multiple tasks.

Here's the full database schema file

The data modeling is not that complex if you see. But when we bring in roles and permissions-based access, the whole thing just becomes more complex. Now we have to validate the user's role and permission and based on that send only data that the user has access to.

Roles and Permissions

These are the roles defined in the application (No custom roles at this point):

• Admin
• Org Admin
• Project Admin
• User

The hierarchy chart should give some idea about how the users of the application will be placed.

Each role has a set of assigned permissions which is used in the front-end to show only necessary actions and in the back-end to allow access to data they are authorized to view.

Setting up Auth0

Auth0 manages all things related to user login and tokens. There is quite a bit of setup that needs to be done in Auth0 to make it work with the current architecture of the application.

The good thing is that there is a good amount of documentation and has SDKs for everything which makes our life easier. For the front-end, I used the Auth0-Angular library for everything from logins to token management.

Setting up front-end and Auth0

The first step is to create a new application in Auth0, of type Single Page Application.

1. Login to Auth0 and create a new application

Once you have given a name and selected the type of the application. Go ahead and create it.

2. Go to the Settings tab and copy the details to your application.

- Domain
- Client ID

3. Add the front-end URL in the Allowed URL

Add the front-end URL in

• Allowed Callback URLs

http://localhost:4200

• Allowed Web Origins

http://localhost:4200

• Allowed Logout URLs

http://localhost:4200/auth/login

4. Paste the above details in the environment.ts

export const environment = {
  production: false,
  baseURL: 'http://localhost:4200',
  api: 'http://localhost:3333/api',
  auth: {
    audience: '<auth0_audience>', // <-- will come back to this
    domain: '<auth0_domain>',
    clientId: '<auth0_clientId>',
    redirectUri: window.location.origin,
  },
};

5. Install the Auth0-Angular library:

npm i @auth0/auth0-angular

6. Setup the imports correctly

Import the AuthModule module in app.module.ts:

...
imports:[
AuthModule.forRoot({
      domain: environment.auth.domain,
      audience: environment.auth.audience,
      clientId: environment.auth.clientId,
      redirectUri: window.location.origin,
      errorPath: '/auth/login',
      cacheLocation: 'localstorage',
      useRefreshTokens: false,
      httpInterceptor: {
        allowedList: ['/api/*'],
      },
    })]
...

7. Add the button on the Login page

Now we just have to creat a button for login and call loginWithRedirect() method:

@Component({
  selector: 'compito-login',
  template: ` 
     <main>
       <div>
         <button btn (click)="login()">Login to Compito</button>
       </div>
    </main>`,
})
export class LoginComponent implements OnInit {
  constructor(public auth: AuthService) {}
  login() {
    this.auth.loginWithRedirect({});
  }
}
`

Ref login.component.ts source code

8. Add the route guard

Auth0 ships with a built-in Route guard that can be used to protect the routes.

 {
    path: '',
    canActivateChild: [AuthGuard], // <-- Add here
    loadChildren: () => import('./dashboard/dashboard.module').then((m) => m.DashboardModule),
  }

9. Adding the Auth Interceptor

We can then add the provided interceptor to attach the token with the API calls. Auth0 provides the interceptor out of the box making things easy. We don't have to worry about saving the token or writing the interceptor on our own.

import { AuthHttpInterceptor } from '@auth0/auth0-angular';
@NgModule({
  providers: [
    {
      provide: HTTP_INTERCEPTORS,
      useClass: AuthHttpInterceptor,
      multi: true,
    },
  ],
  bootstrap: [AppComponent],
})
export class AppModule {}

Ref app.module.ts source code

Now, Auth0 will automatically attach the token with API calls. This is all that we have to do in the front-end.

So If the configuration is done correctly, clicking on the login button should take you to the Auth0 login screen.

Ref: https://auth0.com/docs/quickstart/spa/angular

Setting up back-end and Auth0

When it comes to the back-end, we need some way to add users to Auth0 using an API. For that Auth0 provides a NodeJs SDK which is a great way to interact with Auth0 Management APIs.

Management APIs can be used to do a lot of stuff in Auth0 like:

• Create a new user
• Update user
• Change roles
• and more

Ref: Auth0 Management APIs

Ref: Auth0 Node SDK

For the SDK to work, we need to create a Machine-to-Machine or Non-Interactive application.

1. Create a Machine-To-Machine App

Go to the Applications page in Auth0 and create a new application, this time select Machine to Machine applications.

Once done, copy the credentials and paste them into the .env file so that we can later access it.

2. Create a new API in Auth0

Next up we need to create an API. Go to the API section and create a new API. The identifier that you provide is going to be the audience property for the application. If you see in the front-end environment file, we have added this property. Make sure to add AUTH0_AUDIENCE in the .env file as well.

3. Creating an Auth Service

The Auth service will provide us with an instance of the Auth0 Management APIs which can be used throughout our application.

import { ManagementClient } from 'auth0';
const managmentClient = new ManagementClient({
  domain: '{YOUR_ACCOUNT}.auth0.com',
  clientId: '{YOUR_NON_INTERACTIVE_CLIENT_ID}',
  clientSecret: '{YOUR_NON_INTERACTIVE_CLIENT_SECRET}'
});

For the full code, view auth.service.ts source code

3. Validating the API token

In NestJS, we can provide guards to validate the tokens. We can use passport to help us with the extraction and validation of the Bearer tokens.

We need to create a Passport Strategy for that:

import { Injectable, UnauthorizedException } from '@nestjs/common';
import { PassportStrategy } from '@nestjs/passport';
import * as dotenv from 'dotenv';
import { passportJwtSecret } from 'jwks-rsa';
import { ExtractJwt, Strategy } from 'passport-jwt';
import { getUserDetails } from '../core/utils/payload.util';

dotenv.config();

@Injectable()
export class JwtStrategy extends PassportStrategy(Strategy) {
  constructor() {
    super({
      secretOrKeyProvider: passportJwtSecret({
        cache: true,
        rateLimit: true,
        jwksRequestsPerMinute: 5,
        jwksUri: `${process.env.AUTH0_ISSUER_URL}.well-known/jwks.json`,
      }),
      jwtFromRequest: ExtractJwt.fromAuthHeaderAsBearerToken(),
      audience: `${process.env.AUTH0_AUDIENCE}`,
      issuer: `${process.env.AUTH0_ISSUER_URL}`,
      algorithms: ['RS256'],
    });
  }

  validate(payload: any): any {
    return payload;
  }
}

Make sure you have added AUTH0_AUDIENCE and AUTH0_ISSUER_URL in the .env file.

4. Register the strategy

We need to register this as the default strategy in passport.

import { Module } from '@nestjs/common';
import { PassportModule } from '@nestjs/passport';
import { AuthService } from './auth.service';
import { JwtStrategy } from './jwt.stategy';

@Module({
  imports: [PassportModule.register({ defaultStrategy: 'jwt' })],
  providers: [JwtStrategy, AuthService],
  exports: [PassportModule, AuthService],
})
export class AuthModule {}

Create an AuthModule and then define the default strategy. And then we import the AuthModule in the app.module.ts.

5. Setting up the Auth Guard

Once the AuthModule is imported, we can now provide the Auth Guard:

pimport { Module } from '@nestjs/common';
import { APP_GUARD } from '@nestjs/core';
import { AuthGuard } from '@nestjs/passport';

@Module({
  imports: [
    AuthModule,
  ],
  providers: [
    {
      provide: APP_GUARD,
      useClass: AuthGuard('jwt'),
    },
  ],
})
export class AppModule {}

If you don't need any custom login in the Guard, directly import and use the AuthGuard from @nestjs/passport. Else you can create a custom guard and use it as I did in this case.

Note: Here we have enabled the guard globally. You can also enable guards per request in NestJs.

So now when the Front-end sends the Bearer token to the Back-end, it's validated by the guard and if successful, the Details in the Access Token are available for us in the Request prop (req.user).

Ref: https://auth0.com/blog/developing-a-secure-api-with-nestjs-getting-started/

Multi-Org User Management

Since the application is a multi-org application, each user can have access to different orgs. For each org, the user will have a different role.

In the example above Tomy is an Admin for Org B while he is a Project Admin for Org A.

For the MVP, the initial way is to lock the user to one org on login. So If they want to access another org, they can log out of the current org and then log in to another one. In this way, a lot of complexity tied up to the RBAC can be removed.

This is the proposed user login flow.

1. User logins to the system.
2. If the user is only part of one org, log in directly
3. Else redirect the user to the org selection page, where the user can select an org to log in to.
4. User selects and org, which completes the login.

Implementing the Login flow in Auth0

I thought this could be a problem in the architecture and might not be feasible. But to my surprise, all this was super easy thanks to Auth0 Actions. Auth0 Actions are a game-changer. It opens up the door to a lot of extendability. The whole login flow that I mentioned above can be done using an action.

Creating an action

Go to Actions > Custom and Create a new action. For the Trigger, we need to go with Login / Post Login.

Once you click on the action, we can write custom JavaScript to do a lot of stuff. Our main aim here is to check and redirect the user to an Org Selection landing page if the user is part of multiple orgs.

Also once the user is logged in, we need to add some metadata into the access token so that we can easily access them and don't have to hit the DB for every request. Here is the information that we need to add to the tokens.

• User Id - user id associated with the logged-in user
• Email - logged in user's email
• Org Id - the current logged in org id
• Role Details - the role of the user for the current org

Setup the action

We need to set few environment variables in the action. Then add axios as a dependency for the action.

1. Once the user is logged in, we call our API to fetch the details of the user. For validating pre-auth request, inside actions we can create sessions_token which can be validated in the back-end. The session token payload can be used to transport any information to the back-end.

   const token = api.redirect.encodeToken({
      secret: event.secrets.TOKEN_SECRET,
      payload: {
        email: event.user.email,
        userId: event.user.user_metadata.userId,
      },
    });
    const { status, data } = await axios.get(`${event.secrets.API_URL}/users/auth`, {
      headers: {
        'x-session-token': token,
      },
    });
   

2. If the user is part of multiple orgs, we redirect the user to the org selection page:

    if (partOfMultipleOrgs || pendingInvites) {
      return api.redirect.sendUserTo(event.secrets.ORG_SELECT_REDIRECT, {
        query: { session_token: token },
      });
    }
   

   The session_token is passed as a query so that once in the org selection page, we can use the same to get the org details from the Back-end.

3. Else if the user is part of only one org, we proceed with attaching custom claims to the tokens:

   api.accessToken.setCustomClaim(`${namespace}/role`, role);
   api.idToken.setCustomClaim(`${namespace}/role`, role);
   

   It's that simple, now our tokens will have the role information. The user gets redirected to the org selection page. We get the session_token in the front-end and make an API call to get the user's orgs and pending invites. When the user clicks on the org, we call the /continue API from the front-end which will resume the action.

   loginToOrg(orgId: string) {
    window.location.href = `https://${this.environment.auth.domain}/continue?state=${this.state}&orgId=${orgId}`;
   }
   

Ref: Front-end API Call

exports.onContinuePostLogin = async (event, api) => {}

We then attach the role and other info to the token. Here is the full action code:

const axios = require('axios'); //<-- require axios for making api calls

exports.onExecutePostLogin = async (event, api) => {
  const userId = event.user.user_metadata.userId; // <-- Get user Id
  if (!userId) {
    return api.access.deny(`Access denied`);
  }
  try {
    // Create the session token
    const token = api.redirect.encodeToken({
      secret: event.secrets.TOKEN_SECRET,
      payload: {
        email: event.user.email,
        userId: event.user.user_metadata.userId,
      },
    });

    // Get user details from the back-end
    const { status, data } = await axios.get(`${event.secrets.API_URL}/users/auth`, {
      headers: {
        'x-session-token': token,
      },
    });
    if (status !== 200) {
      return api.access.deny(`Something went wrong!`);
    }

    const { partOfMultipleOrgs, pendingInvites, orgs, roles, projects } = data;
    // If the user is part of multiple orgs, redirect to org selection page
    if (partOfMultipleOrgs || pendingInvites) {
      return api.redirect.sendUserTo(event.secrets.ORG_SELECT_REDIRECT, {
        query: { session_token: token },
      });
    }
    const namespace = event.secrets.CLAIM_NAMESPACE;
    // Add extra data to tokens as custom claims
    if (event.authorization) {
      const org = orgs[0];
      const role = roles[org.id];
      api.accessToken.setCustomClaim(`${namespace}/role`, role);
      api.accessToken.setCustomClaim(`${namespace}/projects`, projects);
      api.accessToken.setCustomClaim(`${namespace}/org`, org);
      api.accessToken.setCustomClaim(`${namespace}/userId`, userId);
      api.accessToken.setCustomClaim(`${namespace}/email`, event.user.email);
      api.idToken.setCustomClaim(`${namespace}/role`, role);
      api.idToken.setCustomClaim(`${namespace}/projects`, projects);
      api.idToken.setCustomClaim(`${namespace}/org`, org);
      api.idToken.setCustomClaim(`${namespace}/userId`, userId);
    }
  } catch (e) {
    return api.access.deny(`Something went wrong`);
  }
};


// Once the user has selected the org in UI, we will do the same thing as above
exports.onContinuePostLogin = async (event, api) => {
  try {
    const userId = event.user.user_metadata.userId;
    const orgId = event.request.query.orgId;
    if (!orgId) {
      return api.access.deny(`Something went wrong`);
    }
    const token = api.redirect.encodeToken({
      secret: event.secrets.TOKEN_SECRET,
      payload: {
        email: event.user.email,
        org: orgId,
        userId: event.user.user_metadata.userId,
      },
    });
    const { status, data } = await axios.get(`${event.secrets.API_URL}/users/auth`, {
      headers: {
        'x-session-token': token,
      },
    });
    console.log('Project Response Status', status);
    if (status !== 200 || data == null) {
      return api.access.deny(`Something went wrong!`);
    }
    const { org, role, projects } = data;
    const namespace = event.secrets.CLAIM_NAMESPACE;
    if (event.authorization) {
      api.accessToken.setCustomClaim(`${namespace}/role`, role);
      api.accessToken.setCustomClaim(`${namespace}/projects`, projects);
      api.accessToken.setCustomClaim(`${namespace}/org`, org);
      api.accessToken.setCustomClaim(`${namespace}/userId`, userId);
      api.accessToken.setCustomClaim(`${namespace}/email`, event.user.email);
      api.idToken.setCustomClaim(`${namespace}/role`, role);
      api.idToken.setCustomClaim(`${namespace}/projects`, projects);
      api.idToken.setCustomClaim(`${namespace}/org`, org);
      api.idToken.setCustomClaim(`${namespace}/userId`, userId);
    }
  } catch (error) {
    return api.access.deny(`Something went wrong`);
  }
};

Ref: Aut0 Action source code Note: If you are planning to copy the actions code, copy it from the source code.

Once the action is ready and all the environment variables are configured properly, Deploy the action.

Implementing the action

Head to Actions > Flows and Choose Login Flow.

Now we can add the action to our login flow by just dragging and dropping the action in the flow.

Once you apply the flow, we are all set. See the outcome below:

Setting up Roles and Permissions in Back-end

In the back-end we need to set two guards:

• Role Guard - to check if the user has the required role to perform the operation
• Permission Guard - to check if the user has required permission to perform the operation

Role Points:

export const ROLE_LEVEL = {
  'user': 1,
  'project-admin': 2,
  'org-admin': 3,
  'admin': 4,
  'super-admin': 5,
};

User has the lowest level of access or is the most restrictive role we can say.

Ref: Role guard source code

Ref: Permission guard source code

I'll write separate articles about them.

This is how we would use these guards:

  @UseGuards(RolesGuard, PermissionsGuard) // <-- apply guards
  @Role('org-admin') // <-- set min required role
  @Permissions(PERMISSIONS.project.create) // <-- permission required
  @Post()
  create(@Body() project: ProjectRequest, @Req() req: RequestWithUser) {
    return this.projectService.create(project, req.user);
  }

Handling Role and Permission in UI

In the UI, the user should only be seeing actions that they have access to. So for example a Project Admin should not be able to see the Edit option in the Org card.

For implementing this, I created a simple directive that does the job.

@Directive({
  selector: '[permission]',
})
export class PermissionsDirective implements OnInit, OnDestroy {
  private loggedInUser!: UserDetails;
  private requiredPermission!: string;

  subscription!: Subscription;

  @Input()
  set permission(permission: string) {
    this.requiredPermission = permission;
    this.updateView();
  }
  constructor(
    private tpl: TemplateRef<any>,
    private vcr: ViewContainerRef,
    private authService: AuthService,
    private cdr: ChangeDetectorRef,
  ) {}

  ngOnInit() {
    this.subscription = this.authService.user$.pipe(formatUser()).subscribe((user) => {
      if (user) {
        this.vcr.clear();
        this.loggedInUser = user;
        this.updateView();
      }
    });
  }

  ngOnDestroy() {
    this.subscription.unsubscribe();
  }

  private updateView() {
    if (this.hasPermission()) {
      this.vcr.createEmbeddedView(this.tpl);
    } else {
      this.vcr.clear();
    }
    this.cdr.markForCheck();
  }

  private hasPermission() {
    if (!this.loggedInUser) return false;
    const userPermissions = this.loggedInUser.role.permissions;
    if (userPermissions) {
      return userPermissions.includes(this.requiredPermission);
    }
    return false;
  }
}

The directive will only render the component if the user has access to the item.

Attachments and Object storage

For saving and managing the files, I've used Oracle Cloud which provides object storage under its free tier . For managing the uploads, minio (https://docs.min.io/docs/minio-client-complete-guide.html) client is used for interacting with the S3 compatible APIs of Oracle Cloud.

@Injectable()
export class FileStorageService {
  private client: Client;
  private logger = new CompitoLogger('FILE_STORAGE');
  constructor(private config: ConfigService) {
    this.client = this.createMinioInstance();
  }

  private createMinioInstance(): Client {
    return new Client({
      endPoint: this.config.get('FILE_STORAGE_URI'),
      useSSL: true,
      pathStyle: true,
      region: 'ap-mumbai-1',
      accessKey: this.config.get('FILE_STORAGE_ACCESS_KEY'),
      secretKey: this.config.get('FILE_STORAGE_ACCESS_SECRET'),
    });
  }

  async get(path: string) {
    const bucket = this.config.get('BUCKET');
    return this.client.getObject(bucket, path);
  }

  async upload(file: Express.Multer.File, name: string, folder: string) {
    const bucket = this.config.get('BUCKET');
    const fileName = `${folder}/${name}.${extension(file.mimetype)}`;
    try {
      const result = await this.client.putObject(bucket, fileName, file.buffer);
      return { result, filePath: fileName };
    } catch (error) {
      this.logger.error('upload', 'Failed to upload', error);
      return null;
    }
  }

  async delete(path: string) {
    const bucket = this.config.get('BUCKET');
    try {
      await this.client.removeObject(bucket, path);
      return true;
    } catch (error) {
      this.logger.error('delete', 'Failed to delete object', error);
      return false;
    }
  }
}

Full source code

Roadmap

• Task Dates and Time tracking
• Calendar view
• Activity Bar
• Notifications (Email and Push)
• Audit Trail Logs
• Easy Org Switching
• Tags
• Sub Tasks

I am planning to write about individual features and API in-depth as it would be very hard to include all in this one blog post. So it makes sense to maybe make a series on the same in the future. Till then, feel free to hit me up If you have any questions or doubts.

Best practices

Validation

The server uses joi for validating the request even before reaching the services. There is also a custom logger implemented to give a clear idea of the errors. The custom logger can be used to connect to log monitoring services like Sentry in the future.

Error handling

Error handling is very important in any project and so is logging. With proper logs in place, it's much easier to sport the bugs. The errors are streamed by pm2 and are visible via the PM2 Dashboard.

Errors are also sent to Sentry for easy RCA. Sentry has a good integration and setting up was not that difficult. Will try to write about it in a separate blog.

Database backups

Database backups are created locally on a daily basis and uploaded to object storage in the cloud. More details about the setup here: How to backup Postgres data to object storage.

Security and Others

When it comes to API Security, there is CORS, Rate limiting, etc implemented. Thanks to middleware like

• Helmet
• Express Rate Limit

Since the API is proxied via Nginx, by setting up brolti compression, the API payload can be compressed very well making APIs faster.

I am pretty much satisfied with the outcome of the project given I was able to put all this together in under 3 weeks of my free time. Code quality is checked by SonarQube. There are few smells, which can be easily cleaned up.

Lighthouse Scores

The initial lighthouse scores without much optimizations done are pretty good I would say. The test is done on the production website. There are a lot of improvements in the application and I can see the scores improving more over time.

As always thanks to Vercel for making the websites super fast.

Links

• Github Repo
• Demo

Update

Thanks all for the massive support. We've crossed 100 stars on Github, More than 120 users signed up in Auth0, and also around 1.5K pageviews after the launch.

Connect with me

• Twitter
• Github
• Linkedin
• Cardify - Dynamic SVG Images for Github Readmes

Do add your thoughts in the comments section. Stay Safe ❤️

So when I say custom form controls, I am talking about those elements that are not your typical controls like input fields, radio buttons, or checkboxes. For example, a star rating component or a knob. These are not available out of the box.

We can also make sections in a form as child components which can be then used as custom form controls. In this way, larger forms can be broken down into manageable pieces.

For all the default form controls like input field, radio button, checkbox, select dropdown, etc, custom control value accessors are already written and shipped with Angular. Eg: CheckboxControlValueAccessor

We will be talking more about ControlValueAccessor it and how to use it to create really cool form.

Custom Form Elements

When we hear the term form, we would be thinking of few input text fields and maybe some checkboxes and stuff. But when it comes to really complex forms where we have a lot of custom buttons, lists, and selections, the whole form will become very complex. And managing such a complex form would be a problem.

When there are a lot of custom form elements or when the form starts to get big, it's probably a good idea to break it into smaller sections. Placing everything in a single template would make it really messy.

We can break down the form into multiple components and then connect it with the main form.

Custom form control in Angular

ControlValueAccessor is something that comes with Angular. It acts as a bridge between DOM elements and the angular Form API.

So If you have a custom element that you would like to connect to your form, you have to make use of ControlValueAccessor to make the element compatible with Angular Forms API. Doing so will enable the element to be connected using ngModel (Template Driven Forms) or formControl (Reactive Forms).

Let's take a look at how do we create a custom form control.

When I started with Angular, I was not aware that something like this existed. I remember when I wrote child components for forms and used @Input() and @Output() to receive and send form values to the parent form component. I used to listen to the changes in the child component and then emit the values to the parent.

In the parent, the values will be taken and used to patch the form. This was until I came across the magical ControlValueAccessor. No more inputs and outputs, everything just works.

Implement the ControlValueAccessor interface.

Step 1 is to implement the interface in the custom component. The interface would ask us to add few methods in our class.

interface ControlValueAccessor {
  writeValue(obj: any): void
  registerOnChange(fn: any): void
  registerOnTouched(fn: any): void
  setDisabledState(isDisabled: boolean)?: void
}

Let us see what each of the methods is doing. Once we are clear on how things are, we can dive into the implementation.

• writeValue() - this function is called by the Forms API to update the value of the element. When ngModel or formControl value changes, this function gets called and the latest value is passed in as the argument to the function. We can use the latest value and make changes in the component. (ref)
• registerOnChange() - we get access to a function in the argument that can be saved to a local variable. Then this function can be called when there are any changes in the value of our custom form control. (ref)
• registerOnTouched() - we get access to another function that can be used to update the state of the form to touched. So when the user interacts with our custom form element, we can call the saved function to let Angular know that the element has been interacted with. (ref)
• setDisabledState() - this function will be called by the forms API when the disabled state is changed. We can get the current state and update the state of the custom form control. (ref)

Once we implement these functions, the next step is to provide the NG_VALUE_ACCESSOR token in the component's providers array like so:

const COUNTRY_CONTROL_VALUE_ACCESSOR: Provider = {
  provide: NG_VALUE_ACCESSOR,
  useExisting: forwardRef(() => CustomFormControlComponent),
  multi: true,
};

@Component({
  selector: 'app-country-selector',
  template: ``,
  providers: [COUNTRY_CONTROL_VALUE_ACCESSOR], // <-- provided here
})
export class CustomFormControlComponent implements ControlValueAccessor {}

Note: Here I created a provider constant and then passed it into the providers. Also you can see the use of forwardRef (ref) here. It is needed because we are referring to the CountrySelectorComponent class which is not defined before its reference.

So now that we know what each of these functions does, we can start implementing our custom form element.

Basic Form

We are going to take a look at the base form that we are gonna work with. We just have some basic input fields and 2 custom form elements.

{
    name: 'Adithya',
    github: 'https://github.com/AdiSreyaj',
    website: 'https://adi.so',
    server: 'IN',
    communications: [{
          label: 'Marketing',
          modes: [{
              name: 'Email',
              enabled: true,
            },
            {
              name: 'SMS',
              enabled: false,
            }],
        },
        {
          label: 'Product Updates',
          modes: [{
              name: 'Email',
              enabled: true,
            },
            {
              name: 'SMS',
              enabled: true,
            }],
        },
      ]
  }

This is how we need the data to be. Here the server and the communications fields are going to be connected to a custom form control. We are using Reactive Forms in the example.

Here is how our form will look like:

const form = this.fb.group({
    name: [''],
    github: [''],
    website: [''],
    server: [''],
    communications: [[]]
  });

and in the template

<form [formGroup]="form">
    <div class="form-group">
      <label for="name">Name</label>
      <input type="text" id="name" formControlName="name">
    </div>
    <div class="form-group">
      <label for="github">Github</label>
      <input type="url" id="github" formControlName="github">
    </div>
    <div class="form-group">
      <label for="website">Website</label>
      <input type="url" id="website" formControlName="website">
    </div>
    <div class="form-group">
      <label>Region</label>
      <app-country-selector formControlName="server"></app-country-selector>
    </div>
    <div class="form-group">
      <label>Communication</label>
      <app-communication-preference formControlName="communications"></app-communication-preference>
    </div>
  </form>

Notice in the above template we are directly using formControlName on the app-country-selector and app-communication-preference components. This will be only possible if those components are implementing the ControlValueAccessor interface. This is how you make a component behave like a form control.

Country Selector custom form control

We are going to see how to implement a cool country selector component as a custom form control that can be directly connected to a form. In this example, I'll be using Reactive Forms.

The component is pretty straightforward, we will give the user to select one country from a given list. The behavior is similar to a radio button. The only difference here is that we are using our own custom component to implement this design.

As always, I start by creating a new module and component for our country selector form control.

Here is how we implement the ControlValueAccessor for our country selector component.

const COUNTRY_CONTROL_VALUE_ACCESSOR: Provider = {
  provide: NG_VALUE_ACCESSOR,
  useExisting: forwardRef(() => CountrySelectorComponent),
  multi: true,
};

We provide it in the providers array inside the @Component decorator.

@Component({
  selector: 'app-country-selector',
  template: `
    <div>
      <ng-container *ngFor="let country of countries">
        <button [disabled]="disabled" (click)="selectCountry(country.code)"
             [class.selected]="!disabled && selected === country.code">
          <ng-container *ngIf="!disabled && selected === country.code">
            <!-- Checkmark Icon -->
          </ng-container>
          <img [src]="...flag src" [alt]="country.name" />
          <p>{{ country?.name }}</p>
        </button>
      </ng-container>
    </div>
  `,
  providers: [COUNTRY_CONTROL_VALUE_ACCESSOR],
})
export class CountrySelectorComponent implements ControlValueAccessor {
  countries = [
    { code: 'IN', name: 'India' },
    { code: 'US', name: 'United States' },
    { code: 'GB-ENG', name: 'England' },
    { code: 'NL', name: 'Netherlands' },
  ];
  selected!: string;
  disabled = false;
  private onTouched!: Function;
  private onChanged!: Function;

  selectCountry(code: string) {
    this.onTouched(); // <-- mark as touched
    this.selected = code;
    this.onChanged(code); // <-- call function to let know of a change
  }

  writeValue(value: string): void {
    this.selected = value ?? 'IN';
  }
  registerOnChange(fn: any): void {
    this.onChanged = fn; // <-- save the function
  }
  registerOnTouched(fn: any): void {
    this.onTouched = fn; // <-- save the function
  }
  setDisabledState(isDisabled: boolean) {
    this.disabled = isDisabled;
  }
}

If the user has given an initial value to server in the form, we will get the initial value in the writeValue() method. We get the value and assign it to our local variable selected which manages the state.

When the user clicks on a different country, we mark the field as touched and then assign the value to the selected variable. The main part is we also call the onChanged method and pass the newly selected country code. This will set the new value as the form control's value.

By using the argument from setDisabledState() method we can implement the disabled state for our component. So If we trigger disable from the form using:

this.form.get('server').disable();

Doing the above will trigger a call to setDisabledState() method where the state isDisabled is passed, which is then assigned to a local variable disabled. Now we can use this local variable to add a class or disable the button.

setDisabledState(isDisabled: boolean) {
    this.disabled = isDisabled;
  }

That is all! We have successfully created a custom form control. Check the GitHub repo for full code.

Communication Preferences custom form control

Now let's see how to implement the second custom form control in our form, which allows user to select their communication preferences.

This is also a very simple component that has a bunch of checkboxes. We could have added this in the same parent component where the form is initialized. But by creating a separate component, we are making it more maintainable.

const COM_PREFERENCE_CONTROL_VALUE_ACCESSOR: Provider = {
  provide: NG_VALUE_ACCESSOR,
  useExisting: forwardRef(() => CommunicationPreferenceComponent),
  multi: true,
};

@Component({
  selector: 'app-communication-preference',
  template: `<div>
    <ul>
      <ng-container *ngFor="let item of options; index as i">
        <li>
          <p>{{ item?.label }}</p>
          <div>
            <ng-container *ngFor="let mode of item.modes; index as j">
              <div>
                <input
                  type="checkbox"
                  [id]="item.label + mode.name"
                  [(ngModel)]="mode.enabled"
                  (ngModelChange)="handleChange(i, j, $event)" />
                <label [for]="item.label + mode.name">{{ mode.name }}</label>
              </div>
            </ng-container>
          </div>
        </li>
      </ng-container>
    </ul>
  </div>`,
  providers: [COM_PREFERENCE_CONTROL_VALUE_ACCESSOR],
})
export class CommunicationPreferenceComponent implements ControlValueAccessor {
  options: CommunicationPreference[] = [];
  private onTouched!: Function;
  private onChanged!: Function;
  handleChange(itemIndex: number, modeIndex: number, change: any) {
    this.onTouched();
    this.options[itemIndex].modes[modeIndex].enabled = change;
    this.onChanged(this.options);
  }

  writeValue(value: any): void {
    this.options = value;
  }
  registerOnChange(fn: any): void {
    this.onChanged = fn;
  }
  registerOnTouched(fn: any): void {
    this.onTouched = fn;
  }
}

Again it's the same thing we are doing, we have an options variable that manages the local state of the component. When there is any value-change triggered by the form, we get the new value in the writeValue method, we update the local state with the changed value. When the user makes any change, we update the local state and call the onChanged method and pass the updated state which updates the form as well.

Find the complete code for the component in the repo.

Final Thoughts

Angular makes it really easy to implement custom form control using ControlValueAccessor. By implementing few methods, we can directly hook our component to a Reactive or Template Driven form with ease.

We can write all sorts of crazy form elements and use them without writing logic to handle communication between parent and child. Let the forms API do the magic for us.

We can also use this approach to break sections of the form into their own individual component. This way if the form is big/complex, we can break then down into smaller components that can be easily managed.

Code and Demo

• Github: https://github.com/adisreyaj/ng-custom-form-elements
• Demo: https://ng-custom-form-elements.vercel.app/

Connect with me

• Twitter
• Github
• Linkedin
• Cardify - Dynamic SVG Images for Github Readmes

Do add your thoughts in the comments section. Stay Safe ❤️

Accordions

Accordions in general are vertically stacked lists of headers when clicked reveals some content. Accordions or expandable sections are seen as part of almost all the UI libraries out there.

If we take a look at Angular material, we have Expansion Panel (ref) and in Ng Bootstrap its called simple Accordion (ref).

Building a custom accordion

What we are gonna build is a much simpler version of these. And as always, the whole idea behind this is to help you explore some possibilities of Angular. This blog post would be mostly about how we can use Content Projection (ref) in Angular to create reusable and customizable UI components.

We are not going to rely on any 3rd party library for building our component. We are going to use Directives, TemplateRef, Animation etc in this post.

Planning it out

If we see the anatomy of an accordion component, we need a main parent container to accommodate all the different items inside. Each of the items will contain a header and a content part.

The content part is completely dynamic and we don't have to worry about it. When it comes to the header, there will be:

• Default header with title and the toggle icon
• Default header with custom title
• Completely custom header

Building Accordion component

Let's start by creating a dedicated module for the component. Here are the items that we need to create along with the module:

• Accordion Parent Component
• Accordion Item Directive
• Accordion Header Directive
• Accordion Title Directive
• Accordion Content Directive

lib/
├─ accordion/
│  ├─ directives/
│  │  ├─ accordion-item.directive.ts
│  │  ├─ accordion-content.directive.ts
│  │  ├─ accordion-title.directive.ts
│  │  ├─ accordion-header.directive.ts
│  ├─ accordion.component.html
│  ├─ accordion.component.css
│  ├─ accordion.component.ts
│  ├─ accordion.module.ts

Here's how the module will look like:

import { CommonModule } from "@angular/common";
import { NgModule } from "@angular/core";

import { AccordionComponent } from "./accordion.component";
import { AccordionItem } from "./directives/accordion-item.directive";
import { AccordionContent } from "./directives/accordion-content.directive";
import { AccordionTitle } from "./directives/accordion-title.directive";
import { AccordionHeader } from "./directives/accordion-header.directive";

@NgModule({
  declarations: [
    AccordionComponent,
    AccordionItem,
    AccordionContent,
    AccordionTitle,
    AccordionHeader
  ],
  imports: [CommonModule],
  exports: [
    AccordionComponent,
    AccordionItem,
    AccordionContent,
    AccordionTitle,
    AccordionHeader
  ]
})
export class AccordionModule {}

We start with the directives first, as most of them will be used as selectors and will not have any logic inside them. We inject the TemplateRef so that we can get access to the template reference of the host elements where these directives are placed.

Content Directive

@Directive({
  selector: "[accordionContent]"
})
export class AccordionContent {
  constructor(public templateRef: TemplateRef<any>) {}
}

Header Directive

@Directive({
  selector: "[accordionHeader]"
})
export class AccordionHeader {
  constructor(public templateRef: TemplateRef<any>) {}
}

Title Directive

@Directive({
  selector: "[accordionTitle]"
})
export class AccordionTitle {
  constructor(public templateRef: TemplateRef<any>) {}
}

Item Directive

@Directive({
  selector: "accordion-item"
})
export class AccordionItem {
  @Input() title = "";
  @Input() disabled = false;
  @ContentChild(AccordionContent) content: AccordionContent;
  @ContentChild(AccordionTitle) customTitle: AccordionTitle;
  @ContentChild(AccordionHeader) customHeader: AccordionHeader;
}

In the item directive, we set some @Input() for getting data from the user. And We have taken the reference of the content, title, and the header using the @ContentChild() (ref) decorator.

This is how the title, content, and header will be passed in the template:

<accordion-item>
     <ng-template accordionHeader>ng-template>
     <ng-template accordionTitle>ng-template>
     <ng-template accordionContent>ng-template>
</accordion-item>

Once we have the basic setup ready, the main component is the AccordionComponent or the parent component.

Accordion component

We have to essentially manage only a single state for managing the expanded items.

@Component({
  selector: "accordion",
  templateUrl: "./accordion.component.html",
  styleUrls: ["./accordion.component.css"],
  changeDetection: ChangeDetectionStrategy.OnPush,
})
export class AccordionComponent {
  expanded = new Set<number>();
  /**
   * Decides if the single item will be open at once or not.
   * In collapsing mode, toggling one would collapse others
   */
  @Input() collapsing = true;

  @ContentChildren(AccordionItem) items: QueryList<AccordionItem>;

  /**
   * Make the toggle function available to be called from
   * outside.
   * @param index - Index of the accordion item
   */
  getToggleState = (index: number) => {
    return this.toggleState.bind(this, index);
  };

  toggleState = (index: number) => {
    if (this.expanded.has(index)) {
      this.expanded.delete(index);
    } else {
      if (this.collapsing) {
        this.expanded.clear();
      }
      this.expanded.add(index);
    }
  };
}

A Set is used to maintain the state of currently expanded accordion items. A set guarantees distinct values.

  @ContentChildren(AccordionItem) items: QueryList<AccordionItem>;

This will give us the accordion items in the template which can be used to iterate and display the contents in the view.

An input collapsing is taken from the user which defines the behavior of the accordion. It tells the accordion whether to close other items when an item is expanded.

• collapsing = true will make sure there will be only one item open at a time
• collapsing = false means multiple items can be open at once

A function called toggleState is added which basically toggles the state of an item. We pass the index of the item, it will check and expand/collapse the item.

The getToggleState function is a special one which I will discuss in a bit.

Accordion component template

Let's now see how this is all laid out.

<section class="accordion">
  <div *ngFor="let item of items;index as i"
    class="accordion__item" [class.disabled]="item.disabled" [class.active]="expanded.has(i)">
    <ng-container
      [ngTemplateOutlet]="(item?.customHeader?.templateRef || defaultHeader)"
      [ngTemplateOutletContext]="{$implicit: item, index: i, toggle: getToggleState(i)}"></ng-container>
    <div class="accordion__content" [class.expanded]="expanded.has(i)" [@contentExpansion]="expanded.has(i) ? 'expanded':'collapsed'">
      <ng-container *ngTemplateOutlet="item?.content?.templateRef"></ng-container>
    </div>
  </div>
</section>

<ng-template #defaultHeader let-item let-index="index">
  <header class="accordion__header"
    (click)="item.disabled ? {} :toggleState(index)">
    <ng-container *ngTemplateOutlet="item?.customTitle?.templateRef || defaultTitle"></ng-container>
    <button class="accordion__toggle-btn" [disabled]="item.disabled">
      <svg
        xmlns="http://www.w3.org/2000/svg"
        viewBox="0 0 24 24" width="24" height="24">
        <path fill="none" d="M0 0h24v24H0z" />
        <path d="M12 13.172l4.95-4.95 1.414 1.414L12 16 5.636 9.636 7.05 8.222z"/>
      </svg>
    </button>
  </header>
  <ng-template #defaultTitle>
    <p class="accordion__title">{{item?.title}}</p>
  </ng-template>
</ng-template>

We are just iterating over the items array (Querylist), which basically is a list of the accordion-items passed inside our accordion component.

Content Projection

<ng-container
      [ngTemplateOutlet]="(item?.customHeader?.templateRef || defaultHeader)"
      [ngTemplateOutletContext]="{$implicit: item, index: i, toggle: getToggleState(i)}">
</ng-container>

If the user has provided a custom header, we use that template or we use our defaultHeader. We use something called ngTemplateOutlet (ref) to project the template into the view.

ngTemplateOutletContext is used to pass some information into the template. We pass:

• item - the current accordion item.
• index - index of the accordion item (required for toggling it).
• toggle - a function that can be called to toggle the accordion item.

The toggle property is a function that has the current context and the index bound to it. So whenever it's called, that particular item will automatically be toggled without passing the index value to the function.

Also, see that it's an arrow function, that is the reason we can call the toggleState function with the proper context (this).

getToggleState = (index: number) => {
  return this.toggleState.bind(this, index);
};

Note: If you are worried about using methods in the template, there are two ways to make this code better:

1. Memoize the getToggleState method

import { memoize } from 'lodash-es';

getToggleState = memoize((index: number) => {
  console.log('Called');
  return this.toggleState.bind(this, index);
})

2. Use Custom Pipe

@Pipe({
  name:'getToggleFunction'
})
export class TogglePipe implements PipeTransform{
  transform(i: number, toggleFn: Function){
    return () => toggleFn(i);
  }
}

and make necessary change the template:

<ng-container 
  [ngTemplateOutlet]="(item?.customHeader?.templateRef || defaultHeader)"
  [ngTemplateOutletContext]="{$implicit: item, index: i, toggle: i | getToggleFunction: toggleState}"
</ng-container>

Usage

This is how we use the ngTemplateOutletContext:

<ng-template #defaultHeader let-item let-index="index"></ng-template>

When let-item is called, it refers to the implicit property that we attached ({$implicit: item}). It just means that its the default value to use when the user didn't specify which property they want (see how index is queried).

By adding let-index="index", we are assigning the index property to a variable called index. This would make the variable available to use within the template.

Finally, lets see how we can use the component. First thing is that the AccordionModule should be imported before it can be used.

Here are all the different ways you can use the component:

Basic usage

<accordion [collapsing]="collapsing">
    <accordion-item title="Super simple Accordion">
        <ng-template accordionContent>
          <div class="p-4">
            A simple and customizable accordion component.
          </div>
        </ng-template>
    </accordion-item>
</accordion>

With Custom title

<accordion [collapsing]="collapsing">
   <accordion-item>
      <ng-template accordionTitle>
          <div class="flex space-x-2">
            <p>Custom Title</p>
          </div>
        </ng-template>
        <ng-template accordionContent>
            <div class="p-4">
              This is a simple implementation where title part is custom.
            </div>
        </ng-template>
     </accordion-item>
</accordion>

With Custom Header

<accordion [collapsing]="collapsing">
   <accordion-item title="Super simple Accordion">
     <ng-template accordionHeader let-toggle="toggle">
          <div class="flex items-center justify-between px-4 h-12 bg-purple-200">
            <p> Custom Header <span>(with custom toggle button)</span><p>
            <div class="flex space-x-2">
              <button (click)="toggle()">Toggle</button>
            </div>
          </div>
        </ng-template>
        <ng-template accordionContent>
            <div class="p-4">
              This is a <strong>complete custom header</strong> implementation.
            </div>
        </ng-template>
      </accordion-item>
</accordion>

See how the toggle function is first defined let-toggle="toggle" and then used in the button <button (click)="toggle()">Toggle</button>

This is how you can create a simple, but a customizable accordion component in angular.

Bonus: Animations

I have added Angular animations for animating the content when the user toggles the accordion item.

Only two things have to be added for this. First we need to defined our animation in the @Component decorator (ref):

@Component({
 // --- removed for brevity
  animations: [
    trigger('contentExpansion', [
      state('expanded', style({height: '*', opacity: 1, visibility: 'visible'})),
      state('collapsed', style({height: '0px', opacity: 0, visibility: 'hidden'})),
      transition('expanded <=> collapsed',
        animate('200ms cubic-bezier(.37,1.04,.68,.98)')),
    ])
  ]
})
export class AccordionComponent {}

and then in the template:

<div class="accordion__content" [@contentExpansion]="expanded.has(i) ? 'expanded':'collapsed'">
      <ng-container *ngTemplateOutlet="item?.content?.templateRef"></ng-container>
</div>

We add the animation trigger to the div and pass the state based on the expanded condition. This gives us a smooth animation when toggling the panel.

All the styles that are required for the accordion are in the accordion.component.css file. TailwindCSS is used only for styling the main application.

Code and Demo

Demo: https://ssscp.csb.app

Code: https://codesandbox.io/s/ng-accordion-ssscp

Code with Pipe: https://codesandbox.io/s/ng-accordion-optimized-49bxr

Connect with me

• Twitter
• Github
• Linkedin
• Cardify - Dynamic SVG Images for Github Readmes

Do add your thoughts in the comments section. Stay Safe ❤️

Text Highlighting

Here is what we are going to build in this post. A very simple and straightforward highlight directive in Angular. We see something similar in chrome dev tools.

The idea is pretty simple. We just have to match the searched term and somehow wrap the matched text in a span or mark ( ref ) tag so that we can style them later according to our needs.

How to highlight matched text?

We are going to use Regex to find matches in our paragraph. Regex makes it very simple to do operations like this on strings. The directive should be ideally added only to elements with text in it. This is what we are building:

So let's plan out our directive. The main input to the directive is the term that needs to be highlighted. So yeah, we will use @Input() to pass the term to our directive. I think that is pretty much what we need inside the directive

So now we need to get hold of the actual paragraph to search in. So there is an easy way to get the text from an HTMLElement. We can use the textContent( ref ) which should give us the text to search in.

Building the Highlight directive

As always, I would recommend you create a new module only for the directive. And If you really properly manage your codebase, you can consider creating it as a library within the project as well.

To keep things simple, we put our code in a lib folder:

lib/
├── highlight/
│   ├── highlight.module.ts
│   ├── highlight.directive.ts

Highlight Module

This module would be simple declaring our directive and exporting it. Nothing much is needed here.

import { CommonModule } from "@angular/common";
import { NgModule } from "@angular/core";
import { HighlightDirective } from "./highligh.directive";

@NgModule({
  declarations: [HighlightDirective],
  imports: [CommonModule],
  exports: [HighlightDirective]
})
export class HighlightModule {}

Highlight Directive

Now that our setup is complete, we can start creating our directive where all our magic is going to happen.

import {
  Directive,
  ElementRef,
  HostBinding,
  Input,
  OnChanges,
  SecurityContext,
  SimpleChanges
} from "@angular/core";
import { DomSanitizer, SafeHtml } from "@angular/platform-browser";

@Directive({
  selector: "[highlight]"
})
export class HighlightDirective implements OnChanges {
  @Input("highlight") searchTerm: string;
  @Input() caseSensitive = false;
  @Input() customClasses = "";

  @HostBinding("innerHtml")
  content: string;
  constructor(private el: ElementRef, private sanitizer: DomSanitizer) {}

  ngOnChanges(changes: SimpleChanges) {
    if (this.el?.nativeElement) {
      if ("searchTerm" in changes || "caseSensitive" in changes) {
        const text = (this.el.nativeElement as HTMLElement).textContent;
        if (this.searchTerm === "") {
          this.content = text;
        } else {
          const regex = new RegExp(
            this.searchTerm,
            this.caseSensitive ? "g" : "gi"
          );
          const newText = text.replace(regex, (match: string) => {
            return `<mark class="highlight ${this.customClasses}">${match}</mark>`;
          });
          const sanitzed = this.sanitizer.sanitize(
            SecurityContext.HTML,
            newText
          );
          this.content = sanitzed;
        }
      }
    }
  }
}

Let's do a code breakdown.

The first thing that we need is the Inputs in our directive. We only actually need the search term, but I have added some extra functionalities to our directive. We can provide customClasses for the highlighted text, and another flag 'caseSensitive` which will decide whether we have to match the case.

@Input("highlight") searchTerm: string;
@Input() caseSensitive = false;
@Input() customClasses = "";

Next up we add a HostBinding ( ref ) which can be used to add value to a property on the host element.

@HostBinding("innerHtml")
 content: string;

We bind to the innerHtml ( ref ) property of the host element. We can also do it in this way:

this.el.nativeElement.innerHtml = 'some text';

To get access to the host element, we inject ElementRef in the constructor, and also since we are going to be playing around with direct HTML manipulation, I have also injected DomSanitizer ( ref ) to sanitize the HTML before we inject it into the element.

So now we move on to the actual logic which we can write in the ngOnChanges ( ref ) lifecycle hook. So when our search term changes, we can update the highlights. The interesting part is:

const regex = new RegExp(this.searchTerm,this.caseSensitive ? "g" : "gi");
const newText = text.replace(regex, (match: string) => {
     return `<mark class="highlight ${this.customClasses}">${match}</mark>`;
});
const sanitzed = this.sanitizer.sanitize(
    SecurityContext.HTML,
    newText
);
this.content = sanitzed;

First, we set up the regex to help us find the matches. based on the caseSensitive condition we just add different Regex Flags:

• g - search for all matches.
• gi -search for all matches while ignoring case.

We just wrap the matches with mark tag using the replace ( ref ) method on the string.

const newText = text.replace(regex, (match: string) => {
     return `<mark class="highlight ${this.customClasses}">${match}</mark>`;
});

After that the newText, which is a HTML string needs to be sanitized before we can bind it to the innerHTML. We use the sanitize ( ref ) method on the DomSanitizer class:

const sanitzed = this.sanitizer.sanitize(
    SecurityContext.HTML,
    newText
);

Now we just assign the sanitized value to our content property which gets added to the innerHTML via HostBinding.

Usage

This is how we can use it in our component. Make sure to import our HighlightModule to make our directive available for use in the component.

<p [highlight]="searchTerm" [caseSensitive]="true" customClasses="my-highlight-class">
      Lorem Ipsum has been the industry's standard dummy text ever since the
      1500s, when an unknown printer took a galley of type and scrambled it to
      make a type specimen book.
</p>

That's all! We've successfully created a very simple text highlighter in Angular using directives. As always, please don't directly reuse the code above, try to optimize it and you can always add or remove features to it.

Demo and Code

CodeSandbox: https://codesandbox.io/s/ng-highlight-11hii

Connect with me

• Twitter
• Github
• Linkedin
• Cartella - building at the moment

Do add your thoughts in the comments section. Stay Safe ❤️