What this blog covers: Building a VPC from scratch, understanding every component, calculating CIDR ranges, and connecting everything together securely.

What is a VPC?

A Virtual Private Cloud (VPC) is your own isolated network inside AWS. Everything you deploy — EC2 instances, RDS databases, Lambda functions — lives inside a VPC.

Key facts:

• One VPC per region (but you can have multiple VPCs)

• You define its IP address space using CIDR notation

• By default it's completely isolated — no internet access until you configure it

• Free to create (you pay for resources inside it, not the VPC itself)

CIDR Notation — How IP Ranges Work

CIDR stands for Classless Inter-Domain Routing. It's how you define a block of IP addresses.

The Format

10.0.0.0 / 16
─────────
IP Address  Prefix length (how many bits are "fixed")

An IPv4 address is 32 bits total, written as 4 groups of 8 bits (octets):

10   .   0   .   0   .   0
│      │        │       │
8 bits  8 bits  8 bits  8 bits  =  32 bits total

The Prefix Length Controls How Many IPs You Get

The prefix /N means the first N bits are fixed (your network). The remaining (32 - N) bits are free (your hosts).

Number of usable IPs = 2^(32 - N)

Why "usable IPs" is always 2 less than total: AWS reserves 5 IPs per subnet (first 4 + last 1). So a /24 gives 256 - 5 = 251 usable IPs.

Visual: What /16 vs /24 Looks Like

10.0.0.0/16  →  covers  10.0.0.0  to  10.0.255.255
               fixed: [10.0]  free: [0-255].[0-255]

10.0.1.0/24  →  covers  10.0.1.0  to  10.0.1.255
               fixed: [10.0.1]  free: [0-255]

The 5 Reserved IPs AWS Takes (per subnet)

For a subnet 10.0.1.0/24:

So 251 IPs are actually available for your resources.

How to Calculate IPs for Your VPC and Subnets

Step-by-step planning

• Rule #1 — VPC must be bigger than all subnets combined

• Rule #2 — Subnet CIDR must be within the VPC CIDR range

• Rule #3 — Subnets in the same VPC cannot overlap

Example: Planning a production VPC

Goal: 2 public subnets + 2 private subnets across 2 Availability Zones

Why 10.0.1.0 and not 10.0.0.0 for subnets? Leave 10.0.0.0/24 as a spare block. Start subnets at .1, .2, .3, .4 so your numbering is clean and you have room to add subnets later.

The CIDR Calculation Formula

First IP of subnet:  your chosen start address
Last IP of subnet:   first IP + (2^free_bits - 1)

Example: 10.0.3.0/24
  free bits = 32 - 24 = 8
  total IPs = 2^8 = 256
  range: 10.0.3.0 → 10.0.3.255

Quick sizing guide

Private IP ranges you must use (RFC 1918)

AWS VPCs must use private IP ranges — these are NOT routable on the public internet:

10.0.0.0    –  10.255.255.255   →  /8  (16M IPs)
172.16.0.0  –  172.31.255.255   →  /12 (1M IPs)
192.168.0.0 –  192.168.255.255  →  /16 (65K IPs)

Best practice: Use 10.0.0.0/16 for your VPC CIDR. It's the most spacious and clearest for mental mapping.

Step 1 — Create the VPC

What it is

The outer boundary of your private network in AWS. All subnets, gateways, and resources live inside it.

How to create it

AWS Console:

1. Go to VPC → Your VPCs → Create VPC

2. Choose "VPC only" (not VPC and more — we want manual control)

3. Set the IPv4 CIDR block

Configuration:

Name:        my-production-vpc
IPv4 CIDR:   10.0.0.0/16
Tenancy:     Default  (shared hardware — cheaper)

What gets created automatically

• A default route table (main route table)

• A default security group

• A default network ACL

⚠️ Don't use the default VPC for production. It has permissive defaults and a fixed CIDR. Always create a custom VPC.

Step 2 — Create Subnets

What they are

Subnets carve your VPC CIDR into smaller chunks, each tied to a specific Availability Zone. A subnet is "public" only if its route table has a route to an Internet Gateway — not because of its name.

VPC: 10.0.0.0/16
Public Subnet A  (10.0.1.0/24)  [us-east-1a]  ← has route to IGW
Public Subnet B  (10.0.2.0/24)  [us-east-1b]  ← has route to IGW
Private Subnet A (10.0.3.0/24)  [us-east-1a]  ← no route to IGW
Private Subnet B (10.0.4.0/24)  [us-east-1b]  ← no route to IGW

How to create them

For each subnet, go to VPC → Subnets → Create Subnet:

Subnet 1 — Public A
  Name:   public-subnet-a
  VPC:    my-production-vpc
  AZ:     us-east-1a
  CIDR:   10.0.1.0/24

Subnet 2 — Public B
  Name:   public-subnet-b
  VPC:    my-production-vpc
  AZ:     us-east-1b
  CIDR:   10.0.2.0/24

Subnet 3 — Private A
  Name:   private-subnet-a
  VPC:    my-production-vpc
  AZ:     us-east-1a
  CIDR:   10.0.3.0/24

Subnet 4 — Private B
  Name:   private-subnet-b
  VPC:    my-production-vpc
  AZ:     us-east-1b
  CIDR:   10.0.4.0/24

Enable auto-assign public IP (public subnets only)

For each public subnet: Actions → Edit Subnet Settings → Enable auto-assign public IPv4 address

Why two AZs? If one AZ goes down (rare but it happens), your service keeps running from the other AZ. This is high availability.

Step 3 — Internet Gateway (IGW)

What it is

The door between your VPC and the internet. Without it, nothing in your VPC can reach the outside world — even resources in "public" subnets.

Internet
  │
[Internet Gateway]  ← attached to VPC
  │
[VPC]

How it works

• Two-way: allows inbound AND outbound internet traffic

• Stateless at the gateway level (Security Groups handle stateful inspection)

• Horizontally scalable: AWS manages it — no bandwidth limits, no single point of failure

• One per VPC

How to create and attach it

1. VPC → Internet Gateways → Create Internet Gateway

2. Name it my-igw

3. After creation: Actions → Attach to VPC → select my-production-vpc

⚠️ Two-step process! Creating the IGW is not enough. You must explicitly attach it to your VPC. Then you must add a route pointing to it in your public subnet route table.

Step 4 — Route Tables

What they are

A route table is a set of rules that tells traffic "where to go." Every subnet must be associated with exactly one route table.

The two route tables you need

Public Route Table (for public subnets):

Destination      Target
10.0.0.0/16      local      ← talk to any resource in the VPC
0.0.0.0/0        igw-xxxxx  ← everything else → internet

Private Route Table (for private subnets):

Destination      Target
10.0.0.0/16      local      ← talk to any resource in the VPC
0.0.0.0/0        nat-xxxxx  ← everything else → NAT Gateway (outbound only)

How to create them

Create public route table:

1. VPC → Route Tables → Create Route Table

2. Name: public-rt, VPC: my-production-vpc

3. Routes tab → Edit routes → Add route: 0.0.0.0/0 → Target: Internet Gateway → my-igw

4. Subnet Associations tab → Associate public-subnet-a and public-subnet-b

Create private route table:

1. Create Route Table: private-rt, VPC: my-production-vpc

2. Add route: 0.0.0.0/0 → Target: NAT Gateway (do this after creating the NAT GW)

3. Associate private-subnet-a and private-subnet-b

Route table flow diagram

Incoming request from internet:
  0.0.0.0/0 → [IGW] → [Public subnet] → ALB → EC2 in private subnet

EC2 making outbound call:
  EC2 → [Private subnet route table] → 0.0.0.0/0 → [NAT GW] → [IGW] → Internet
  Response comes back through NAT GW → EC2 (NAT handles translation)

Step 5 — NAT Gateway

What it is

NAT = Network Address Translation. The NAT Gateway gives private subnet resources one-way internet access — they can initiate outbound connections, but the internet cannot initiate connections to them.

Private EC2 (10.0.3.10)
    │ wants to reach api.github.com
    
NAT Gateway (in public subnet, has Elastic IP: 54.x.x.x)
    │ translates 10.0.3.10 → 54.x.x.x
   
Internet Gateway
    │
    
api.github.com
    │ response goes back to 54.x.x.x (Elastic IP)
    
NAT Gateway translates back → delivers to 10.0.3.10

⛔ Someone trying to reach 10.0.3.10 FROM the internet? Blocked.

Where it lives

In the public subnet — it needs internet access itself to forward traffic out.

How to create it

1. VPC → NAT Gateways → Create NAT Gateway

2. Subnet: public-subnet-a (must be public!)

3. Connectivity: Public

4. Elastic IP: Allocate Elastic IP (click the button)

5. Create

Then add to your private route table:

0.0.0.0/0  →  nat-xxxxxxxx

Cost warning

NAT Gateway costs ~\(0.045/hour + \)0.045/GB data. For dev environments, consider a NAT Instance (cheaper but requires manual management).

Step 6 — Security Groups

What they are

Virtual firewalls attached to individual resources (EC2, RDS, ALB, etc.). They control what traffic is allowed in (inbound) and out (outbound).

Key properties

Stateful explained

Client → [HTTPS port 443, ALLOWED] → EC2
EC2   → [Response traffic]         → Client  ✅ automatic, no rule needed

Compare with NACL (stateless):
EC2   → [Response on port 52341]   → Client  ❌ must explicitly allow ephemeral ports

The 3-tier Security Group pattern

Internet
    │  (HTTPS 443)
   
[SG-ALB]  →  inbound: 443 from 0.0.0.0/0
              outbound: 8080 to SG-App
    │  (HTTP 8080)
   
[SG-App]  →  inbound: 8080 from SG-ALB
              outbound: 3306 to SG-DB
    │  (MySQL 3306)
   
[SG-DB]   →  inbound: 3306 from SG-App
              outbound: all (default)

How to create Security Groups

SG-ALB (Load Balancer):

Name: sg-alb
VPC:  my-production-vpc

Inbound rules:
  Type: HTTPS  Port: 443   Source: 0.0.0.0/0   (internet traffic)
  Type: HTTP   Port: 80    Source: 0.0.0.0/0   (redirect to HTTPS)

Outbound rules:
  Type: Custom TCP  Port: 8080  Destination: sg-app  (to app servers)

SG-App (EC2 App Servers):

Name: sg-app
VPC:  my-production-vpc

Inbound rules:
  Type: Custom TCP  Port: 8080  Source: sg-alb  ← reference by SG ID!

Outbound rules:
  Type: MySQL/Aurora  Port: 3306  Destination: sg-db
  Type: HTTPS         Port: 443   Destination: 0.0.0.0/0  (for API calls via NAT)

