Forem: Tanmoy Basak Anjan

Auto scale and load balance dockerized app on AWS - Part 2/3

Tanmoy Basak Anjan — Tue, 13 May 2025 17:44:35 +0000

In Part 1, we dockerized a nodejs application and hosted it in AWS ECR. We also deployed it in an AWS EC2 instance. Additionally, we used AWS parameter store to host environment variables of the nodejs application.

In this part 2, we will use EC2 auto scaling to automatically scale our application which automatically spins up EC2 instances of our app. Later we will use load balancer to handle incoming requests and point to our app.

This is part 2, Autoscale and Load Balance a dockerized app on AWS

Lets pull up our sleeves and start 🚀

Create a base image (AMI) for our ec2 instances.

In this section we will create a base image or AWS Machine image (AMI). This AMI will be later used automatically spin up ec2 instances for our application.

Prerequisites:

You should have a security group with SSH, HTTP and HTTPS access (Although these access will not be required later)
Create a ec2 role with SSM and ECR access. (Refer to Part 1). This role is called ec2-my-app-role (for example)

First, Go to AWS ec2 panel, And hit "Launch instance". We will use the instance to create an AMI image.

Go through with the following instructions to create the instance:

name: my-app-ec2-base-instance (or any name you like)
Machine image: Ubuntu (choose the latest version)
Instance type: t3a.micro (or any instance you prefer)
Key pair: Make sure to attach a key pair (create a new key if needed)
Security group: Select existing or create a security group. Make sure allow SSH, HTTP and HTTPS traffic is ticked.
Add storage: 12GB is good enough
Open Advanced details, under "IAM instance profile", select the role we created in previous section ec2-my-app-role

That's it, not hit "Launch instance"

Now go to the ec2 panel and you should see the instance loading up.

When instance is in running state, click on it and then on next page. Click on "Connect". We will connect to our EC2 instance using SSH to configure and run it.

You should see a terminal to configure your EC2 now.

Configuring the EC2

The following steps are very similar to what we did before in part 1, except we will also add code deploy agent.
Go through the following instructions to configure the EC2. This will install necessary dependencies, nginx, install docker, aws cli and aws code deploy agent.

Install necessary dependencies

First install some necessary updates and dependencies for the next steps.

# Update package list and upgrade all packages
sudo apt-get update -y
sudo apt-get upgrade -y

# Necessary packages
sudo apt-get install -y apt-transport-https ca-certificates curl software-properties-common

We will also install nginx and git in the instance

sudo apt-get install -y nginx
sudo systemctl start nginx
sudo systemctl enable nginx

sudo apt-get install -y git

We install docker in the EC2 instance

We also install docker compose and configure user permissions for docker

curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo apt-key add -
sudo add-apt-repository "deb [arch=amd64] https://download.docker.com/linux/ubuntu $(lsb_release -cs) stable" -y

sudo apt-get update -y
sudo apt-get install -y docker-ce docker-ce-cli containerd.io -y

# enable, start docker
sudo systemctl start docker
sudo systemctl enable docker

sudo docker --version

# Docker user group
sudo usermod -aG docker $USER
newgrp docker

# Docker Compose
sudo curl -L "https://github.com/docker/compose/releases/download/v2.22.0/docker-compose-$(uname -s)-$(uname -m)" -o /usr/local/bin/docker-compose
sudo chmod +x /usr/local/bin/docker-compose

# optional - clean all docker unused images, containers
docker system prune -a --force

Next, we will install AWS CLI into the instance. We will need the aws cli to pull docker image from ECR and to configure env variables in next part.

sudo apt-get update -y
sudo apt-get install -y unzip curl

curl "https://awscli.amazonaws.com/awscli-exe-linux-x86_64.zip" -o "awscliv2.zip"
unzip awscliv2.zip
sudo ./aws/install
aws --version

Install Aws code deploy agent. The code deploy agent will be needed in the next part (part 3) for continuous deployment. You may skip if you do not need continuous deployment pipeline.