SG-DB (RDS Database):

Name: sg-db
VPC:  my-production-vpc

Inbound rules:
  Type: MySQL/Aurora  Port: 3306  Source: sg-app  ← only app servers can reach it!

Outbound rules:
  (leave default — all outbound allowed)

Why reference SGs by ID instead of IP?

If you used IP:   Source = 10.0.3.15
                  → scale to 10 EC2s = update rule 10 times

If you used SG:   Source = sg-app
                  → any EC2 with sg-app attached = always works
                  → scale to 100 EC2s = no changes needed ✅

Step 7 — Network ACLs (Extra Layer)

What they are

Network ACLs (NACLs) are subnet-level firewalls. They're stateless (must allow return traffic explicitly) and support both allow and deny rules.

SG vs NACL comparison

Private subnet NACL example

Inbound rules:
  Rule 100  ALLOW  TCP  10.0.0.0/16  all ports  ← VPC-internal traffic only
  Rule *    DENY   ALL  0.0.0.0/0               ← block everything else

Outbound rules:
  Rule 100  ALLOW  TCP  10.0.0.0/16  all ports  ← VPC-internal
  Rule 200  ALLOW  TCP  0.0.0.0/0   1024-65535  ← ephemeral ports for responses
  Rule *    DENY   ALL  0.0.0.0/0               ← block everything else

Ephemeral ports (1024–65535): When a server responds to a client, it uses a random high port. Since NACLs are stateless, you must explicitly allow these return ports in your outbound rules.

Full Architecture — How It All Connects

Traffic flow (inbound request):
  Internet → IGW → ALB (public subnet) → EC2 (private subnet) → RDS (private subnet)

Traffic flow (outbound from EC2):
  EC2 → Private route table → NAT GW (public subnet) → IGW → Internet

Request lifecycle step by step

1. User hits https://myapp.com
        │
2. DNS resolves to ALB's public IP
        │
3. Internet → IGW → ALB (SG-ALB allows port 443 from 0.0.0.0/0)
        │
4. ALB → EC2 (SG-App allows port 8080 from SG-ALB)
        │
5. EC2 → RDS (SG-DB allows port 3306 from SG-App)
        │
6. RDS returns data → EC2 → ALB → User

[EC2 calling external API]
7. EC2 → private route table → 0.0.0.0/0 → NAT GW → IGW → api.example.com
8. Response → IGW → NAT GW → EC2  (internet can't initiate step 7 in reverse)

Security Group Cheat Sheet

Common Mistakes

❌ Subnet is "public" because I named it public

✅ A subnet is public ONLY if its route table routes 0.0.0.0/0 to an IGW

❌ I created the IGW but resources still can't reach the internet

✅ Did you: (1) attach IGW to VPC? (2) add the route in the route table?

❌ My private EC2 can't download packages

✅ Check: (1) NAT Gateway exists? (2) private route table has 0.0.0.0/0 → NAT? (3) NAT Gateway is in a PUBLIC subnet?

❌ I set SG inbound source to the app server's IP address

✅ Set source to the SG ID (sg-xxxxxxxx) — it scales automatically

❌ NACL is blocking my traffic even though SG allows it

✅ NACLs are stateless — add outbound rule for ephemeral ports 1024-65535

❌ My subnets overlap (10.0.1.0/24 and 10.0.1.128/24)

✅ AWS will reject this. Plan CIDR ranges before creating subnets.

❌ I used /32 for my VPC CIDR

✅ VPC minimum is /28, maximum is /16. Recommended: /16 or /20.

NAT Gateway MUST live in a public subnet

Here's the core logic: the NAT Gateway's entire job is to forward your private resources' traffic out to the internet. To do that, it needs internet access itself. And to have internet access, it must be in a subnet whose route table points to the Internet Gateway.

That's the definition of a public subnet.

Private EC2 wants to reach github.com
        │
       
Private route table: 0.0.0.0/0 → NAT Gateway
        │
       
NAT Gateway (sitting in PUBLIC subnet, has Elastic IP)
        │
       
Public route table: 0.0.0.0/0 → IGW
        │
       
Internet Gateway → github.com

If you put the NAT Gateway in a private subnet, it would have no route to the internet itself — so it could never forward traffic anywhere. It would be completely useless, like a postal relay office with no road connecting it to the outside world.

What makes the NAT Gateway "safe" even though it's public

People get nervous hearing "NAT Gateway is in the public subnet" — but here's why it's not a security risk:

The NAT Gateway does not have a Security Group. It's not a compute resource you SSH into. It's a managed AWS appliance that only does one thing: translate source IPs. It never accepts unsolicited inbound connections from the internet — it only handles return traffic for connections that your private resources initiated.

The protection of your private EC2 and RDS instances comes from the fact that they have no public IP and no route from the internet reaching them. The NAT Gateway is just a forwarding pipe — it's not the thing being protected.

Internet trying to reach your private EC2:
  Internet → IGW → ... no route to 10.0.3.x exists in public subnet → DROPPED

Your private EC2 calling the internet:
  EC2 → NAT GW → IGW → Internet → response back to NAT GW → EC2  ✅

One more practical tip

You should create one NAT Gateway per Availability Zone, not one total. If you have subnets in us-east-1a and us-east-1b, create a NAT Gateway in each public subnet, then point each private subnet's route table to the NAT Gateway in the same AZ. If you share a single NAT Gateway across AZs and that AZ goes down, all your private instances lose internet access simultaneously — which defeats the whole purpose of multi-AZ architecture.

Before we start, I'm assuming you have basic knowledge of AWS IAM, know how to navigate the AWS console, and are familiar with using the AWS CLI.

Understanding core concepts:

What is AWS S3?

Amazon S3 is defined by AWS as an industry-leading object storage service that sets the standard for scalability, data availability, security, and performance. The service enables organizations to store and protect unlimited amounts of data for diverse use cases, ranging from data lakes and websites to cloud-native applications and machine learning initiatives. Amazon S3 is engineered to deliver exceptional reliability with a designed durability of 99.999999999% (11 9's), serving millions of customers globally with their data storage needs. This robust infrastructure supports various operational requirements, including data analytics, archival storage, and backup solutions, making it a cornerstone of modern cloud architecture.

Why Choose S3?

Amazon S3 has established itself as the high standard for cloud storage, by offering a combination of reliability, scalability, and cost-effectiveness that makes it an ideal choice for businesses of all sizes. At its core, S3's architecture delivers exceptional durability—99.999999999% (11 nines)—meaning that if you store 10 million objects, you can expect to lose only one object every 10,000 years. This durability is achieved through automatic replication across multiple facilities within your chosen region, ensuring your data remains safe even if entire data centers fail.

Beyond durability, S3's availability guarantee of 99.99% means your data is accessible when you need it, which is crucial for business-critical applications. The service scales automatically without any intervention. Whether you're storing a few gigabytes or several petabytes, S3 grows with your needs without requiring any capacity planning or hardware provisioning.

The pay-as-you-go pricing model transforms how organizations approach storage costs. Rather than making large upfront investments in storage hardware that might go underutilized, you pay only for the storage you actually use. This model is particularly beneficial for startups and growing businesses, as it allows them to start small and scale their storage costs in direct proportion to their growth.

S3's deep integration with other AWS services creates a powerful ecosystem for building sophisticated applications. You can trigger Lambda functions when new files arrive, process data with Amazon EMR, or deliver content through CloudFront with just a few clicks. This seamless integration eliminates the complexity of building and maintaining custom integration points between different services.

Security is another cornerstone of S3's design. The service provides multiple layers of security controls, including bucket policies, IAM policies, encryption at rest and in transit, and versioning to protect against accidental deletions or modifications. These features help organizations meet various compliance requirements while maintaining the flexibility to implement security best practices.

What is Object?

An object in Amazon S3 represents any data you wish to store and retrieve, including static files, backups, unstructured data, log files, and more. Objects can range in size from zero bytes to 5 terabytes. Each object consists of two main components: the actual file and its associated metadata. The metadata contains essential information such as content type and additional key-value data. Amazon S3 supports two distinct types of metadata: system-defined and user-defined. System-defined metadata includes automatically tracked properties such as the object's creation date, size, and storage class. User-defined metadata consists of optional name-value pairs that you can specify when uploading an object, allowing you to add custom attributes that suit your specific needs.

What is Bucket?

In Amazon S3, a bucket serves as container for storing objects. Think of a bucket as a top-level directory that helps organize and control access to your objects. Each bucket must have a globally unique name across all AWS accounts worldwide, as this name becomes part of the URL used to access your objects. When creating a bucket, you select a specific AWS Region where it will reside, which affects factors such as latency, cost, and compliance requirements. Buckets also play a role in access control and security management—you can configure bucket-level permissions, enable versioning, set lifecycle policies, and implement encryption settings. By default, all buckets and objects are private, but you have the flexibility to make either the entire bucket public or specific objects within it using bucket policies and Access Control Lists (ACLs). Bucket policies operate at the bucket level, allowing you to grant broad permissions, while ACLs provide more granular control at the object level—letting you make individual files publicly accessible even if the bucket itself remains private. This dual-layer approach to access control gives you precise control over your data's visibility, While S3 provides unlimited storage capacity, there are some service limits to consider: an AWS account can have up to 100 buckets by default (though this limit can be increased), and objects within a bucket can't be nested more than approximately 1,000 levels deep.

Organizing Objects with Keys/Prefixes

In Amazon S3, every object needs a unique identifier within its bucket, and this identifier is called a key. Think of a key as the complete path to your object, similar to how you might locate a file on your computer. For example, if you store a file called "profile.jpg" in a folder named "images" within your "users" folder, its key would be "users/images/profile.jpg".

The prefix is any part of the key that helps create a logical grouping of objects, much like folders in a traditional file system. In our example, both "users/" and "users/images/" are prefixes. However, it's important to understand that S3 doesn't actually have a folder hierarchy—it just uses these prefixes to create the illusion of folders for easier organization. When you see folders in the S3 console, you're actually looking at a user-friendly visualization of these prefixes.

Let's consider a practical example. Imagine you're storing user data for a social media application. You might organize your objects with keys like:

• "users/john/profile.jpg"

• "users/john/posts/2024/01/post1.jpg"

• "users/sarah/profile.jpg"

• "users/sarah/posts/2024/01/post2.jpg"

In this structure, "users/", "users/john/", and "users/john/posts/2024/01/" are all prefixes that help organize the objects logically. This organization becomes particularly valuable when you want to:

• List all objects for a specific user

• Find all posts from a particular month

• Apply permissions to groups of related objects

• Set lifecycle policies for certain types of content

Understanding keys and prefixes is important because they affect how you interact with your objects, influence performance, and impact your application's design. For instance, if you expect to have millions of objects, choosing an effective key naming strategy becomes essential for optimal performance.

URLs and endpoints

Every object in Amazon S3 has its own unique URL that serves as its web address. These URLs follow a consistent structure that reflects how S3 organizes your data. The standard format for an S3 URL looks like this: https://bucket-name.s3.region.amazonaws.com/object-key. For instance, if you have an image called "profile.jpg" in a bucket named "my-company-assets" in the us-east-1 region, its URL would be: https://my-company-assets.s3.us-east-1.amazonaws.com/profile.jpg.

S3 also provides different types of endpoints to suit various access patterns and security requirements. The most common endpoint types are Virtual-hosted style and Path-style. Virtual-hosted style URLs place the bucket name as part of the domain name (as shown in the example above), while Path-style URLs place the bucket name after the domain (like https://s3.region.amazonaws.com/bucket-name/object-key). Though Path-style endpoints are being phased out for newer regions, they're still supported in older ones.

Common Use Cases

Let's explore these common use cases and important considerations to keep in mind when implementing S3:

Static website hosting

One of the most popular uses of S3 is static website hosting. Whether you're hosting a simple portfolio site or a complex web application's assets, S3 can serve your HTML, CSS, JavaScript, images, and other static content reliably and efficiently. When combined with Amazon CloudFront, S3 becomes a powerful content delivery platform, ensuring your content reaches users quickly regardless of their location.

Data lakes and big data analytics

Data lakes represent another significant use case, where S3 serves as the foundation for big data analytics. Organizations store vast amounts of structured and unstructured data in S3, then use services like Amazon Athena or Amazon EMR to analyze this data without moving it to separate analytics platforms. This approach eliminates the need for complex extract, transform, and load (ETL) processes and allows for more flexible data analysis.

Backup and disaster recovery

Backup and disaster recovery solutions frequently rely on S3's durability and availability guarantees. Companies can automatically backup their databases, file systems, and application data to S3, knowing it's protected across multiple facilities. The various storage classes available in S3, from Standard to Glacier, allow organizations to optimize costs based on how quickly they need to access their backups.

Application asset storage

Mobile and cloud-native applications often use S3 as their primary storage backend. Whether storing user-generated content, application assets, or log files, S3's scalability ensures the storage grows seamlessly with the application's user base. The robust security features and fine-grained access controls make it suitable for handling sensitive user data while maintaining compliance requirements.

When implementing S3 for any of these use cases, several key considerations should guide your design decisions. First, consider your data access patterns – how frequently you'll need to retrieve data and how quickly you need it – as this affects your choice of storage class and potentially your costs. Security should be a primary concern; implement the principle of least privilege using IAM roles and bucket policies, and decide whether you need server-side encryption or additional security measures.

Cost optimization is another crucial consideration. While S3's pay-as-you-go model is attractive, costs can accumulate through storage, requests, and data transfer. Implement lifecycle policies to move infrequently accessed data to cheaper storage tiers and set up monitoring to track usage patterns and identify optimization opportunities. Finally, consider your application's performance requirements and implement best practices like enabling transfer acceleration or using appropriate naming schemes for high request rates.

Conclusion

We've covered the core concepts of objects, buckets, keys, and endpoints, providing you with the essential knowledge needed to understand how S3 organizes and manages your data, however, this is just the beginning of our journey into Amazon S3. In our next article, we'll dive deeper into S3's security features, exploring how to protect your data using IAM policies, bucket policies, and encryption options. We'll examine access control mechanisms in detail, including how to safely configure public access when needed and how to implement fine-grained permissions using ACLs. Understanding these security concepts is crucial for building secure and compliant storage solutions in the cloud.

Setup React Project

Create new project & configure Tailwind.css

Before we dive in, you'll need a React project with Tailwind CSS configured. Feel free to set up the project in your preferred way, or to save time, you can clone repository and start from the base branch

Install necessary dependencies

We'll need these key dependencies:

• i18next - core internationalization framework

• react-i18next - React bindings for i18next

• i18next-browser-languagedetector - auto-detects user's language preference from browser settings (optional)

📒 Note: The language detector is optional if you prefer implementing your own language switcher, which we'll also cover in this guide

💡 Quick Link: For this section's code, check out the base branch

Basic i18next Configuration

Initialize i18next

Let's start with the basic configuration. To understand how i18next works, we first need to create a configuration file. This file needs to be bundled, so we'll import it at the root of our app

import i18n from "i18next";
import { initReactI18next } from "react-i18next";
import LanguageDetector from "i18next-browser-languagedetector";

i18n
  .use(LanguageDetector)
  .use(initReactI18next)
  .init({
    debug: true,
    lng:"en",
    fallbackLng: "en",
    interpolation: {
      escapeValue: false, // not needed for react as it escapes by default
    },
    resources: {
      en: {
        translation: {
          welcome: "Hi",
        },
      },
      de: {
        translation: {
          welcome: "Hallo",
        },
      },
      ar: {
        translation: {
          welcome: "مرحبا",
        },
      },
    },
  });

export default i18n;

root app file: main.tsx (in my case)

import { StrictMode } from "react";
import { createRoot } from "react-dom/client";
import "./index.css";

import App from "./app";
import "./app/i18n";

createRoot(document.getElementById("root")!).render(
  <StrictMode>
    <App />
  </StrictMode>
);

Now let's test our localization setup. Open the App file and verify that everything works correctly

import { useTranslation } from "react-i18next";

function App() {
  const { t } = useTranslation();
  return (
    <div className="h-screen flex justify-center items-center">
      <h1 className="text-red-600 font-bold">{t("welcome")}</h1>
    </div>
  );
}
export default App;

if you see a message like this in your browser's console, congratulations! 🎉 The localization setup is working correctly

and you get this result in the interface:

Now let's explore the key configuration options:

• use: Loads additional i18next plugins (more details)

• debug: Enables debugging in development (more details)

• fallbackLng: Sets default language when translations are missing (more details)
  lng: Sets default language

• interpolation: Handles dynamic values in translations (more details)

• resources: Defines translations in key-value format (more details)

Let's dive into implementing localization:

• useTranslation: The main hook provided by i18next that returns:

  • t: Function that translates your content

  • i18n: Instance that manages language switching and other configuration options

i18next provides multiple ways to handle translations based on your needs:

• withTranslation: A Higher-Order Component (HOC) that gives your component access to t and i18n (more details)

    import React from 'react';
    import { withTranslation } from 'react-i18next';
  
    function App({ t, i18n }) {
      return <div className="h-screen flex justify-center items-center">
          <h1 className="text-red-600 font-bold">{t("welcome")}</h1>
        </div>
    }
  
    export default withTranslation()(App);
  

• Translation: A render prop component that provides t function and i18n instance to your component (more details)

    import React from 'react';
    import { Translation } from 'react-i18next';
  
    export function App() {
      return (
        <Translation>
          {
            (t, { i18n }) => <div className="h-screen flex justify-center items-center">
          <h1 className="text-red-600 font-bold">{t("welcome")}</h1>
        </div>
          }
        </Translation>
      )
    }
  

• <Trans>: A component that handles complex translations with React elements and interpolation (more details)

📒 Note: In most cases, you'll only need useTranslation hook, which provides a simpler and more straightforward way to handle translations.

💡 Quick Link: For explore more language tags locale codes check out Wikipedia

💡 Quick Link: For this section's code, check out the basic-configuration branch

Translation File Organization

As discussed in our previous article, localization involves collaboration with translators and legal teams. Therefore, we need a well-organized and structured approach to manage translations, In this section, we'll dive into that

JSON structure

For better translation management, we can separate our translations into JSON files and spread them into the i18next configuration like this:

import i18n from "i18next";
import { initReactI18next } from "react-i18next";
import LanguageDetector from "i18next-browser-languagedetector";
import enTranslation from "../locales/english/translation.json";
import deTranslation from "../locales/deutsch/translation.json";
import arTranslation from "../locales/arabic/translation.json";
i18n
  .use(LanguageDetector)
  .use(initReactI18next)
  .init({
    debug: true,
    lng: "en",
    fallbackLng: "ar",
    interpolation: {
      escapeValue: false, // not needed for react as it escapes by default
    },
    resources: {
      en: {
        translation: {
          ...enTranslation,
        },
      },
      de: {
        translation: {
          ...deTranslation,
        },
      },
      ar: {
        translation: {
          ...arTranslation,
        },
      },
    },
  });

export default i18n;

📒 Note: We'll improve this later by using the i18next-http-backend plugin to enhance performance when loading translations.

💡 Quick Link: For this section's code, check out the json-structure branch

Namespaces

When considering performance, we need to optimize how translations are loaded. i18next provides a powerful feature called namespaces that helps us:

• Split translations into multiple files

• Load translations on demand, not on initial page load

• Organize translations into logical categories

Common namespace examples:

• common: Shared translations (buttons, labels)

• validation: Form validation messages

• auth: Authentication-related content

This approach improves both performance and maintainability by loading only the translations needed for each part of your application, let’s dive into it

I've organized the translations into these namespaces:

• auth: Authentication-related content

• common: Shared actions and frequently used text

• validation : Form validation messages

// File structure:
// src/
//  locales/
//    english/
//      common.json
//      validation.json
//      auth.json


// English (english/common.json)
{
 "actions": {
   "create": "Create",
   "delete": "Delete",
   "cancel": "Cancel",
   "save": "Save"
 },
 "messages": {
   "loading": "Please wait...",
   "success": "Operation completed successfully",
   "error": "Something went wrong"
 }
}

// English (english/validation.json)
{
  "required": "This field is required",
  "email": "Please enter a valid email",
  "password": {
    "min": "Password must be at least {{min}} characters",
    "match": "Passwords do not match"
  }
}

// English (english/auth.json)
{
  "login": {
    "title": "Welcome Back",
    "submit": "Sign In",
    "forgotPassword": "Forgot Password?"
  },
  "register": {
    "title": "Create Account",
    "submit": "Sign Up"
  }
}

back to configuration to fit current change:

import i18n from "i18next";
import { initReactI18next } from "react-i18next";
import LanguageDetector from "i18next-browser-languagedetector";

import enCommon from "../locales/english/common.json";
import enValidation from "../locales/english/validation.json";
import enAuth from "../locales/english/auth.json";

import deCommon from "../locales/deutsch/common.json";
import deValidation from "../locales/deutsch/validation.json";
import deAuth from "../locales/deutsch/auth.json";

import arCommon from "../locales/arabic/common.json";
import arValidation from "../locales/arabic/validation.json";
import arAuth from "../locales/arabic/auth.json";

i18n
  .use(LanguageDetector)
  .use(initReactI18next)
  .init({
    debug: true,
    lng: "en",
    fallbackLng: "en",

    // Define default namespace
    defaultNS: "common",

    interpolation: {
      escapeValue: false, // not needed for react as it escapes by default
    },

    resources: {
      en: {
        common: enCommon,
        validation: enValidation,
        auth: enAuth,
      },
      de: {
        common: deCommon,
        validation: deValidation,
        auth: deAuth,
      },
      ar: {
        common: arCommon,
        validation: arValidation,
        auth: arAuth,
      },
    },
  });

export default i18n;

Now let's test our implementation. I've created a login form component that includes validation. First, install the required packages:

pnpm install zod react-hook-form @hookform/resolvers

Let's create our form component that leverages namespaces with form validation:

import { useTranslation } from "react-i18next";
import { z } from "zod";
import { useForm } from "react-hook-form";
import { zodResolver } from "@hookform/resolvers/zod";

function LoginForm() {
  const { t } = useTranslation(["auth", "validation", "common"]);

  const loginSchema = z.object({
    email: z
      .string()
      .min(1, t("validation:required"))
      .email(t("validation:email")),
    password: z.string().min(8, t("validation:password.min", { min: 8 })),
  });

  type LoginFormData = z.infer<typeof loginSchema>;

  const {
    register,
    handleSubmit,
    formState: { errors },
  } = useForm<LoginFormData>({
    resolver: zodResolver(loginSchema),
  });

  const onSubmit = (data: LoginFormData) => {
    console.log(data);
  };

  return (
    <div className="min-h-screen flex items-center justify-center bg-gray-50 py-12 px-4 sm:px-6 lg:px-8">
      <div className="max-w-md w-full space-y-8">
        <div>
          <h1 className="mt-6 text-center text-3xl font-extrabold text-gray-900">
            {t("auth:login.title")}
          </h1>
        </div>

        <form className="mt-8 space-y-6" onSubmit={handleSubmit(onSubmit)}>
          <div className="rounded-md shadow-sm -space-y-px">
            <div>
              <input
                {...register("email")}
                type="email"
                className="appearance-none rounded-none relative block w-full px-3 py-2 border border-gray-300 placeholder-gray-500 text-gray-900 rounded-t-md focus:outline-none focus:ring-indigo-500 focus:border-indigo-500 focus:z-10 sm:text-sm"
              />
              {errors.email && (
                <span className="text-red-500 text-xs mt-1">
                  {errors.email.message}
                </span>
              )}
            </div>

            <div>
              <input
                {...register("password")}
                type="password"
                className="appearance-none rounded-none relative block w-full px-3 py-2 border border-gray-300 placeholder-gray-500 text-gray-900 rounded-b-md focus:outline-none focus:ring-indigo-500 focus:border-indigo-500 focus:z-10 sm:text-sm"
              />
              {errors.password && (
                <span className="text-red-500 text-xs mt-1">
                  {errors.password.message}
                </span>
              )}
            </div>
          </div>

          <div className="flex items-center justify-between">
            <a
              href="#"
              className="text-sm text-indigo-600 hover:text-indigo-500"
            >
              {t("auth:login.forgotPassword")}
            </a>
          </div>

          <div className="flex gap-4">
            <button
              type="submit"
              className="group relative w-full flex justify-center py-2 px-4 border border-transparent text-sm font-medium rounded-md text-white bg-indigo-600 hover:bg-indigo-700 focus:outline-none focus:ring-2 focus:ring-offset-2 focus:ring-indigo-500"
            >
              {t("auth:login.submit")}
            </button>
            <button
              type="button"
              className="group relative w-full flex justify-center py-2 px-4 border border-gray-300 text-sm font-medium rounded-md text-gray-700 bg-white hover:bg-gray-50 focus:outline-none focus:ring-2 focus:ring-offset-2 focus:ring-indigo-500"
            >
              {t("common:actions.cancel")}
            </button>
          </div>
        </form>
      </div>
    </div>
  );
}

export default LoginForm;

Import the form component into your main interface/App file:

import LoginForm from "../components/auth/login/form";

function App() {
  return <LoginForm />;
}
export default App;

Expected result:

now let’s break out the details:

• In our configuration, we:

  • Changed the default namespace from translation to multiple namespaces: auth, common, and validation

  • Set common as the default namespace using defaultNS: 'common'

• To use these namespaces in components:

  • Load required namespaces:

      const { t } = useTranslation(["auth", "validation", "common"]);
    

  • Access translations using namespace prefix:

      <h1 className="mt-6 text-center text-3xl font-extrabold text-gray-900">
        {t("auth:login.title")}
      </h1>
    

💡 Quick Link: For this section's code, check out the namespaces branch

Core Translation Features

What makes i18next a mature, production-ready framework is its ability to handle complex scenarios such as:

• Plural forms

• Number and date formatting

• Translation interpolation

• Dynamic values and variables

Basic text translation

Let's look at a real example. Imagine we have a dashboard where we want to display a personalized greeting. For instance, if the user's name is Othmane, we want to show 'Hello Othmane!'. Here's how to implement this:

• In your localization folder (/locales/[language]/common.json), add these translations:

    "greeting": {
            "title": "Hello, {{name}}",
            "subtitle": "Welcome to your dashboard"
          },
  

• Add new component dashboard and import it to page:

    import { useTranslation } from "react-i18next";
  
    function Dashboard() {
      const { t } = useTranslation();
      // This can be dynamic based on your needs
      const userName = "Othmane";
  
      return (
        <div className="min-h-screen flex items-center justify-center">
          <div className="max-w-2xl w-full mx-auto p-8 bg-white rounded-lg shadow-lg">
            <h1 className="text-3xl font-bold text-center bg-gradient-to-r from-blue-600 to-purple-600 bg-clip-text text-transparent">
              {t("greeting.title", { name: userName })}
            </h1>
            <p className="mt-4 text-lg text-gray-600 text-center leading-relaxed">
              {t("greeting.subtitle")}
            </p>
          </div>
        </div>
      );
    }
    export default Dashboard;
  

  There's no need to explicitly specify 'common' as the namespace in useTranslation(), since we've already configured it as the default namespace in our i18n configuration. This simplifies our code and reduces redundancy while maintaining the same functionality.

• Expected result:

  

  

📝 Note: Arabic is a Right-to-Left (RTL) language. We will cover later how to handle RTL text direction using Tailwind CSS's built-in RTL support through the rtl: directive. This includes:

• Text alignment

• Margin and padding

• Borders and shadows

• Layout direction

Handling plurals

Handling plurals is a crucial and challenging aspect of internationalization, as it extends beyond the simple singular/plural format found in English. Many languages, such as Arabic and Russian, have multiple plural forms. The i18n framework efficiently manages these complexities by providing built-in support for the plural rules of all your supported languages.

starting by real example and break out the details box, we have a listItem we need to render the total of those items based on counter that dynamically passed to t function:

• In your localization folder (/locales/en/common.json), add these translations:

     "item_zero": "No items",
      "item_one": "{{count}} item",
      "item_other": "{{count}} items",
      "pluralExample": {
        "title": "Plural example",
        "currentLang": "current Language"
      },
  

• In your localization folder (/locales/ar/common.json), add these translations:

      "item_zero": "لا توجد عناصر",
      "item_one": "عنصر واحد",
      "item_two": "عنصران",
      "item_few": "{{count}} عناصر",
      "item_many": "{{count}} عنصراً",
      "item_other": "{{count}} عنصر",
      "pluralExample": {
        "title": "مثال الجمع",
        "currentLang": "اللغة الحالية"
      },
  

• Add new component dashboard and import it to page:

    import { useTranslation } from "react-i18next";
  
    export default function ItemsList() {
      const { t, i18n } = useTranslation();
  
      const quantities = [0, 1, 2, 3, 11, 100];
  
      return (
        <div className="min-h-screen flex items-center justify-center bg-gray-50">
          <div className="max-w-2xl w-full mx-auto p-8 bg-white rounded-xl shadow-lg">
            {/* Header Section */}
            <div className="mb-8 text-center">
              <h2 className="text-2xl font-bold bg-gradient-to-r from-blue-600 to-purple-600 bg-clip-text text-transparent">
                {t("pluralExample.title")}
              </h2>
              <p className="mt-2 text-gray-600">
                {t("pluralExample.currentLang")}:{" "}
                {i18n.language === "en" ? "English" : "العربية"}
              </p>
            </div>
  
            {/* Examples Grid */}
            <div className="grid grid-cols-1 md:grid-cols-2 gap-4">
              {quantities.map((count) => (
                <div
                  key={count}
                  className="p-4 border border-gray-200 rounded-lg hover:border-blue-500 transition-colors duration-300"
                >
                  <div className="flex items-center justify-between">
                    <span className="text-lg font-semibold text-blue-600">
                      {count}
                    </span>
                    <span className="text-gray-700">{t("item", { count })}</span>
                  </div>
                </div>
              ))}
            </div>
  
            {/* Language Switch Button */}
            <div className="mt-8 text-center">
              <button
                onClick={() =>
                  i18n.changeLanguage(i18n.language === "en" ? "ar" : "en")
                }
                className="px-6 py-2 bg-gradient-to-r from-blue-600 to-purple-600 text-white rounded-lg
                         hover:from-blue-700 hover:to-purple-700 transition-all duration-300
                         focus:outline-none focus:ring-2 focus:ring-blue-500 focus:ring-offset-2"
              >
                Switch to {i18n.language === "en" ? "Arabic" : "English"}
              </button>
            </div>
          </div>
        </div>
      );
    }
  

• Expected result:

  

  

Different languages have varying rules for handling plural forms:

English (2 forms):

• one: for exactly 1 (1 item)

• other: for 0 and numbers greater than 1 (0 items, 2 items, etc.)

Arabic (6 forms):

• zero: for 0

• one: for exactly 1

• two: for exactly 2

• few: for 3-10

• many: for 11-99

• other: for 100+

Example quantities:

• 0 → No items | لا توجد عناصر

• 1 → 1 item | عنصر واحد

• 2 → 2 items | عنصران

• 5 → 5 items | 5 عناصر

• 15 → 15 items | 15 عنصراً

• 100 → 100 items | 100 عنصر

i18n automatically handles these rules based on the selected language and the provided count value.

📝 Note: To enhance your multilingual development workflow in VSCode, you can use the i18n-ally extension. It provides:

• Real-time translation previews in your code

• Locale file management

• Auto-completion for translation keys

• Inline translation annotations

In this project, I've configured i18n-ally with English as the source language. This extension works with any framework and helps streamline translation management.

💡 Quick Link: For this section's code, check out the Plural branch

Number & Date formatting

i18next's flexible interpolation system allows you to create custom format functions by leveraging the Intl API, which is widely supported in modern browsers. This enables advanced number formatting through custom interpolation functions. Let's examine a comprehensive implementation:

// i18n configuration:
import i18n, { FormatFunction } from "i18next";
import { initReactI18next } from "react-i18next";
import LanguageDetector from "i18next-browser-languagedetector";

// Import namespaces for each language
import enCommon from "../locales/en/common.json";
import enValidation from "../locales/en/validation.json";
import enAuth from "../locales/en/auth.json";

import deCommon from "../locales/de/common.json";
import deValidation from "../locales/de/validation.json";
import deAuth from "../locales/de/auth.json";

import arCommon from "../locales/ar/common.json";
import arValidation from "../locales/ar/validation.json";
import arAuth from "../locales/ar/auth.json";

i18n
  .use(LanguageDetector)
  .use(initReactI18next)
  .init({
    debug: true,
    lng: "ar",
    fallbackLng: "en",

    // Define default namespace
    defaultNS: "common",

    interpolation: {
      format: function (value, format, lng) {
        console.log({ value, format, lng });
        const numValue = Number(value);
        if (!isNaN(numValue)) {
          switch (format) {
            // Currency, Decimal, Percent, Compact
            case "currency":
              return new Intl.NumberFormat(lng, {
                style: "currency",
                currency: lng === "ar" ? "SAR" : "USD",
              }).format(numValue);
            case "decimal":
              return new Intl.NumberFormat(lng, {
                minimumFractionDigits: 2,
                maximumFractionDigits: 2,
              }).format(numValue);
            case "percent":
              return new Intl.NumberFormat(lng, {
                style: "percent",
                minimumFractionDigits: 2,
                maximumFractionDigits: 2,
              }).format(numValue);
            case "compact":
              return new Intl.NumberFormat(lng, {
                notation: "compact",
                compactDisplay: "short",
              }).format(numValue);

            // Units
            case "bytes":
              return new Intl.NumberFormat(lng, {
                style: "unit",
                unit: "byte",
                unitDisplay: "long",
              }).format(numValue);
            case "kg":
              return new Intl.NumberFormat(lng, {
                style: "unit",
                unit: "kilogram",
                unitDisplay: "long",
              }).format(numValue);
            case "meter":
              return new Intl.NumberFormat(lng, {
                style: "unit",
                unit: "meter",
                unitDisplay: "long",
              }).format(numValue);
            case "temperature":
              return new Intl.NumberFormat(lng, {
                style: "unit",
                unit: "celsius",
                unitDisplay: "long",
              }).format(numValue);
            default:
              return numValue.toString();
          }
        }
        return String(value);
      } as FormatFunction,
      escapeValue: false, // not needed for react as it escapes by default
    },

    resources: {
      en: {
        common: enCommon,
        validation: enValidation,
        auth: enAuth,
      },
      de: {
        common: deCommon,
        validation: deValidation,
        auth: deAuth,
      },
      ar: {
        common: arCommon,
        validation: arValidation,
        auth: arAuth,
      },
    },
  });

export default i18n;

for translations :

// en:
  "numberExample": {
    "title": "Number Formatting Examples",
    "currency": "Currency: {{value, currency}}",
    "decimal": "Decimal: {{value, decimal}}",
    "percent": "Percentage: {{value, percent}}",
    "compact": "Compact: {{value, compact}}",
    "bytes": "Bytes: {{value, bytes}}",
    "kg": "Weight: {{value, kg}}",
    "meter": "Length: {{value, meter}}",
    "temperature": "Temperature: {{value, temperature}}"
  },
// ar:
"numberExample": {
    "title": "أمثلة تنسيق الأرقام",
    "currency": "العملة: {{value, currency}}",
    "decimal": "العدد العشري: {{value, decimal}}",
    "percent": "النسبة المئوية: {{value, percent}}",
    "compact": "مختصر: {{value, compact}}",
    "bytes": "الحجم: {{value, bytes}}",
    "kg": "الوزن: {{value, kg}}",
    "meter": "الطول: {{value, meter}}",
    "temperature": "درجة الحرارة: {{value, temperature}}"
  },

Component implementation:

import { useTranslation } from "react-i18next";

export default function NumberFormats() {
  const { t, i18n } = useTranslation();
  const isRTL = i18n.language === "ar";

  const examples = [
    { type: "currency", value: 1234567.89 },
    { type: "decimal", value: 1234567.89 },
    { type: "percent", value: 0.8567 },
    { type: "compact", value: 1234567 },
    { type: "bytes", value: 1024 },
    { type: "kg", value: 75.5 },
    { type: "meter", value: 150 },
    { type: "temperature", value: 25 },
  ];

  return (
    <div className="min-h-screen flex items-center justify-center bg-gray-50">
      <div
        dir={isRTL ? "rtl" : "ltr"}
        className="max-w-2xl w-full mx-auto p-8 bg-white rounded-xl shadow-lg"
      >
        <div className="mb-8 text-center">
          <h2 className="text-2xl font-bold bg-gradient-to-r from-blue-600 to-purple-600 bg-clip-text text-transparent">
            {t("numberExample.title")}
          </h2>
        </div>

        <div className="space-y-4">
          {examples.map(({ type, value }) => (
            <div
              key={type}
              className="p-4 border border-gray-200 rounded-lg hover:border-blue-500 transition-colors duration-300"
            >
              <p className="text-gray-700">
                {t(`numberExample.${type}`, {
                  value,
                })}
              </p>
            </div>
          ))}
        </div>

        <div className="mt-8 text-center">
          <button
            onClick={() => i18n.changeLanguage(isRTL ? "en" : "ar")}
            className="px-6 py-2 bg-gradient-to-r from-blue-600 to-purple-600 text-white rounded-lg
                     hover:from-blue-700 hover:to-purple-700 transition-all duration-300
                     focus:outline-none focus:ring-2 focus:ring-blue-500 focus:ring-offset-2"
          >
            Switch to {isRTL ? "English" : "Arabic"}
          </button>
        </div>
      </div>
    </div>
  );
}

Expected result:

The custom format function provides flexibility beyond just Intl API usage. You can integrate other formatting libraries as fallbacks for browsers with limited Intl API support. Similarly, this approach can be applied to date formatting.

💡 Quick Link: For this section's code, check out the Formatting branch

Language Switching

A crucial aspect of supporting multiple languages is allowing users to choose their preferred language rather than relying solely on browser-detected settings. i18next provides comprehensive tools to handle language switching, loading, and configuration. It also manages language detection, changing, and initialization. Let's explore how to implement these features:

Language selector component

We've already implemented some of these features in previous sections. The useTranslation hook returns an i18n instance that we can use to change and retrieve the current language, as shown in the example below:

import { useTranslation } from "react-i18next";

export default function NumberFormats() {
  const { t, i18n } = useTranslation();
  const isRTL = i18n.language === "ar";
  return (
        <div className="mt-8 text-center">
          <button
            onClick={() => i18n.changeLanguage(isRTL ? "en" : "ar")}
            className="px-6 py-2 bg-gradient-to-r from-blue-600 to-purple-600 text-white rounded-lg
                     hover:from-blue-700 hover:to-purple-700 transition-all duration-300
                     focus:outline-none focus:ring-2 focus:ring-blue-500 focus:ring-offset-2"
          >
            Switch to {isRTL ? "English" : "Arabic"}
          </button>
        </div>
  );
}

i18n provides several useful functions and properties for language management:

• i18n.language: Gets the currently loaded language

• i18n.dir(): Returns the text direction (RTL/LTR) based on the current language, or for a specific language when passed as an argument

• i18n.changeLanguage(): Asynchronous function that changes the active language. Returns a Promise, allowing error handling with try/catch

💡 Quick Link: For more details about API, check out this page

Events & Persisting language preference

Persisting the preference language of the user is most handled case you should covered in your application, i18n provides powerful events for make it easier for you

One important event for data persistence is languageChanged. This event fires when the language changes, allowing you to execute callback functions. Here's how to implement this functionality to save the preferred language in localStorage:

import i18n, { FormatFunction } from "i18next";
import { initReactI18next } from "react-i18next";
import LanguageDetector from "i18next-browser-languagedetector";

// Import namespaces for each language
import enCommon from "../locales/en/common.json";
import enValidation from "../locales/en/validation.json";
import enAuth from "../locales/en/auth.json";

import deCommon from "../locales/de/common.json";
import deValidation from "../locales/de/validation.json";
import deAuth from "../locales/de/auth.json";

import arCommon from "../locales/ar/common.json";
import arValidation from "../locales/ar/validation.json";
import arAuth from "../locales/ar/auth.json";
const getStoredLanguage = () => {
  const storedLanguage = localStorage.getItem("language");
  return storedLanguage || navigator.language.split("-")[0];
};
i18n
  .use(LanguageDetector)
  .use(initReactI18next)
  .init({
    debug: true,
    lng: getStoredLanguage(),
    fallbackLng: "en",
    // Define default namespace
    defaultNS: "common",
    interpolation: {
      escapeValue: false, // not needed for react as it escapes by default
    },
    resources: {
     //
    },
  });

i18n.on("languageChanged", (lng) => {
  localStorage.setItem("language", lng);
});

export default i18n;

💡 Quick Link: For this section's code, check out the persistence-events branch

💡 Quick Link: For more details about Events, check out this page

RTL Support

Several languages are written from right to left (RTL). While these languages are less common in Western web development, they serve millions of users globally. The main RTL languages include Arabic, Hebrew, and Persian.

Supporting RTL languages significantly expands your application's reach. Tailwind CSS v3 makes this easier with its built-in rtl: and ltr: modifiers, allowing you to create multi-directional layouts efficiently. (more details)

To enable Tailwind's RTL/LTR modifiers, we add a language change listener in our i18next configuration that updates the document's direction and language attributes:

i18n.on("languageChanged", (lng) => {
  localStorage.setItem("language", lng);
  // Set HTML lang attribute
  document.documentElement.lang = lng;
  // Set HTML dir attribute based on language
  document.dir = i18n.dir(lng);
});
document.dir = i18n.dir(i18n.language);
document.documentElement.lang = i18n.language;

Key RTL-aware classes in Tailwind CSS:

1. Spacing Classes:

• ps- instead of pl- for padding-start

• pe- instead of pr- for padding-end

• ms- instead of ml- for margin-start

• me- instead of mr- for margin-end

2. Positioning Classes:

• start- instead of left- for positioning

• end- instead of right- for positioning

• text-start instead of text-left for text alignment

3. Flex Layout:

• rtl:flex-row-reverse for reversing flex direction

• Flex items automatically adjust in RTL contexts

These logical properties ensure your layout works correctly in both LTR and RTL directions

💡 Quick Link: For this section's code, check out the rtl-support branch

Performance Optimization

Now that we've set up our internationalization system, let's optimize it for better performance. When dealing with multiple languages and translation files, it's crucial to consider bundle size and loading strategies. In this section, we'll explore how to optimize our i18next implementation using dynamic imports and file splitting

Now that we've set up our internationalization system, let's optimize it for better performance. When dealing with multiple languages and translation files, it's crucial to consider bundle size and loading strategies. In this section, we'll explore how to optimize our i18next implementation using dynamic imports and file splitting.

First, install the HTTP backend plugin:

pnpm add i18next-http-backend

1. Setup i18next-http-backend:

typescriptCopy// i18n.ts
import i18n from "i18next";
import { initReactI18next } from "react-i18next";
import HttpBackend from 'i18next-http-backend';
import LanguageDetector from "i18next-browser-languagedetector";

i18n
  .use(HttpBackend)
  .use(LanguageDetector)
  .use(initReactI18next)
  .init({
    backend: {
      loadPath: '/locales/{{lng}}/{{ns}}.json',
    },
    fallbackLng: "en",
    defaultNS: "common",

    // Disable suspense if needed
    react: {
      useSuspense: false
    }
  });

export default i18n;

2. Translation File Structure:

public/
  locales/
    en/
      common.json     # Shared translations
      auth.json       # Authentication translations
      dashboard.json  # Dashboard-specific translations
    ar/
      common.json
      auth.json
      dashboard.json

3. Lazy Loading Translations:

function Dashboard() {
  // Load dashboard translations only when needed
  const { t, i18n } = useTranslation('dashboard', {
    useSuspense: false
  });

  // Load multiple namespaces
  const { t } = useTranslation(['dashboard', 'common'], {
    useSuspense: false
  });

  return (
    <div>
      <h1>{t('dashboard:title')}</h1>
      <button>{t('common:actions.save')}</button>
    </div>
  );
}

By splitting translation files and implementing lazy loading, we achieve a smaller initial bundle size since only necessary translations are loaded. The on-demand translation loading means resources are fetched only when needed, while better caching capabilities ensure efficient resource management.

💡 Quick Link: For this section's code, check out the performance branch

Conclusion

This guide has walked you through implementing internationalization in modern web applications using i18next, from basic setup to handling complex formatting, plural rules, and RTL support. You can find the complete implementation and examples in the GitHub repository. While we've covered significant ground, there's always more to explore in the world of i18next and internationalization. If you need help implementing these features in your application or are interested in collaborating on i18n-related projects, feel free to reach out to me on LinkedIn or via email at contact@othmanekahtal.me. Stay tuned for more articles diving into advanced i18next features and internationalization patterns!

Project Repository

You can find the complete source code for this project on GitHub: Import Clients' Data via CSV

Prerequisites:

• Basic understanding of AWS Lambda and S3

• AWS SAM CLI installed

• Node.js knowledge

• AWS account with appropriate permissions

Project Overview

This application automates the process of importing clients' data via CSV files. Here's what it does:

1. Accepts CSV file uploads to an S3 bucket

2. Triggers a Lambda function to process the file

3. Validates and stores the data in DynamoDB

Implementation Details

SAM Template

Our infrastructure is defined using AWS SAM:

AWSTemplateFormatVersion: '2010-09-09'
Transform: AWS::Serverless-2016-10-31
Description: Lambda function with S3 and DynamoDB access

Parameters:
  ExistingBucketName:
    Type: String
    Description: Name of the existing S3 bucket to use

Resources:
  AppDynamoDBTable:
    Type: AWS::Serverless::SimpleTable
    Properties:
      PrimaryKey:
        Name: id
        Type: String
      ProvisionedThroughput:
        ReadCapacityUnits: 5
        WriteCapacityUnits: 5

  S3JsonLoggerFunction:
    Type: AWS::Serverless::Function
    Properties:
      Handler: src/handlers/s3-json-logger.s3JsonLoggerHandler
      Runtime: nodejs18.x
      Architectures:
        - x86_64
      MemorySize: 128
      Timeout: 60
      Policies:
        - S3ReadPolicy:
            BucketName: !Ref ExistingBucketName
        - DynamoDBCrudPolicy:
            TableName: !Ref AppDynamoDBTable
      Environment:
        Variables:
          APPDYNAMODBTABLE_TABLE_NAME: !Ref AppDynamoDBTable
          APPDYNAMODBTABLE_TABLE_ARN: !GetAtt AppDynamoDBTable.Arn
          S3_BUCKET_NAME: !Ref ExistingBucketName

Lambda Function

The Lambda function processes CSV files and stores data in DynamoDB:

import { S3Client, GetObjectCommand } from "@aws-sdk/client-s3";
import { sdkStreamMixin } from "@aws-sdk/util-stream-node";
import { parseString } from "@fast-csv/parse";
import { DynamoDBClient } from "@aws-sdk/client-dynamodb";
import {
  DynamoDBDocumentClient,
  PutCommand,
} from "@aws-sdk/lib-dynamodb";

const tableName = process.env.APPDYNAMODBTABLE_TABLE_NAME;
const client = new DynamoDBClient({});
const dynamo = DynamoDBDocumentClient.from(client);
const s3 = new S3Client({});

export const s3JsonLoggerHandler = async (event, context) => {
  const getObjectRequests = event.Records.map((record) => {
    return processS3Object(
      new GetObjectCommand({
        Bucket: record.s3.bucket.name,
        Key: record.s3.object.key,
      })
    );
  });
  await Promise.all(getObjectRequests);
};

// Data validation
const isValidClient = (record) => {
  const { name, email, company, phone, id, status } = record;
  return (
    name &&
    email &&
    company &&
    phone &&
    id &&
    status &&
    /^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(email)
  );
};

// Process S3 objects
const processS3Object = async (object) => {
  try {
    const data = await s3.send(object);
    const objectString = await sdkStreamMixin(data.Body).transformToString();

    const records = await new Promise((resolve, reject) => {
      const records = [];
      parseString(objectString, { headers: true })
        .on("error", (error) => {
          console.error("Error parsing CSV:", error);
          reject(error);
        })
        .on("data", async (row) => {
          if (isValidClient(row)) {
            records.push(row);
          }
        })
        .on("end", (rowCount) => {
          resolve(records);
        });
    });

    const insertPromises = records.map(insertIntoDynamoDB);
    return await Promise.all(insertPromises);
  } catch (err) {
    console.error("Error in processS3Object:", err);
    throw err;
  }
};

// Insert into DynamoDB
const insertIntoDynamoDB = async (record) => {
  try {
    const command = new PutCommand({
      TableName: tableName,
      Item: {
        id: record.id,
        name: record.name,
        email: record.email,
        company: record.company,
        phone: record.phone,
        status: record.status,
      },
    });
    await dynamo.send(command);
  } catch (err) {
    console.error(`Error inserting client ${record.email}:`, err);
  }
};

Smart Variable Usage: This project uses SAM parameters and environment variables instead of hard-coded values for S3 bucket names and DynamoDB configurations. This makes the application easy to maintain and deploy across different environments without code changes.

Event-Driven Architecture: The application uses S3 events to trigger Lambda functions automatically. This serverless approach enables efficient processing of multiple CSV files in parallel, improving performance for large data sets.

Data Validation: Before storing in DynamoDB, each record goes through validation checks for email format and required fields. This ensures data quality while properly handling and logging any invalid records.

CSV Format

Your CSV files should follow this structure:

id,name,email,company,phone,status
1,John Doe,john@example.com,Acme Inc,+1234567890,active
2,Jane Smith,jane@example.com,Tech Corp,+0987654321,pending

DVA-C02 Exam Topics Covered

This project helps understand several key exam topics:

• SAM template structure and deployment

• Lambda function development

• S3 event notifications

• DynamoDB operations

• IAM roles and policies

• Error handling patterns

Deployment

Deploy the application using SAM CLI (check the repository for the guide):

sam build
sam deploy --guided

What is Internationalization:

Internationalization or i18n (18 represents the number of characters between 'i' and 'n') is a process to make your product ready for a global audience by adopting multiple languages and cultures, as well as adding a smooth switching in your product based on user preferences.

Let's take a look at PayPal as a real example. When you select China as your region, the website adapts completely - not just the language changes, but also the example images used to demonstrate transactions. They show payment scenarios involving neighboring countries (India, Thailand, China) as well as transactions with distant countries like the United States.

In this section, we can see that even the testimonials are localized - PayPal displays only region-specific feedback from Chinese users, making the content more relevant and relatable to their local audience

Now, if we change the region to Saudi Arabia, we see a completely different page that respects the local culture and legal requirements of this region

The example above shows how PayPal creates region-specific landing pages, adapting their content, layout, and visuals based on each region's requirements and preferences

Internationalization best practices:

There are many things to keep in mind when implementing i18n properly, regardless of your role (Frontend or Backend engineer). before writing any code, you need to consider several crucial aspects:

• Database Design Considerations:

  • User preferences storage

  • Preferred language(s)

  • Region/location settings

  • Timezone

  • Date format preferences

  • Number format preferences (decimal separators, thousand separators)

  • Currency preferences

• Content Management:

  • Text content in multiple languages

  • Media assets adapted for different cultures

  • Region-specific legal content

  • Direction of text (LTR vs RTL support)

  • Local holidays and important dates

  • Region-specific contact information

• Technical Implementation:

  • Smooth language/region switching without page reload

  • Proper data formatting based on locale

    • Numbers (1,234.56 vs 1.234,56)

    • Dates (MM/DD/YYYY vs DD/MM/YYYY)

    • Times (12-hour vs 24-hour format)

    • Phone numbers

    • Addresses

  • Currency conversion and display

  • Timezone handling for scheduled events

  • Form validation for different formats

  • Search functionality across multiple languages

• User Experience:

  • Automatic language detection

  • Remembering user preferences

  • Fallback languages when translations are missing

  • Loading states during language switches

  • Clear language/region selection interface

  • Consistent formatting throughout the application

• Performance Considerations:

  • Lazy loading of language packs

  • Caching strategies for localized content

  • Bundle size management for multiple languages

  • Server-side rendering with correct locale

What is localization:

Localization or l10n (10 represents the number of characters between 'l' and 'n') is the process of adapting internationalized products and taking care of their content, whether it's images, videos, text, documents, colors, legal requirements, fonts, etc.

Let's go back to PayPal as an example. We notice that PayPal goes beyond just language translation and adapts both images and structure based on the activities and products they provide in each region. For instance, look at the image of the person used in the guide's cover.

Let's look at another region, like India. As we can see, the internationalization is working as expected - in this region, PayPal localizes the landing page specifically for the Indian market. We can notice this in both the images used and the types of businesses showcased below.

Looking at Singapore's version, we can see several regional adaptations: the phone number formats are localized, the hero section displays a different background

Internationalization and localization work in combination to maximize the chances of making your product reachable to a global audience. Engineers and developers take on the duty of implementing internationalization, while localization is a mission for translators.

Both concepts fall under the umbrella of globalization - making products ready to use everywhere in the world across all markets, regardless of cultures, languages, or regions.

As demonstrated in the examples above, PayPal takes a comprehensive approach to localization. Their region-specific landing pages go beyond simple translation - they adapt content, layout, visuals, and even featured businesses to match each region's unique requirements, cultural preferences, and market characteristics

I18n vs I10n : Key differences

The culture is more than different language

Local culture in each region isn't just about different languages - it's about different worlds, ideas, and much more. What's acceptable in one region might not be in others, like the Middle East or China. For example, red symbolizes luck and prosperity in Chinese culture, but can represent danger or warning in Western countries

Examples about that :

• E-commerce Platforms:

  • In the US, Black Friday is the biggest shopping event

  • In China, Singles' Day (11.11) is the major shopping festival

  • In Middle Eastern countries, Ramadan-specific shopping sections are prominent

  • In Japan, gift-wrapping options are crucial as presentation is highly valued

• Payment Preferences:

  • In China, QR code payments (WeChat Pay, Alipay) dominate

  • In Japan, cash payments are still widely preferred

  • In Northern Europe, card payments are standard

  • In India, Cash on Delivery is very popular

• Numbers and Symbols:

  • Number 4 is avoided in East Asian products (similar to 13 in Western countries)

  • Green is positive in Islamic countries but associated with infidelity in China

  • Thumbs-up gesture is offensive in some Middle Eastern countries

  • OK hand gesture is considered rude in Brazil

• Content Presentation:

  • In Western designs, white space is considered elegant

  • In East Asian markets, dense information layouts are often preferred

  • In Arab countries, designs should accommodate right-to-left reading

  • In Japan, cute mascots (kawaii culture) are effective for business communication

conclusion:

We can recap everything we discussed in this article: globalization is a crucial part of launching a successful product that respects both global requirements and local cultures. It's not a simple task but rather a continuous workflow, starting with prioritizing your target markets and ending with teams working closely together to achieve this goal.

Prerequisites:

• Familiarity with basic TypeScript types

• Familiarity with React.js

• Reading the previous article is recommended

TypeScript provides several built-in utilities that help reduce type duplication, making your code cleaner and easier to maintain. Let’s explore some of these utilities and see how they can be applied in real-world scenarios.

For Objects:

TypeScript provides utilities to avoid duplicating type definitions for objects. Let’s start with a basic object and apply some of these utilities!

type User = {
  email: string;
  first_name: string;
  last_name: string;
  username: string;
}

Pick vs. Omit:

Sometimes, we need to create a type similar to an existing one but with some properties added or removed. TypeScript provides the Omit and Pick utilities to make this easy:

type User = {
  email: string;
  first_name: string;
  last_name: string;
  username: string;
}

// Create new type without email and username:
type UserWithoutEmailUsername = Omit<User, 'email' | 'username'>
// Result:
// type UserWithoutEmailUsername = {
//   last_name: string;
//   first_name: string;
// }

In this example, we use Omit to exclude email and username from the User type.

type User = {
  email: string;
  first_name: string;
  last_name: string;
  username: string;
}

// Create new type with only email and username:
type UserWithEmailUsername = Pick<User, 'email' | 'username'>
// Result:
// type UserWithEmailUsername = {
//   email: string;
//   username: string;
// }

Here, we use Pick to include only email and username from the User type.

So, when should you use Pick or Omit? It depends on the type you want to manipulate and how you want to modify it.

Required vs. Partial:

Let’s consider a real scenario: you’re building an API application with endpoints for creating and updating resources. You need different types for each service function. Your code might look like this:

type User = {
    email: string;
    first_name: string;
    last_name: string;
    username: string;
}

function createUser(user: User) {
    // ....
    return {
        email: user.email,
        username: user.username,
        id: 10
    }
}
type OptionalUser = {
    email?: string;
    first_name?: string;
    last_name?: string;
    username?: string;
}
// You need an ID to query the user that you want to update
function updateUser(user: OptionalUser, id: number) {
    // ....
    return {
        email: user.email,
        username: user.username,
        id: 10
    }
}

But you can simplify this using Partial, making your code cleaner:

type User = {
    email: string;
    first_name: string;
    last_name: string;
    username: string;
}

function createUser(user: User) {
    // ....
    return {
        email: user.email,
        username: user.username,
        id: 10
    }
}
function updateUser(user: Partial<User>, id: number) {
    // ....
    return {
        email: user?.email,
        username: user?.username,
        id: 10
    }
}

This makes your code easier to understand and more consistent.

What if you have a type with optional properties, and you want to clone this type but make all properties required? TypeScript provides the Required utility:

type OptionalUser = {
    email?: string;
    first_name?: string;
    last_name?: string;
    username: string;
}

type RequiredUser = Required<OptionalUser>

Readonly:

When working with React, the props passed to a component shouldn’t be modified within the component to enforce immutability. TypeScript provides the readonly modifier to prevent reassignment of props, supporting this best practice. React props should be read-only.

import React from 'react';
// Define the props interface with readonly
interface UserCardProps {
  readonly name: string;
  readonly age: number;
}const UserCard: React.FC<UserCardProps> = ({ name, age }) => {
  // Attempting to modify name or age will cause a TypeScript error
  // name = "New Name"; // Error: Cannot assign to 'name' because it is a read-only property.  return (
    <div>
      <h2>{name}</h2>
      <p>Age: {age}</p>
    </div>
  );
};export default UserCard;

Record:

The Record utility is a powerful tool to create objects with specific key-value pairs, ensuring that all keys are present and that each key's value matches a defined type. Let's consider a real-world scenario where using the Record utility type would be beneficial. Imagine you are developing an admin dashboard for a web application where users have different roles, such as admin, editor, and viewer. Each role has specific permissions associated with it, such as the ability to create, read, update, or delete data. You can use the Record type to define and manage these roles and their permissions in a type-safe way.

Define User Roles and Permissions:

// Define possible roles
type UserRole = 'admin' | 'editor' | 'viewer';

// Define possible permissions
type Permission = 'create' | 'read' | 'update' | 'delete';
// Use Record to map roles to their permissions
const rolePermissions: Record<UserRole, Permission[]> = {
  admin: ['create', 'read', 'update', 'delete'],
  editor: ['create', 'read', 'update'],
  viewer: ['read'],
};

Creating a Function to Check Permissions:

function hasPermission(role: UserRole, permission: Permission): boolean {
  const permissions = rolePermissions[role];
  return permissions.includes(permission);
}

Using the Function in a Component:

import React from 'react';
type UserProps = {
  role: UserRole;
};
const Dashboard: React.FC<UserProps> = ({ role }) => {
  return (
    <div>
      <h1>Dashboard</h1>
      {hasPermission(role, 'create') && (
        <button>Create New Item</button>
      )}
      {hasPermission(role, 'read') && (
        <div>Here are the items you can view.</div>
      )}
      {hasPermission(role, 'update') && (
        <button>Update Item</button>
      )}
      {hasPermission(role, 'delete') && (
        <button>Delete Item</button>
      )}
    </div>
  );
};
export default Dashboard;

Example Usage of the Dashboard Component:

import React from 'react';
import Dashboard from './Dashboard';

const App: React.FC = () => {
  return (
    <div>
      <h1>Admin View</h1>
      <Dashboard role="admin" />
      <h1>Editor View</h1>
      <Dashboard role="editor" />
      <h1>Viewer View</h1>
      <Dashboard role="viewer" />
    </div>
  );
};
export default App;

NonNullable:

Let’s consider a scenario where you have a form for managing user profiles. This form can be used to create a new user or edit an existing one. We’ll use TypeScript to handle these scenarios safely, ensuring that certain fields are non-nullable when the form is submitted.

Defining the User Data Type:

interface User {
  id?: number; // Optional during creation, required during editing
  username: string;
  email: string;
  age?: number;
}

Form State Type:

type UserFormState = {
  id?: number;
  username: string | undefined;
  email: string | undefined;
  age?: number | undefined;
};

This type allows fields like username and email to be undefined initially, especially when editing.

Using NonNullable to Ensure Non-Nullable Fields

When submitting the form, you want to make sure that username and email are always defined:

type ValidUser = Omit<User, 'id'> & {
  id?: number;
  username: NonNullable<UserFormState['username']>;
  email: NonNullable<UserFormState['email']>;
};

Here, ValidUser ensures that username and email are non-nullable, making sure

these fields are always present when processing the form submission.

Form Component Implementation:

import React, { useState } from 'react';

const UserForm: React.FC<{ initialData?: User }> = ({ initialData }) => {
  // Initialize form state with optional initial data
  const [formState, setFormState] = useState<UserFormState>({
    id: initialData?.id,
    username: initialData?.username,
    email: initialData?.email,
    age: initialData?.age,
  });
  const handleChange = (event: React.ChangeEvent<HTMLInputElement>) => {
    const { name, value } = event.target;
    setFormState((prevState) => ({ ...prevState, [name]: value }));
  };
  const handleSubmit = () => {
    // Assert that username and email are non-nullable
    const { id, username, email, age } = formState;
    if (!username || !email) {
      alert('Username and email are required.');
      return;
    }
    const validUser: ValidUser = {
      id,
      username,
      email,
      age,
    };
    // Proceed with form submission logic
    console.log('Submitting form:', validUser);
  };
  return (
    <form onSubmit={(e) => e.preventDefault()}>
      <div>
        <label>
          Username:
          <input
            type="text"
            name="username"
            value={formState.username || ''}
            onChange={handleChange}
            required
          />
        </label>
      </div>
      <div>
        <label>
          Email:
          <input
            type="email"
            name="email"
            value={formState.email || ''}
            onChange={handleChange}
            required
          />
        </label>
      </div>
      <div>
        <label>
          Age:
          <input
            type="number"
            name="age"
            value={formState.age || ''}
            onChange={handleChange}
          />
        </label>
      </div>
      <button type="submit" onClick={handleSubmit}>
        Submit
      </button>
    </form>
  );
};
export default UserForm;

For Functions:

TypeScript gives us many utilities to work with functions, allowing us to infer types and avoid duplicating type definitions. Let’s dive into an example:

type User = {
  email: string;
  first_name: string;
  last_name: string;
  username: string;
}

function createUser(args: User) {
    // ....
    return {
        id: 12,
        email: args.email,
        username: args.username
    }
}

How can we infer the return type of this function?

We have two methods to get the return type of this function:

type returnTypeOfCreateUser = Omit<User, 'last_name' | 'first_name'>

This approach works, but it doesn’t offer the flexibility or consistency needed if the return type of the function changes. To solve this, we can use ReturnType to directly infer the type:

type returnTypeOfCreateUser2 = ReturnType<typeof createUser>

What about async functions?

async function createUser2(args: User) {
    // ....
    return {
        id: 12,
        email: args.email,
        username: args.username
    }
}

The answer is yes! You can combine Awaited with ReturnType to handle async functions:

type returnTypeOfCreateUser3 = Awaited<ReturnType<typeof createUser2>>

What if I want to get the type of parameters that a function from an external library accepts?

Imagine you’re using a third-party library, and you want to wrap one of its functions. You can use the Parameters utility to get the types of its parameters:

type paramsType = Parameters<typeof createUser> // type paramsType = [args: User]

The Parameters utility returns an array of the parameter types that createUser accepts!

Conclusion

TypeScript’s utility types like ReturnType, Parameters, Partial, Required, Omit, Pick, Readonly, Record, and NonNullable make it easier to write clean, maintainable, and type-safe React code. By using these utilities, you can handle real-world scenarios effectively, reduce errors, and enhance the overall quality of your projects. Start leveraging these powerful features to take your React development to the next level. For more detailed information and advanced use cases, check out additional resources like the TypeScript Handbook and the React Documentation.

Prerequisites:

• Familiar with basic TypeScript types

• Familiar with React.js

• Reading the previous article

Naming Conventions:

• use PascalCase for class, component and Enum names.

• use camelCase for variable and function names.

• do not use I as prefix of the interface instead use ComponentNameProps or FunctionNameParams.

• use .generated.* as suffix for the files are generated and you don't edit them.

interface ComponentNameProps {
  position: 'left' | 'right'
}
function ComponentName({ position }: ComponentNameProps) {
  if (position === 'left') {
    return <div>left</div>
  }
  return <div>right</div>
}

interface FunctionNameParams {
  args: string[]
}
function functionName({ args }: FunctionNameParams) {
  return args.join(' ')
}

Types:

• put the shared types in types.ts file.

• use generics to avoid duplicating the components/functions.

• do not export functions/types that not shared across multi-components.

• in your component file, the type definitions must comes the first.

• use Utility Types to avoid duplicating of the type definitions.

• use readonly to define the data coming from your API

Components:

• don’t use FunctionComponent<T> or FC<T> to define your component, because it's explicit about the return type, while the normal function version is implicit, read more about this codemod-replace-react-fc-typescript.

• use ReactNode instead JSX.Element to define your children when use the normal functions, because JSX.Element is the return value of React.createElement, while ReactNode is return value of a component

• use generic components to make your component more flexible, read more about this topic.

• use the React.ComponentPropsWithoutRef<T> as Wrapping/Mirroring a HTML Element when you want to make component that takes all the normal props of this Element.read more about this topic

// bad
interface MyCustomLinkProps {
  href: string
  children?: React.ReactNode
}
function MyCustomLink(props: MyCustomLinkProps) {
  const { children, href } = props
  return <a href={href}>{children}</a>
}
// most recommended
function MyCustomLink(props: React.ComponentPropsWithoutRef<'a'>) {
  return <a {...props}>{children}</a>
}

• use Fragment or use the shorthand <> instead div in wrapping the component.

// bad
function ComponentName() {
  return (
    <div>
      <section></section>
      <section></section>
    </div>
  )
}

// most recommended
function ComponentName() {
  return (
    <>
      <section></section>
      <section></section>
    </>
  )
}

Forms and Events:

• inline event handler:

const InputComponent = () => (
  <input
    // TypeScript automatically inffers it
    onChange={(e) => {
      // logic here
    }}
  />
)

• separated event handler:

const InputComponent = () => {
  const onChnageInputHandler = (e: React.FormEvent<HTMLInputElement>): void => {
    // your logic here
  }
  return <input onChange={onChnageInputHandler} />
}

or:

const InputComponent = () => {
  const onChnageInputHandler: React.ChangeEventHandler<HTMLInputElement> = (
    e
  ) => {
    // your logic here
  }
  return <input onChange={onChnageInputHandler} />
}

• onSubmit definition for uncontrolled form component

const Form = () => (
  <form
    onSubmit={(e: React.SyntheticEvent) => {
      e.preventDefault()
      const target = e.target as typeof e.target & {
        email: { value: string }
        password: { value: string }
      }
      const email = target.email.value // typechecks!
      const password = target.password.value // typechecks!
      // etc...
    }}
  >
    <label>
      Email:
      <input type="email" name="email" />
    </label>
    <label>
      Password:
      <input type="password" name="password" />
    </label>
    <button type="submit">Login</button>
  </form>
)

you can use formik or any other library for handling Forms, those libraries are built on the principles of controlled components

Hooks:

• useState hook :

const Component = () => {
  //1- inferred type:
  // `state` is inferred to be a number
  const [state, setState] = useState(0)
  // `stringState` is inferred to be a string
  const [stringState, setStringState] = useState('')
  //2- implicit type:
  const [state1, setState2] = useState<number | undefined>()
  return <></>
}

• useCallback hook :

//   it's just like any other function
interface MemoizedFunctionParams {
params:string[]
}
const memoizedFunction = useCallback(
  (args:MemoizedFunctionParams) => {
    return 'text'
  },
  [...],
);

• useReducer hook:

import { useReducer } from 'react'

const initialState = { count: 0 }
type ACTIONTYPE =
  | { type: 'increment'; payload: number }
  | { type: 'decrement'; payload: string }
function reducer(state: typeof initialState, action: ACTIONTYPE) {
  switch (action.type) {
    case 'increment':
      return { count: state.count + action.payload }
    case 'decrement':
      return { count: state.count - Number(action.payload) }
    default:
      throw new Error()
  }
}
function Counter() {
  // If you don't define return type, TypeScript automatically infers it.
  const [state, dispatch] = useReducer(reducer, initialState)
  return (
    <>
      Count: {state.count}
      <button onClick={() => dispatch({ type: 'decrement', payload: '5' })}>
        -
      </button>
      <button onClick={() => dispatch({ type: 'increment', payload: 5 })}>
        +
      </button>
    </>
  )
}

• useRef hook :

import { useRef, useEffect } from 'react'
// This is just an example, React recommended you to use Controlled components
function Component() {
  const inputRef = useRef<HTMLInputElement>(null)
  const divRef = useRef<HTMLDivElement>(null)
  useEffect(() => {
      if (!inputRef) {
        throw Error('input not mounted !!!!')
      }
      inputRef.current.value = 'assign value'
    }, [])
    const onChnageButtonHandler = () => {
      divRef.current.innerHTML = 'we change this text here'
    }
  return (
    <div>
      <input ref={inputRef} />
      <div ref={divRef}>this is div content</div>
      <button onClick={onChnageButtonHandler}>change the content</button>
    </div>
  )
}

Context:

• with default value:

import { createContext, useState, useContext } from 'react'

type ThemeContextType = 'light' | 'dark'
const ThemeContext = createContext<ThemeContextType>('light')
const App = () => {
  const [theme, setTheme] = useState<ThemeContextType>('light')
  return (
    <ThemeContext.Provider value={theme}>
      <MyComponent />
    </ThemeContext.Provider>
  )
}
const MyComponent = () => {
  const theme = useContext(ThemeContext)
  return <p>The current theme is {theme}.</p>
}

• without default value:

import { createContext, useState, useContext } from 'react'

type userContextType = { name: string; email: string }
const UserContext = createContext<userContextType>()
const App = () => {
  const [user, setUser] = useState<userContextType>({
    name: 'name',
    email: 'email@mail.com',
  })
  return (
    <ThemeContext.Provider value={...{ user, setUser }}>
      <MyComponent />
    </ThemeContext.Provider>
  )
}
const MyComponent = () => {
  const { user } = useContext(UserContext)
  return <p>The current theme is {user?.name}.</p>
}

Conclusion:

In conclusion, using TypeScript with React can write safer, more maintainable code, and catch errors earlier in the development process. Additionally, TypeScript’s static typing can help improve developer productivity by providing better tooling and documentation.

when you adopt TypeScript to React projects, you don’t need to add additional packages to validate props like prop-types, also you can catching types errors in compile-time rather than runtime, and getting IntelliSense to your IDE, which can help you to write code quickly and correctly.

The freedom of JavaScript can be painful when you work in a team, when you don’t write tests for your application, and when the application grows.

Imagine you have a component that accepts position as a prop, this prop will be left or right to work well, with JavaScript you need to add a manual check

//components/MyComponent.jsx
function MyComponent({ position = "left" }) {
  if (position === "left") {
    return <div>left</div>;
  }
  if (position === "right") {
    return <div>right</div>;
  }
  return <div>position will be right or left</div>;
}

//App.js
import MyComponent from "./components/MyComponent";

function App() {
  return (
    <div className="App">
      <MyComponent position="fddffd" />
    </div>
  );
}
export default App;

you can use the prop-types to validate the props but it is still painful :

//components/MyComponent.jsx
import React from "react";
import PropTypes from "prop-types";

function MyComponent({ position = "left" }) {
  if (position === "left") {
    return <div>left</div>;
  }
  if (position === "right") {
    return <div>right</div>;
  }
  return <div>position will be right or left</div>;
}
MyComponent.propTypes = {
  position: PropTypes.oneOf(["right", "left"]),
};

//App.js
function App() {
  return (
    <div className="App">
      <MyComponent position="fddffd" />
    </div>
  );
}
export default App;

No warning or alert again 🥲:

To make sure is props are valid you must open the console to show up the errors and warnings:

But when we use TypeScript you will get alerts and warnings anywhere :

//components/MyComponent.tsx
interface MyComponentProps {
  position: "right" | "left";
}
function MyComponent({ position }: MyComponentProps) {
  return <div>{position}</div>;
}
export default MyComponent;

Your IDE tells you stop you have error 🛑:

Also your browser gives you alerts to correct your code

Conclusion:

TypeScript is a powerful tool that helps you to become a productive developer and to write clean and readable code, it’s not just a props validator, we can do with it a lot of things like alias, creating solid and re-usable components with generics