sudo apt-get update -y
sudo apt-get install -y ruby-full
wget https://aws-codedeploy-us-east-1.s3.amazonaws.com/latest/install
chmod +x ./install
sudo ./install auto

# check
sudo service codedeploy-agent status

Now that all the base requirements are met for the image, we will create an AMI using the instance.
Close the SSH connection tab and go to the EC2 panel. Select the EC2 instance which was just configured.
From "actions" -> "image and templates" -> "Create image", click here.
Provide a name and this will create an image from the instance, which can be used for any application using docker.

It will take some time for the AMI to be ready.

Create an EC2 launch template

Now that our ec2 image is ready, we will now create an ec2 launch template. A launch template is a set of configuration that can be used to launch an ec2 instance.

Go to "EC2 panel" and select "Launch template" from side panel.

Now click on "Create launch template"
We will now go through a series of instructions to create the launch template.

Provide a name for the launch template, for example my-app-launch-template
Make sure to tick the "Provide guidance to help me set up a template that I can use with EC2 Auto Scaling" under "Auto scaling guidance". As we will use the launch template with auto scaling group later.
Under "Application and OS images", click on "My AMIs", and select the AMI you created in previous section, i.e. docker-app-base-ami
Under instance type, select t3a.micro (or any other instance)
Select an existing key pair
Under network settings, select a security group with SSH (You may add HTTP and HTTPS access if you would like to test the ec2 access later).
Add minimum 12GB of storage
Under "Advanced details", under "IAM instance profile", select ec2-my-app-role (with ECR and SSM access)
User data. This is one of the most important section of the launch template.

The "User data" is a bash script which is run after the ec2 instance is up and running for the FIRST time. In the section you will add commands to pull your ECR image, setup environment and run the application.

Here are instructions for the User data.

First, get these variables ready:

APP_NAME: This is the app name, which was used in docker repo, i. e. "my-app"
PORT: The port which is used by your application, i.e 8000
AWS_ACCOUNT_ID: The account ID needed for docker repo
AWS_REGION: The account region needed for docker repo
IMAGE_TAG: THe docker image tag, i.e latest

Note: Make sure to use quotation ("") in the variable values

Explanation of the user data:

We login to ECR
We pull the application image
We setup .env file from SSM
We run the application using docker
We add nginx configuration and run it.

#!/bin/bash

# ---- DOCKER PULL and RUN
# VARS
APP_NAME="my-app"
PORT="8000"

AWS_ACCOUNT_ID="<aws_account_id>"
AWS_REGION="<aws_region>"
IMAGE_TAG="latest"

# Go to HOME
cd /home/ubuntu

aws ecr get-login-password --region $AWS_REGION | docker login --username AWS --password-stdin $AWS_ACCOUNT_ID.dkr.ecr.$AWS_REGION.amazonaws.com
docker pull $AWS_ACCOUNT_ID.dkr.ecr.$AWS_REGION.amazonaws.com/$APP_NAME:$IMAGE_TAG

# Load .env from ssm
aws ssm get-parameters-by-path \
    --path "/${APP_NAME}" --recursive --with-decrypt \
    | jq -r '.Parameters[] | (.Name | split("/")[-1]) + "=" + (.Value)' \
    | tee .env

docker run --env-file .env -p 8000:8000 -d $AWS_ACCOUNT_ID.dkr.ecr.$AWS_REGION.amazonaws.com/my-app:latest

# nginx setup
echo "server {
listen 80;
server_name _;
client_max_body_size 20M;

location / {
proxy_pass http://localhost:${PORT};
proxy_http_version 1.1;
proxy_set_header Upgrade \$http_upgrade;
proxy_set_header Connection "upgrade";
proxy_set_header Host \$host;
proxy_cache_bypass \$http_upgrade;
}
}" | sudo tee /etc/nginx/sites-available/default > /dev/null

sudo nginx -t
sudo service nginx restart

Now all the launch template configuration is ready. Hit "Create launch template".

Note: To test the launch template from ec2 Launch templates panel, Select the Launch template my-app-launch-template, from "Actions" dropdown, click "Launch instance from template". With the configuration, click "Launch template". You will have an instance running your application.

Create Load balancer with auto scaling

In this section, we will create a load balancer with auto scaling group.
The load balancer with take requests and route them to proper instances.
We will use target groups to register and manage instances.
Finally, we will use an auto scaling group to control how many instances of the application we will use.

First, we will create a security group for our load balancer.

From the "Ec2 panel", go to "security groups" and click on "Create security group"

Follow these instructions

Use a name like "my-app-lb-sg"
Add a description like "My app load balancer"
Under inbound rules, use "HTTP", source "Custom" with "0.0.0.0/0" (Allow from anywhere)
Under outbound rules, make sure "All traffic" from anywhere is added.

Create the security group.

Create target group

Now we will create a target group that will be attached to load balancer later.
In EC2 panel, go to "Target groups" under "Load balancing", click on "Click target group"

Follow these instructions

Under target type, select "Instances"
Add a target group name "my-app-tg"
Make sure Protocol "HTTP" and port "80" are selected
Keep IP address, VPC and protocol, and Health checks as is default
click "next"
In next page directly click "Create target group"

Create load balancer

Now we will create a load balancer.
From "EC2 panel", go to "Load balancers", click "Create load balancer"

Follow these instructions:

Under "Application load balancer", click "create"
Add a load balancer name "my-app-lb"
Keep scheme "internet facing"
Under network mapping, keep "default vpc", under availability zones, make sure you have at least 2 zone chosen
Under "security group", choose the security group we created earlier "my-app-lb-sg"
Under listeners and routing, One listener should be added. Protocol "HTTP", port "80", default action should be forwarded to the target group we created "my-app-tg"
Now click "Create load balancer"

Now our load balancer should be created. You should see a "DNS name" under load balancer details.
It should have a format like this -

my-app-lb-156356388.<aws_region>.elb.amazonaws.com

This is the URL our application will get deployed in ultimately. If you visit this URL now, you will see 503 because there are no instances of our application running under the target group. This is where we need an "Auto scaling group"

Create Auto scaling group

Under "EC2 panel", under "Auto scaling", go to "Auto scaling groups".
Click on "Create auto scaling group"

Step 1: Add a name "my-app-asg"
Select the launch template we created earlier "my-app-launch-template"
Step 2: Instance requirements: keep as is
Under network, select at lease, keep VPC, and select at least one availability zone
Step 3: Select "Attach to existing load balancer"
Under target groups, select our target group "my-app-tg"
Keep rest of the settings as is
Step 4: Select value "1" for desired, minimum and maximum group size, this will make sure at least instance of our app is running
keep rest of settings as is
Step 5 notifications, step 6 tags: keep as is
Step 6: Review everything and click "Create auto scaling group"

Now if you wait some time, in your EC2 instances list, you should see a new instances automatically spinning up.
This is an instance of our application.

Note: If you terminate this instance, a new instance will spin up automatically.

Now if you visit the load balancer DNS my-app-lb-156356388.<aws_region>.elb.amazonaws.com,
You should see "Hello from my-app!"

Congratulations! 🎉🎉, our load balanced auto scaled application is running.

About Author:
Tanmoy Basak Anjan is CEO and Co-Founder of engaze.ai, a sales tech platform that is changing the way restaurants operate. Visit engaze.ai to know more.

Dockerize & Deploy your nodejs app (with env) on AWS EC2 - Part 1/3

Tanmoy Basak Anjan — Fri, 14 Mar 2025 10:38:47 +0000

Your nodejs server app is ready. Its time to get it into the cloud. But the cloud can be overwhelming with many options and many tricks. We will breakdown a straight forward approach to reliably host your application on AWS and also manage its environment variables. Apart from hosting your application on day 1, you will also automatically scale your application and load balance incoming requests. Finally you will need a way to easily ship updates and push new code on the fly.

We will breakdown the full journey into 3 parts. Not because the journey is long, but because we want to understand the journey.

Part 1: Dockerize and deploy a sample nodejs application using AWS ECR (Elastic container registry) and AWS EC2 (Elastic compute cloud) and manage environment using AWS Parameter store.

Part 2: Autoscale and Load balance the dockerized nodejs application using AWS Auto scaling group, AWS Application load balancer and EC2.

Part 3: Continuous deployment of your dockerized nodejs application using AWS Code Pipeline and AWS Code Build and Github

This is Part 1, Dockerize and deploy a nodejs app on AWS

Lets pull up our sleeves and start 🚀

A sample nodejs app to work with

We will first create a sample app to work with and then dockerize it. Throughout the tutorial we will call our app my-app. So create a directory called my-app and setup our application.

MAKE SURE you have nodejs and npm available

mkdir my-app 
cd my-app
npm init -y

You should now have a bare bone nodejs server. Lets, install express and dotenv for a simple app.

npm i express dotenv

create an index.js file and add this code. It creates a server using express. Note that server uses Port 8000

const express = require("express");
require("dotenv").config();

const PORT = 8000;
const APP_NAME = process.env.APP_NAME;

const app = express();

app.get("/", (_, res) => {
  res.send(`Hello from ${APP_NAME}!`);
});

app.listen(PORT, () => {
  console.log(`Hello from ${APP_NAME}!`);
});

The code reads APP_NAME from a .env file. This is mainly to demonstrate how environments can be managed in aws. create a .env file and add the following env variables, Use any values you would like

APP_NAME=myapp

In package.json, add the start command under scripts

"scripts": {
  "start": "node index.js"
}

Now run npm install and then npm start to run the server. You should see Hello from myapp! when the server starts.

You can find the Sample application in Github

Dockerize the application

We will dockerize our nodejs application in this section. First make sure Docker is installed in your system. Check the Official Documentation to install.

Note: Make sure to install buildx and support multi architecture builds.

The first step to dockerize your app is to write a Dockerfile. For our nodejs app, create a file named Dockerfile and add the following code.

# Use the official Node.js 20.13.1 image
FROM node:20.13.1-alpine

# Set the working directory
WORKDIR /app

# Copy the project
COPY . ./

# Install dependencies
RUN npm install

# Expose the port (replace with your application's port)
EXPOSE 8000

# Command to start the application
CMD ["npm", "start"]

Also create a .dockerignore file to ignore specific files from getting copied to docker image.

node_modules
.env

Note: we will not pass the .env file when building docker image. In AWS, env vars will be made available in a more secure and scalable way using AWS parameter store.

Now run the following code to build an image of your application. You can use any name other than my-app

docker build -t my-app:latest .

Now your docker image is ready. To check docker images you can run docker images. You should see my-app in the list.

To run the docker image in a container locally, use the following command. Make sure you are in the Folder with .env file. Use the appropriate port mapping

docker run --env-file .env -p 8000:8000 my-app:latest

This should run your dockerized application now. Visit https://localhost:8000 to check.

Deploy Application on EC2

Now we start working on AWS, Make sure to sign in to the AWS console on your preferred zone. We will also need to sign in to AWS CLI on our local machine. You can follow along the AWS CLI **installation instructions HERE
Next, **Login to be authenticated with AWS CLI following instructions HERE

Create an ECR repository for our app

Now that our docker image is ready and we have tested that it works, we will now host the image in AWS ECR. AWS ECR or Elastic container service is a service where you can host docker images.

Login to AWS console from the Browser and search for ECR. From the ECR console, click on "Create Repository". Fill in the name as "my-app", or your desired name.

On the ECR console, you should see the "Repository URI" with the following structure. We will need this "Repository URI" later.

<aws_account_id>.dkr.ecr.<aws_region>.amazonaws.com/my-app
(or, the repository name you use)

*Note: * The variables aws_account_id, aws_region will be used repeatedly in this tutorials.

Push image to ECR

To push our image to ECR we will use the AWS CLI. First login to ECR using CLI on your local machine. Make sure to replace <aws_account_id>, <aws_region>

aws ecr get-login-password --region <aws_region> | docker login --username AWS --password-stdin <aws_account_id>.dkr.ecr.<aws_region>.amazonaws.com

You should see Login Succeeded in the console.
Now we will push the my-app docker image to ECR.

docker buildx build --platform linux/amd64,linux/arm64 -t <aws_account_id>.<aws_region>.amazonaws.com/my-app:latest --push .

This will push our image to ECR. If you visit ECR and click on my-app repository. You should see the latest tagged image.

Notes: We are building the image for multiple platforms as our production instance can have any platform. You may skip multiple architecture build if you know the architecture of your production servers.
Make sure buildx is installed with docker locally.

Running application in EC2

There are a number of steps to run our application properly on an EC2. The steps are

Configure env using parameter store
Configure ec2 role so our ec2 has proper permissions
Run application in ec2

configuring aws parameter store for env variables

To securely use environment variables with AWS services, we will use AWS parameter store (a feature of AWS Systems Manager or SSM).
parameter store is a service where you can store secrets or variables and then read from different services.

Search for "Parameter store" in AWS and go into it. Click "Create parameter".

Use /my-app/APP_NAME as the name and use my-app as value. You can even use encrypted values if your secrets are sensitive.

Now click "Create parameter" and we are done

Create AWS EC2 role for configuring permissions

In this section we will create an AWS EC2 role which will be used with the AWS instance.

Search for "IAM" in the AWS panel and go in. Select "Roles" from the left panel under "Access management". Click on "Create role".

Step 1. Under "Select trusted entity", select "AWS service", under "Use case", select "EC2". Click next.

Step 2. Next we "Add permissions". Add the following permission sets by searching

AmazonSSMReadOnlyAccess
AmazonEC2ContainerRegistryPullOnly

Now, click next

step 3. Provide name and check access and create the role.

Provide a name for the role like ec2-my-app-role, check permissions and create the role.

Run application on EC2

Now it is time to create our EC2 and run our application. Go to "EC2" panel in AWS and click Launch instance

Choose the follow config when creating the ec2.

name: my-app-ec2 (or any name you like)
Machine image: Ubuntu (choose the latest version)
Instance type: t3a.micro (or any instance you prefer)
Key pair: Make sure to attach a key pair (create a new key if needed)
Security group: Select existing or create a security group. Make sure to allow SSH, HTTP and HTTPS traffic.
Add storage: 12GB is good enough
Open Advanced details, from "IAM instance profile", select the role we created in previous section ec2-my-app-role

That's it, now hit "Launch instance"

Now, we want to connect to the EC2 and configure and run our application.
Go to the EC2 panel and you should see the instance loading up. When instance is in running state, click on it and then on next page,
Click on "Connect". We will connect to our EC2 instance using SSH to configure and run it.

You should see a terminal to configure your EC2 now.

Configuring the EC2

Install necessary dependencies

First install some necessary updates and dependencies for the next steps.

# Update package list and upgrade all packages
sudo apt-get update -y
sudo apt-get upgrade -y

# Necessary packages
sudo apt-get install -y apt-transport-https ca-certificates curl software-properties-common

We will also install nginx and git in the instance

sudo apt-get install -y nginx
sudo systemctl start nginx
sudo systemctl enable nginx

sudo apt-get install -y git

We install docker in the EC2 instance

curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo apt-key add -
sudo add-apt-repository "deb [arch=amd64] https://download.docker.com/linux/ubuntu $(lsb_release -cs) stable" -y

sudo apt-get update -y
sudo apt-get install -y docker-ce docker-ce-cli containerd.io -y

# enable, start docker
sudo systemctl start docker
sudo systemctl enable docker

sudo docker --version

# Docker user group
sudo usermod -aG docker $USER
newgrp docker

# Docker Compose
sudo curl -L "https://github.com/docker/compose/releases/download/v2.22.0/docker-compose-$(uname -s)-$(uname -m)" -o /usr/local/bin/docker-compose
sudo chmod +x /usr/local/bin/docker-compose

# optional - clean all docker unused images, containers
docker system prune -a --force

Next, we will install AWS CLI into the instance. We will need the AWS CLI to pull docker image from ECR and to configure env variables in next part.

sudo apt-get update -y
sudo apt-get install -y unzip curl

curl "https://awscli.amazonaws.com/awscli-exe-linux-x86_64.zip" -o "awscliv2.zip"
unzip awscliv2.zip
sudo ./aws/install
aws --version

Running the application

Our first task is to pull the ECR image into our EC2 instance.

Make sure to replace <aws_region>, <aws_account_id> and use your docker image name and tags (i.e my-app, latest).

aws ecr get-login-password --region <aws_region> | docker login --username AWS --password-stdin <aws_account_id>.dkr.ecr.<aws_region>.amazonaws.com
docker pull <aws_account_id>.dkr.ecr.<aws_region>.amazonaws.com/my-app:latest

Now if you run docker images, you should see .../my-app image with latest tag.

Next we read env vars from AWS SSM parameter store and create a .env file. What it does is it recursively reads all parameter store parameters that start with /my-app, this is why we used a suffix in the name.

aws ssm get-parameters-by-path \
    --path "/my-app" --recursive --with-decrypt \
    | jq -r '.Parameters[] | (.Name | split("/")[-1]) + "=" + (.Value)' \
    | tee .env

if your run cat .env, you should see contents of .env file just created.

Finally we are ready to run our application. Make sure to replace the variables.

docker run --env-file .env -p 8000:8000 -d <aws_account_id>.dkr.ecr.<aws_region>.amazonaws.com/my-app:latest

You can run curl http://localhost:8000 to check application is running.

Accessing our application

Configure nginx to serve our application in the default Http port accessible from the internet.
The configuration tells nginx to forward requests to port 8000.

echo "server {
listen 80;
server_name _;
client_max_body_size 20M;

location / {
proxy_pass http://localhost:8000;
proxy_http_version 1.1;
proxy_set_header Upgrade \$http_upgrade;
proxy_set_header Connection "upgrade";
proxy_set_header Host \$host;
proxy_cache_bypass \$http_upgrade;
}
}" | sudo tee /etc/nginx/sites-available/default > /dev/null
sudo nginx -t
sudo service nginx restart

Now run curl http://localhost and you see your application output.

To access our application over internet, Go to AWS EC2 console and find you EC2 instance.
You should find a "Public ipv4 address" associated with your instance.
Go to http://{PUBLIC_IP_ADDRESS} and see your application output.

Note: Make sure the security group of the EC2 instance allows HTTP traffic from anywhere in inbound rules.

About Author:
Tanmoy Basak Anjan is CEO and Co-Founder of engaze.ai, a sales tech platform that is changing the way restaurants operate. Visit engaze.ai to know more.

Managing countries and currencies with JS

Tanmoy Basak Anjan — Fri, 27 Dec 2024 18:26:13 +0000

Managing list of countries and currencies along with formatting different currency formats for all the different countries can present some challenges and work in our projects. Firstly, we do not want to carry around list of 200 countries and their currencies, dial codes, flag emojies in our codebase, specially on the front end. Secondly, every country follows different currency symbols, different formatting, like comma placements and different decimal precisions needs to be managed.

This is why the npm package country-currency-utils was written. Its written in typescript, suitable in any project that uses javascript, whether on the server or frontend.

Countries

We have a list of countries hosted through CDN which can be accessed through the COUNTRIES_DETAILS_URL variable from the package. The response is a key value object where key is the 2-letter ISO standard country code. The value object contains Dial code, Currency code (ISO standard) and flag emojis. The following functions can be used to list out countries from the package.

type TCountryDetails = {
  name: string; // Country name
  dialCode: string; // Country dial code
  currencyCode: string; // Country currency code
  flagEmoji: string; // Country flag emoji
};

type TCountryData = TCountryDetails & {
  countryCode: string; // ISO 3166 country code
};

getAllCountryDetails(): Promise<Record<string, TCountryDetails>>
getAllCountryData(): Promise<TCountryData[]>
getCountryData(countryCode: string): Promise<TCountryData | undefined>
getCountryData(countryCode: string): Promise<TCountryData | undefined>

// examples

const allCountriesData = await getAllCountryData()
const countryData = await getCountryData("US")
const countriesData = await getCountriesData(["US", "BD"])

Currencies

We also have a list of currencies hosted through CDN accessible with the CURRENCIES_DETAILS_URL variable. It contains a key value object where key is ISO standard currency code and the value is an object with different currency details like currency symbols (native and standard), digit grouping (million-billion or Lakh-Crore), and decimal precision followed with the currency. Here are functions to use the data.

type TCurrencyDetails = {
  name: string; // Currency name
  demonym: string; // Currency demonym
  majorSingle: string; // Major unit name in singular form (e.g. Dollar)
  majorPlural: string; // Major unit name in plural form (e.g. Dollars)
  symbol: string; // Currency symbol (e.g. $, CA$)
  symbolNative: string; // Currency symbol in native language (e.g. $)
  symbolPreferred: string; // preferred currency symbol, used for display
  minorSingle: string; // Minor unit name in singular form (e.g. Cent)
  minorPlural: string; // Minor unit name in plural form (e.g. Cents)
  decimals: number; // Number of decimal places, used for standard display
  decimalsCompact: number; // Number of decimal places, used for compact display
  digitGrouping: 2 | 3; // Digit grouping for formatting (e.g. 2 for 1,00,000, 3 for 100,000)
};

type TCurrencyData = TCurrencyDetails & {
  currencyCode: string; // ISO 4217 currency codes
};

getAllCurrencyDetails(): Promise<Record<string, TCurrencyDetails>>
getAllCurrencyData(): Promise<TCurrencyData[]>
getCurrencyData(currencyCode: string): Promise<TCurrencyData | undefined>
getCurrenciesData(currencyCodes: string[]): Promise<(TCurrencyData | undefined)[]>

// Examples

const allCurrenciesData = await getAllCurrencyData()
const currencyData = await getCurrencyData("USD")
const currenciesData = await getCurrenciesData(["USD", "BDT"])

Amount Formatting Utilities

When developing a project that handles multiple currencies can be a challenge for a number of reasons -

Handle decimal place accuracies of the currencies
Show proper symbols (native and standard symbols)
Format the currencies with comma separation

The currency list of data contains all of the important data needed for proper display of monetary amounts. There are also utility functions that help with handling monetary amounts.

Rounding amounts

The default to round monetary amount is to ceil the amount. However you can also round the amount in the middle.

const roundedAmount = getRoundedAmount(123.4517, 2); // 123.46
const roundedAmount = getRoundedAmount(123.4517, 2, true); // 123.45

You may also want to round amounts depending on the currency. Here, we have another function to round on the currency details.

const USDCurrencyData = await getCurrencyData("USD");
const BDTCurrencyData = await getCurrencyData("BDT");

const roundedAmount = getRoundedAmountOnCurrency(123.4567, USDCurrencyData); // 123.46
const roundedAmount = getRoundedAmountOnCurrency(123.45, BDTCurrencyData); // 124
const roundedAmount = getRoundedAmountOnCurrency(123.45, BDTCurrencyData, {
  isDecimalsStandard: true,
}); // 123.45

Note: You will notice that we use a promise to read the CurrencyDetails first. It is important to handle this way as we do not want to carry a list of all currency details in our codebase. So we fetch the data and use it. But you can also decide to keep a copy and use the getRoundedAmountOnCurrency function. The same idea applies for the next functions.

Formatting amounts

Formatting amounts returns strings for display purposes. Formatting amounts involves two things

Give the amount fixed decimal places
Return a comma separated amount

Use the following function to format amounts on currency.

// reference
type TCurrencyFormatOptions = TCurrencyRoundOptions & {
  avoidRound?: boolean; // avoids rounding amount
  avoidFixedDecimals?: boolean; // default behavior is to have fixed decimals
};

getFormattedAmountOnCurrency(amount: number, currencyData?: TCurrencyData, options?: TCurrencyFormatOptions): string

// example
const USDCurrencyData = await getCurrencyData("USD");
const BDTCurrencyData = await getCurrencyData("BDT");

const formattedAmount = getFormattedAmountOnCurrency(123456.7, USDCurrencyData); // "123,456.70"
const formattedAmount = getFormattedAmountOnCurrency(
  123456.7,
  USDCurrencyData,
  {
    avoidFixedDecimals: true,
  }
); // "123,456.7"
const formattedAmount = getFormattedAmountOnCurrency(123456.7, BDTCurrencyData); // "1,23,457"
const formattedAmount = getFormattedAmountOnCurrency(
  123456.7,
  BDTCurrencyData,
  {
    avoidRound: true,
  }
); // "1,23,456.7"

Displaying amounts

Finally displaying amounts involves adding currency symbols to the amount formatted. Use the following functions

The first function getDisplayAmountOnCurrency takes currency details -

// reference
type TCurrencyDisplayOptions = TCurrencyFormatOptions & {
  avoidFormat?: boolean; // Default: format amount
  isSymbolStandard?: boolean; // Default: preferredSymbol, isSymbolStandard: standard symbol
  isSymbolNative?: boolean; // Default: preferredSymbol, isSymbolNative: symbolNative
  separator?: string; // Default: space between symbol and amount, can be changed
};

getDisplayAmountOnCurrency(amount: number, currencyData?: TCurrencyData, options?: TCurrencyFormatOptions): string

// example
const USDCurrencyData = await getCurrencyData("USD");
const BDTCurrencyData = await getCurrencyData("BDT");

const displayAmount = getDisplayAmountOnCurrency(123.4567, USDCurrencyData); // "$ 123.46"
const displayAmount = getDisplayAmountOnCurrency(123456.7, USDCurrencyData); // "$ 123,456.70"
const displayAmount = getDisplayAmountOnCurrency(123.4567, BDTCurrencyData, {
  isSymbolStandard: true,
}); // "৳ 124"

The second function, getDisplayAmountOnCurrencyCode only takes a currencySymbol, but its a promise.

const displayAmount = await getDisplayAmountOnCurrencyCode(123.4567, "USD"); // "$ 123.46"
const displayAmount = await getDisplayAmountOnCurrencyCode(123456.7, "USD"); // "$ 123,456.70"
const displayAmount = await getDisplayAmountOnCurrencyCode(123456.7, "USD", {
  avoidFormat: true,
}); // "$ 123456.7"
const displayAmount = await getDisplayAmountOnCurrencyCode(123456.7, "USD", {
  separator: "",
}); // "$123,456.70"
const displayAmount = await getDisplayAmountOnCurrencyCode(123.4567, "BDT"); // "Tk 124"
const displayAmount = await getDisplayAmountOnCurrencyCode(123.4567, "BDT", {
  isSymbolStandard: true,
}); // "৳ 124"

Conclusion

Many applications deal with countries and currencies and this package was developed to solve a lot of the problems we faced during our work at Headless Technologies Limited and when developing the SAAS sales tech platform engaze.ai used across 30 plus countries.

If you find the package useful, consider starring the package Github Repo.

Feel free to leave a question on the post.