What is Polymorphism?

The word polymorphism is derived from Greek, and means "having multiple forms":

• Poly = many

• Morph = forms

In programming, polymorphism is the ability of an object to take many forms.

The key advantage of polymorphism is that it allows us to write more generic and reusable code. Instead of writing separate logic for different classes, we define common behaviours in a parent class and let child classes override them as needed. This eliminates the need for excessive if-else checks, making the code more maintainable and extensible.

MVC frameworks like Django use polymorphism to make code more flexible. For example, Django supports different databases like SQLite, MySQL, and PostgreSQL. Normally, each database requires different code to interact with it, but Django provides a single database API that works with all of them. This means you can write the same code for database operations, no matter which database you use. So, if you start a project with SQLite and later switch to PostgreSQL, you won’t need to rewrite much of your code, thanks to polymorphism.

In this article, to make things easy to understand, I’ll show you a bad code example with no polymorphism. We’ll discuss the issues that this bad code causes, and then solve the issues by refactoring the code to use polymorphism.

(Btw, if you learn better by video, checkout my Polymorphism in Python YouTube video.)

First, an example with no polymorphism:

class Car:
    def __init__(self, brand, model, year, number_of_doors):
        self.brand = brand
        self.model = model
        self.year = year
        self.number_of_doors = number_of_doors

    def start(self):
        print("Car is starting.")

    def stop(self):
        print("Car is stopping.")

class Motorcycle:
    def __init__(self, brand, model, year):
        self.brand = brand
        self.model = model
        self.year = year

    def start_bike(self):
        print("Motorcycle is starting.")

    def stop_bike(self):
        print("Motorcycle is stopping.")

Let’s say that we want to create a list of vehicles, then loop through it and perform an inspection on each vehicle:

# Create list of vehicles to inspect
vehicles = [
    Car("Ford", "Focus", 2008, 5),
    Motorcycle("Honda", "Scoopy", 2018),
]

# Loop through list of vehicles and inspect them
for vehicle in vehicles:
    if isinstance(vehicle, Car):
        print(f"Inspecting {vehicle.brand} {vehicle.model} ({type(vehicle).__name__})")
        vehicle.start()
        vehicle.stop()
    elif isinstance(vehicle, Motorcycle):
        print(f"Inspecting {vehicle.brand} {vehicle.model} ({type(vehicle).__name__})")
        vehicle.start_bike()
        vehicle.stop_bike()
    else:
        raise Exception("Object is not a valid vehicle")

Notice the ugly code inside the for loop! Because vehicles is a list of any type of object, we have to figure out what type of object we are dealing with inside each loop before we can access any information on the object.

This code will continue to get uglier as we add more vehicle types. For example, if we extended our codebase to include a new Plane class, then we’d need to modify (and potentially break) existing code – we’d have to add another conditional check in the for loop for planes.

Introducing: Polymorphism…

Cars and motorcycles are both vehicles. They both share some common properties and methods. So, let’s create a parent class that contains these shared properties and methods:

Parent class (or "superclass"):

class Vehicle:
    def __init__(self, brand, model, year):
        self.brand = brand
        self.model = model
        self.year = year

    def start(self):
        print("Vehicle is starting.")

    def stop(self):
        print("Vehicle is stopping.")

Car and Motorcycle can now inherit from Vehicle. Let’s create the child classes (or "subclasses") of the Vehicle superclass:

class Car(Vehicle):
    def __init__(self, brand, model, year, number_of_doors):
        super().__init__(brand, model, year)
        self.number_of_doors = number_of_doors

    # Below, we "override" the start and stop methods, inherited from Vehicle, to provide car-specific behaviour

    def start(self):
        print("Car is starting.")

    def stop(self):
        print("Car is stopping.")

class Motorcycle(Vehicle):
    def __init__(self, brand, model, year):
        super().__init__(brand, model, year)

    # Below, we "override" the start and stop methods, inherited from Vehicle, to provide bike-specific behaviour

    def start(self):
        print("Motorcycle is starting.")

    def stop(self):
        print("Motorcycle is stopping.")

Car and Motorcycle both extend Vehicle, as they are vehicles. But what’s the point in Car and Motorcycle both extending Vehicle if they are going to implement their own versions of the start() and stop() methods? Look at the code below:

# Create list of vehicles to inspect
vehicles = [Car("Ford", "Focus", 2008, 5), Motorcycle("Honda", "Scoopy", 2018)]

# Loop through list of vehicles and inspect them
for vehicle in vehicles:
    if isinstance(vehicle, Vehicle):
        print(f"Inspecting {vehicle.brand} {vehicle.model} ({type(vehicle).__name__})")
        vehicle.start()
        vehicle.stop()
    else:
        raise Exception("Object is not a valid vehicle")

In this example:

• We have a list, vehicles, containing instances of both Car and Motorcycle.

• We iterate through each vehicle in the list and perform a general inspection on each one.

• The inspection process involves starting the vehicle, checking its brand and model, and stopping it afterwards.

• Despite the vehicles being of different types, polymorphism allows us to treat them all as instances of the base Vehicle class. The specific implementations of the start() and stop() methods for each vehicle type are invoked dynamically at runtime, based on the actual type of each vehicle.

Because the list can only contain objects that extend the Vehicle class, we know that every object will share some common fields and methods. This means that we can safely call them, without having to worry about whether each specific vehicle has these fields or methods.

This demonstrates how polymorphism enables code to be written in a more generic and flexible manner, allowing for easy extension and maintenance as new types of vehicles are added to the system.

For example, if we wanted to add another vehicle to the list, we don’t have to modify the code used to inspect vehicles (“the client code”). Instead, we can just extend our code base (that is, create a new class), without modifying existing code:

class Plane(Vehicle):
    def __init__(self, brand, model, year, number_of_doors):
        super().__init__(brand, model, year)
        self.number_of_doors = number_of_doors

    def start(self):
        print("Plane is starting.")

    def stop(self):
        print("Plane is stopping.")

# Create list of vehicles to inspect
vehicles = [
    Car("Ford", "Focus", 2008, 5),
    Motorcycle("Honda", "Scoopy", 2018),

    ########## ADD A PLANE TO THE LIST: #########

    Plane("Boeing", "747", 2015, 16),

    ############################################
]

The code to perform the vehicle inspections doesn’t have to change to account for a plane. Everything still works, without having to modify our inspection logic.

Conclusion

Polymorphism allows clients to treat different types of objects in the same way. This greatly improves the flexibility of software and maintainability of software, as new classes can be created without you having to modify (often by adding extra if/else if blocks) existing working and tested code.

Further Learning

Polymorphism is related to many other object-oriented programming principles, such as dependency injection and the open-closed SOLID principle. If you’d like to master OOP, then check out my Udemy course:

• Python OOP: Object Oriented Programming From Beginner to Pro 🎥

If you prefer book to video, check out my books:

• Amazon Kindle and paperback 📖

• Gumroad PDF 📖

Thanks for reading :)

The SOLID Principles were introduced by a software engineer named Robert C. Martin (also known as "Uncle Bob") in the early 2000s. Uncle Bob’s goal was to promote good software design practices, particularly in object-oriented programming (OOP), by addressing common problems developers face as software systems grow in size and complexity.

Here are the five SOLID principles:

• S: Single Responsibility Principle (SRP)

• O: Open-closed Principle (OCP)

• L: Liskov Substitution Principle (LSP)

• I: Interface Segregation Principle (ISP)

• D: Dependency Inversion Principle (DIP)

By following these principles, you can create software designs that are easier to understand, maintain, and extend, leading to higher-quality software that is more robust and adaptable to change.

In this article, to demonstrate each principle, I’ll first show you a bad code example in C# that violates the principle. We will then discuss the issues this bad code causes, and then solve those issues by refactoring the code to satisfy the principle.

First up we have the…

Single Responsibility Principle (SRP) in C

A class should have only one reason to change, meaning that it should have only one responsibility or purpose.

This principle encourages you to create classes that are more focussed and perform one single well-defined task, rather than multiple tasks. Breaking up classes into smaller, more focused units makes code easier to understand, maintain, and test.

An example that violates the SRP:

public class User
{
 public string Username { get; set; }
 public string Email { get; set; }

 public void Register()
 {
   // Register user logic, e.g. save to database...

   // Send email notification
   EmailSender emailSender = new EmailSender();
   emailSender.SendEmail("Welcome to our platform!", Email);
 }
}

public class EmailSender
{
 public void SendEmail(string message, string recipient)
 {
   // Email sending logic
   Console.WriteLine($"Sending email to {recipient}: {message}");
 }
}

In this example, the User class manages user data (username and email), and contains logic for registering a user. This violates the SRP because the class has more than one reason to change. It could change due to:

• Modifications in user data management – for example adding more fields, such as firstName, gender, hobbies.

• Modifications to the logic of registering a user, for example we may choose to fetch a user from the database by their username rather than their email.

To adhere to the Single Responsibility Principle, we should separate these responsibilities into separate classes.

Refactoring the code to satisfy the SRP:

public class User
{
 public string Username { get; set; }
 public string Email { get; set; }
}

public class EmailSender
{
 public void SendEmail(string message, string recipient)
 {
   // Email sending logic
   Console.WriteLine($"Sending email to {recipient}: {message}");
 }
}

public class UserService
{
 public void RegisterUser(User user)
 {
   // Register user logic...

   EmailSender emailSender = new EmailSender();
   emailSender.SendEmail("Welcome to our platform!", user.Email);
 }
}

In the refactored code, the User class is responsible solely for representing user data. The UserService class now handles user registration, separating concerns related to user data management from user registration logic. The UserService class is responsible only for the business logic of registering a user.

This separation of responsibilities adheres to the Single Responsibility Principle, making the code easier to understand, maintain, and extend.

Open/Closed Principle (OCP) in C

Software entities (classes, modules, functions, etc.) should be open for extension but closed for modification.

This principle promotes the idea that existing code should be able to be extended with new functionality without modifying its source code. It encourages the use of abstraction and polymorphism to achieve this goal, allowing for code to be easily extended through inheritance or composition.

(By the way, if you don’t understand these fundamental OOP concepts, such as abstraction, polymorphism, inheritance and composition — then check out my book, Mastering Design Patterns in C#: A Beginner-Friendly Guide, Including OOP and SOLID Principles on Amazon or Gumroad.)

Let's consider an example of a Shape class hierarchy that calculates the area of different geometric shapes. Initially, this violates the Open/Closed Principle because adding a new shape requires modifying the existing code:

public enum ShapeType
{
 Circle,
 Rectangle
}

public class Shape
{
 public ShapeType Type { get; set; }
 public double Radius { get; set; }
 public double Length { get; set; }
 public double Width { get; set; }

 public double CalculateArea()
 {
   switch (Type)
   {
     case ShapeType.Circle:
       return Math.PI * Math.Pow(Radius, 2);
     case ShapeType.Rectangle:
       return Length * Width;
     default:
       throw new InvalidOperationException("Unsupported shape type.");
   }
 }
}

In this example, the Shape class has a method, CalculateArea(), that calculates the area based on the type of shape. Adding a new shape, such as a triangle, would require modifying the existing Shape class, violating the OCP.

To adhere to the Open/Closed Principle, we should design the system in a way that allows for extension without modification. Let's refactor the code using inheritance and polymorphism:

public abstract class Shape
{
 public abstract double CalculateArea();
}

public class Circle : Shape
{
 public double Radius { get; set; }

 public override double CalculateArea()
 {
   return Math.PI * Math.Pow(Radius, 2);
 }
}

public class Rectangle : Shape
{
 public double Length { get; set; }
 public double Width { get; set; }

 public override double CalculateArea()
 {
   return Length * Width;
 }
}

In this refactored code, we define an abstract Shape class with an abstract CalculateArea() method. Concrete shape classes (Circle and Rectangle) inherit from the Shape class and provide their own implementations of CalculateArea().

Adding a new shape, such as a triangle, would involve creating a new class – extending the codebase – that inherits from Shape and implements CalculateArea(), without modifying existing code. This adheres to the OCP by allowing for extension without modification.

Being able to add functionality without modifying existing code means that we don’t have to worry as much about breaking existing working code and introducing bugs.

Following the OCP encourages us to design our software so that we add new features only by adding new code. This helps us to build loosely-coupled, maintainable software.

Liskov Substitution Principle (LSP) in C

Objects of a superclass should be replaceable with objects of its subclass without affecting the correctness of the program.

This principle ensures that inheritance hierarchies are well-designed and that subclasses adhere to the contracts defined by their superclasses.

Violations of the LSP can lead to unexpected behavior or errors when substituting objects, making code harder to reason about and maintain.

Let's consider an example involving a Rectangle class and a Square class, which inherit from a common Shape class. Initially, we'll violate the LSP by not adhering to the behavior expected from these classes. Then, we'll fix it to ensure that the principle is respected.

public abstract class Shape
{
 public abstract double Area { get; }
}

public class Rectangle : Shape
{
 public virtual double Width { get; set; }

 public virtual double Height { get; set; }

 public override double Area => Width * Height;
}

public class Square : Rectangle
{
 public override double Width
 {
   get => base.Width;
   set => base.Width = base.Height = value;
 }

 public override double Height
 {
   get => base.Height;
   set => base.Height = base.Width = value;
 }
}

Now, let’s test out if Rectangle calculates its area correctly:

// Program.cs

var rect = new Rectangle();
rect.Height = 10;
rect.Width = 5;

System.Console.WriteLine("Expected area = 10 * 5 = 50.");

System.Console.WriteLine("Calculated area = " + rect.Area);

Running the program:

Expected area = 10 * 5 = 50.

Calculated area = 50

Perfect!

Now, in our program, the Square class inherits from, or extends, the Rectangle class, because, mathematically, a square is just a special type of rectangle, where its height equals its width. Because of this, we decided that Square should extend Rectangle – it’s like saying “a square is a (special type of) rectangle”.

But look what happens if we substitute the Rectangle class for the Square class:

var rect = new Square();
rect.Height = 10;
rect.Width = 5;

System.Console.WriteLine("Expected area = 10 * 5 = 50.");

System.Console.WriteLine("Calculated area = " + rect.Area);

Expected area = 10 * 5 = 50.

Calculated area = 25

Oh dear, LSP has been violated: we replaced the object of a superclass (Rectangle) with an object of its subclass (Square), and it affected the correctness of our program. By modeling Square as a subclass of Rectangle, and allowing width and height to be independently set, we violate the LSP. When setting the width and height of a Square, it should retain its squareness, but our implementation allows for inconsistency.

Let’s fix this to satisfy LSP:

public abstract class Shape
{
 public abstract double Area { get; }
}

public class Rectangle : Shape
{
 public double Width { get; set; }

 public double Height { get; set; }

 public override double Area => Width * Height;
}

public class Square : Shape
{
 private double sideLength;

 public double SideLength
 {
   get => sideLength;
   set
   {
     sideLength = value;
   }
 }

 public override double Area => sideLength * sideLength;
}

// Program.cs

Shape rectangle = new Rectangle { Width = 5, Height = 4 };

Console.WriteLine($"Area of the rectangle: {rectangle.Area}");

Shape square = new Square { SideLength = 5 };

Console.WriteLine($"Area of the square: {square.Area}");

In this corrected example, we redesign the Square class to directly set the side length. Now, a Square is correctly modeled as a subclass of Shape, and it adheres to the Liskov Substitution Principle.

How does this satisfy LSP? Well, we have a superclass, Shape, and subclasses Rectangle and Square. Both Rectangle and Square maintain the correct expected behavior of a Shape — we can substitute a square for a rectangle and the area will still be calculated correctly.

Interface Segregation Principle (ISP) in C

Clients should not be forced to depend on interfaces they do not use.

This principle encourages the creation of fine-grained interfaces that contain only the methods required by the clients that use them. It helps to prevent the creation of "fat" interfaces that force clients to implement unnecessary methods, leading to cleaner and more maintainable code.

Let's consider an example involving 2D and 3D shapes, initially violating the ISP.

Violating ISP:

public interface IShape
{
 double Area();
 double Volume(); // problem: 2D shapes don't have volume!
}

public class Circle : IShape
{
 public double Radius { get; set; }

 public double Area()
 {
   return Math.PI * Math.Pow(Radius, 2);
 }

 public double Volume()
 {
   throw new InvalidOperationException("Volume not applicable for 2D shapes.");
 }
}

public class Sphere : IShape
{
 public double Radius { get; set; }

 public double Area()
 {
   return 4 * Math.PI * Math.Pow(Radius, 2);
 }

 public double Volume()
 {
   return (4.0 / 3.0) * Math.PI * Math.Pow(Radius, 3);
 }
}

In this example, we have an IShape interface representing both 2D and 3D shapes. However, the Volume() method is problematic for 2D shapes, like Circle and Rectangle, because they don't have volume. This violates the ISP because clients (classes using the IShape interface) may be forced to depend on methods they do not need.

var circle = new Circle();
circle.Radius = 10;

System.Console.WriteLine(circle.Area());
System.Console.WriteLine(circle.Volume()); // My text editor doesn't flag a problem...

var sphere = new Sphere();
sphere.Radius = 10;

System.Console.WriteLine(sphere.Area());
System.Console.WriteLine(sphere.Volume());

Usually, if I try to call a method on an object that doesn’t exist, VS Code will tell me that I’m making a mistake. But above, when I call circle.Volume(), VS code is like “no problem”. And VS code is correct, because the IShape interface forces Circle to implement a Volume() method, even though circles don’t have volume.

It’s easy to see how violating ISP can introduce bugs into a program – above, everything looks fine, until we run the program and an exception gets thrown.

Fixing ISP

public interface IShape2D
{
 double Area();
}

public interface IShape3D
{
 double Area();
 double Volume();
}

public class Circle : IShape2D
{
 public double Radius { get; set; }

 public double Area()
 {
   return Math.PI * Math.Pow(Radius, 2);
 }
}

public class Sphere : IShape3D
{
 public double Radius { get; set; }

 public double Area()
 {
   return 4 * Math.PI * Math.Pow(Radius, 2);
 }

 public double Volume()
 {
   return (4.0 / 3.0) * Math.PI * Math.Pow(Radius, 3);
 }
}

In the fixed example, we've segregated the IShape interface into two smaller, more focused interfaces: IShape2D and IShape3D. Each shape class now implements only the interface that is relevant to its functionality.

This adheres to the Interface Segregation Principle by ensuring that clients are not forced to depend on methods that they do not use. Clients can now depend only on the interfaces that they need, promoting better code reuse and flexibility.

Next up, the fifth and final SOLID principle…

Dependency Inversion Principle (DIP) in C

High-level modules should not depend on low-level modules. Both should depend on abstractions.

Dependency Inversion is the strategy of depending upon interfaces or abstract classes rather than upon concrete classes. This principle promotes decoupling between modules and promotes the use of interfaces or abstract classes to define dependencies, allowing for more flexible and testable code.

Let's start with an example violating the DIP and then we’ll correct it.

public class Engine // Engine is our "low-level" module
{
 public void Start()
 {
   System.Console.WriteLine("Engine started.");
 }
}

public class Car // Car is our "high-level" module
{
 private Engine engine;

 public Car()
 {
   this.engine = new Engine(); // Direct dependency on concrete Engine class
 }

 public void StartCar()
 {
   engine.Start();
   System.Console.WriteLine("Car started.");
 }
}

In this example:

• The Car class directly creates an instance of the Engine class, leading to a tight coupling between Car and Engine.

• If the Engine class changes, it may affect the Car class, violating the Dependency Inversion Principle.

The UML diagram below shows that Car depends on Engine:

But what do we mean by “high level” and “low level” classes?

High-Level Class: The high-level class is typically the one that represents the main functionality or business logic of the application. It orchestrates the interaction between various components and is often more abstract in nature.

In this example, the Car class can be considered the high-level class. It represents the main functionality related to starting the car and driving it. The Car class is concerned with the overall behavior of the car, such as controlling its movement.

Low-Level Class: The low-level class is usually one that provides specific functionality or services that are used by the high-level class. It typically deals with implementation details and is more concrete in nature.

In this example, the Engine class can be considered the low-level class. It provides the specific functionality related to starting the engine. The Engine class encapsulates the details of how the engine operates, such as ignition and combustion.

So in summary, the Car class is the high-level class, representing the main functionality of the application related to the car's behavior.

The Engine class is the low-level class, providing specific functionality related to the operation of the engine, which is used by the Car class.

Fixing DIP:

To adhere to the Dependency Inversion Principle, we introduce an abstraction (interface) between Car and Engine, allowing Car to depend on an abstraction instead of a concrete implementation.

public interface IEngine
{
 void Start();
}

public class Engine : IEngine
{
 public void Start()
 {
   System.Console.WriteLine("Engine started.");
 }
}

public class Car
{
 private IEngine engine;

 public Car(IEngine engine)
 {
   this.engine = engine;
 }

 public void StartCar()
 {
   engine.Start();
   System.Console.WriteLine("Car started.");
 }
}

We can now inject any type of engine into Car implementations:

var engine = new Engine(); // concrete implementation to be "injected" into the car

var car = new Car(engine);

car.StartCar();

From the UML diagram below, we can see that both objects now depend on the abstraction level of the interface. Engine has inverted its dependency on Car.

In this corrected example:

1. We define an interface IEngine representing the behavior of an engine.

2. The Engine class implements the IEngine interface.

3. The Car class now depends on the IEngine interface instead of the concrete Engine class.

4. Dependency injection is used to inject the IEngine implementation into the Car class, promoting loose coupling. Now, if we want to give a car a different type of engine, for example a FastEngine, we can inject that in instead.

5. Now, if the implementation of the engine changes, it won't affect the Car class as long as it adheres to the IEngine interface.

Dependency Injection (DI) offers several advantages in software development:

• Decoupling: DI promotes loose coupling between components by removing direct dependencies. Components rely on abstractions rather than concrete implementations, making them more independent and easier to maintain.

• Testability: Dependency injection simplifies unit testing by allowing components to be easily replaced with mock or stub implementations during testing. This enables isolated testing of individual components without relying on their dependencies.

• Flexibility: DI provides flexibility in configuring and swapping dependencies at runtime. It allows different implementations of dependencies to be used interchangeably without modifying the client code, facilitating runtime customization and extensibility.

• Readability and Maintainability: By explicitly specifying dependencies in the constructor or method parameters, DI improves code readability and makes the codebase easier to understand. It also reduces the risk of hidden dependencies, leading to more maintainable and understandable code.

• Reusability: DI promotes component reusability by decoupling them from their specific contexts or environments. Components can be designed to be independent of the application framework or platform, making them more portable and reusable in different projects or scenarios.

• Scalability: DI simplifies the management of dependencies in large-scale applications by providing a standardised approach for dependency resolution. It helps prevent dependency hell and makes it easier to manage and scale complex systems.

Overall, dependency injection enhances modularity, testability, and maintainability of software systems, contributing to improved software quality and developer productivity.

Conclusion

Congratulations – you now understand the extremely important SOLID principles. These principles are going to save you a lot of headaches during your software development career, and guide you towards creating beautiful, maintainable, flexible, testable software.

If you’d like to take your software development skills to the next level and learn:

• OOP principles: encapsulation, abstraction, inheritance, polymorphism, coupling, composition, composition vs inheritance, fragile base class problem.

• All 23 design patterns (“The Gang of Four Design Patterns”) with real world examples.

• Unified Modeling Language (UML): the standard way to model classes and the relationships between them.

Then check out my book:

Mastering Design Patterns in C#: A Beginner-Friendly Guide, Including OOP and SOLID Principles on Amazon (also available on Gumroad).

Hopefully this article helps you to become a better OOP software developer!

Thanks for reading,

Danny 😎

Also, some props (for example, the current authenticated user, UI theme, or preferred language) will be required by many components within an application.

React's Context API provides a way to share values like these between components without having to explicitly pass them down as a prop through every level of the tree. So, Context is designed to share data that can be considered "global" for a tree of React components.

What You'll Learn in This Article

• What is the React Context API and when should you use it?
• React Context API example: how to switch between light and dark mode UI themes
• How to create multiple React Contexts (and why you should)
• How to prevent the React Context re-render issue
• React Context API vs Redux for global state management

Source Code

All examples from this article are in this repo: https://github.com/DoableDanny/React-context-API-tutorial

I also made a video version of this article to make it easier for you to follow along with the examples: React Context Tutorial with Examples

What is the React Context API and When Should You Use It?

The Context API is a feature in React that provides a way to share values like themes, user information, or configuration settings between components without having to explicitly pass props through every level of the component tree. This makes it particularly useful for managing global state, or state that is needed by many components at different nesting levels.

The Context API is a part of the React library, meaning that you don't need to install it as a third-party package in a React application.

So, the Context API can be used for sharing global variables between components in a React app, without having to pass these variables as props down the component tree. This is especially useful if there are components that are deeply nested that need access to variables from higher up components.

Now, let's learn how the Context API works by going through a common use case example for the Context API...

React Context API Example — Light and Dark Mode UI Theme

A very common real-world usecase for the React Context API is for storing the current user's prefered theme – that is, "light mode" or "dark mode".

Think about it: many of the UI components in a React app will need to know about the current theme, in order to display the approprate styles. Buttons, Headings, the Navbar, the Footer, Dropdowns – lots of components are going to need to display themselves differently depending on the current theme.

The passing-down-a-prop solution

The most simple and obvious "React" way to solve this would be to create a theme variable in the main top-level App component, and then keep on passing it down as a prop to all of the components in the tree. But this leads to a React problem known as "prop drilling".

Prop drilling is a term used in React to describe the process of passing data from a parent component to a deeply nested child component through multiple intermediary components. This can happen when you need to pass state or functions several levels down the component tree.

Prop drilling example:

function App() {
  const theme = 'dark';
  return <Parent theme={theme} />;
}

function Parent({ theme }) {
  return <Child theme={theme} />;
}

function Child({ theme }) {
  return <Button theme={theme} />;
}

function Button({ theme }) {
  return <button style={{ background: theme === 'dark' ? 'black' : 'white' }}>Click me</button>;
}

As you can see, each intermediary component needs to include the prop, even if it doesn't use it, just to pass it down further. This clutters the code and makes it more difficult to understand.

Also, intermediary components that do not use the props might still re-render when the props change, leading to performance issues. This can be particularly problematic in large applications with deep component trees.

Context API To The Rescue

We can solve this prop drilling issue by using the Context API.

Creating a context

First, we need to create the context, and pass in the light theme as the default value:

// src/contexts/ThemeContext.js

import { createContext } from "react";

export const themes = {
  light: {
    background: "white",
    text: "black",
  },
  dark: {
    background: "black",
    text: "white",
  },
};

export const ThemeContext = createContext(themes.light);

Above, we have created a contexts folder inside of our src folder for storing all of our contexts. It's considered good practice to create each context in its own file. In our case, we just need to create a context for storing the current theme.

Notice that contexts are created by calling the createContext() function that comes from the React library. We pass the createContext() function a default value of themes.light.

Providing a context

Next, we need to wrap all of the components that need access to the theme in a context provider. The context provider takes a value prop, where we can pass the value that we want to make global.

Below, <Navbar /> and <Button /> will have access to the theme state, even though we haven't explicitly passed it down as a prop. This is because we have wrapped these components in the theme context provider, and passed it the value (theme) that needs to be made global.

// src/App.js

import React, { useState } from "react"
import { ThemeContext, themes } from "./contexts/ThemeContext"
import Navbar from "./components/Navbar"
import Button from "./components/Button"

const App = () => {
  const [theme, setTheme] = useState(themes.light)

  const toggleTheme = () => {
    setTheme(state => (state === themes.light ? themes.dark : themes.light))
  }

  return (
    <div className="App">
      <ThemeContext.Provider value={theme}>
        <Navbar />
        <Button changeTheme={toggleTheme} />
      </ThemeContext.Provider>
    </div>
  )
}

export default App

If we also wanted to make setTheme() available throughout our app via context, we could pass the following object to the value prop. We'd then be able to toggle the theme from any component within the Theme Context Provider:

<ThemeContext.Provider value={{ theme, setTheme }}>

Now let's create the Button and Navbar components that will consume the theme context using the useContext() hook. Notice how the CSS styles of the components change depending on the current theme values:

// src/components/Button.js

import React, { useContext } from "react"
import { ThemeContext } from "../contexts/themeContext"

const Button = ({ changeTheme }) => {
  const theme = useContext(ThemeContext)

  return (
    <button
      style={{ backgroundColor: theme.background, color: theme.text }}
      onClick={changeTheme}
    >
      Toggle theme
    </button>
  )
}

export default Button

// src/components/Navbar.js

import React, { useContext } from "react"
import { ThemeContext } from "../contexts/themeContext"

const Navbar = () => {
  const theme = useContext(ThemeContext)

  return (
    <nav style={{ backgroundColor: theme.background }}>
      <ul>
        <li style={{ color: theme.text }}>Home</li>
        <li style={{ color: theme.text }}>About</li>
      </ul>
    </nav>
  )
}

export default Navbar

Here are the steps involved in using a context:

1. Import the context that you want to use (ThemeContext in this example) into the component.
2. Import the useContext hook from React.
3. Inside of the component that needs access to the context value(s), call the useContext hook and pass the context that you want to use. Assign this to a variable (const theme = useContext(ThemeContext) in our example)
4. The component now has access to the global variable, and the component will re-render/be updated every time a value inside of the context is updated.

OK, that's everything that we need for this example. Let's now start up our application by running the following command in the project route:

npm run start

Now let's test things out in the browser.

Light mode:

Press the Toggle Theme button

Dark mode:

And there we go, we've used the context API to share the theme state throughout our application – without having to pass it down as a prop. Cool! 👌

How to Create Multiple React Contexts

In our example above, we only created one context, ThemeContext. But what if we had other data that needed to be made global, such as the current logged in user's username and age?

We could just create one big context for storing all variables that needed to be consumed globally:

<OneBigContext.Provider value={{ theme, username, age }}>
  <Button changeTheme={toggleTheme} />
  <Navbar />
</OneBigContext.Provider>

But this is considered bad practice, as whenever a context value is updated, all components consuming that context will be re-rendered. This means that all components that only need to know about the theme, and not the user variables, will get re-rendered whenever any of the user variables are updated. This can worsen an app's performance, especially in larger apps with lots of complex components.

We can solve this by creating multiple contexts – one context for the theme and another for the user data – and wrapping our app in both providers, like so:

<ThemeContext.Provider value={theme}>
  <UserContext.Provider value={{ username, age }}>
    <Button changeTheme={toggleTheme} />
    <Navbar />
  </UserContext.Provider>
</ThemeContext.Provider>

By only storing related data in each context, we help prevent unnecessary re-renders of components, and improve the performance of our app.

How to Prevent the React Context Re-render Issue

As we've discussed, whenever a context value is updated, all components consuming that context will be rerendered – even if wrapped in React.memo(). (If you don't know what React.memo() is, don't panic – we'll discuss it soon!) This can worsen an app’s performance.

But we can mitigate this problem with the following methods:

1. Use Multiple React Contexts

This is what we discussed above, and is the "preferred" way of solving the rerender problem (see this answer).

2. Split the Component and Pass the Needed Value

You can also split the component up and pass down (as a prop) the needed value from context, with the child components wrapped in React.memo(). Example:

const Card = () => {
  const appContextValue = useContext(AppContext);
  const theme = appContextValue.theme;

  return (
    <div>
      <CardTitle theme={theme} />
      <CardDescription theme={theme} />
    </div>
  );
};

const CardTitle = React.memo(({ theme }) => {
  return <h2 style={{ color: theme.text }}>This is the Title </h2>;
});

const CardDescription = React.memo(({ theme }) => {
  return <p style={{ color: theme.text }}>lorem ipsum dolor sit amet,</p>;
});

React.memo() is a higher-order component (HOC) in React that is used to optimize functional components by preventing unnecessary re-renders. It does this by memoizing the component, meaning it will only re-render if its props change.

• Without React.memo(): The components, CardTitle and CardDescription, would re-render whenever their parent, Card, re-renders – even if their props haven't changed. This can lead to performance issues in larger applications or with components that are expensive to render.
• With React.memo(): CardTitle and CardDescription only re-render if their props change, reducing unnecessary renders and improving performance.

So, by splitting the component up, passing down only the values that are needed as props, and wrapping the components in React.memo(), CardTitle and CardDescription will only be re-rendered if theme is updated, but not if username is updated.

This solution is particularly useful if we can’t split out context for whatever reason.

3. One Component with React.useMemo() Inside

Below, theme is a dependency of useMemo(), so we will only get a re-render of the elements returned by the callback function when theme is changed:

const Card = () => {
  const appContextValue = useContext(AppContext);
  const theme = appContextValue.theme;

  return useMemo(
    () => (
      <div>
        <CardTitle theme={theme} />
        <CardDescription theme={theme} />
      </div>
    ),
    [theme]
  );
};

const CardTitle = ({ theme }) => {
  return <h2 style={{ color: theme.text }}>This is the Title </h2>;
};

const CardDescription = ({ theme }) => {
  return <p style={{ color: theme.text }}>lorem ipsum dolor sit amet,</p>;
};

Here's how useMemo() works:

1. The first parameter of useMemo() is a callback function that returns a memoized value. In this case, it returns a React element, or tree of React elements.
2. The second parameter is an array of dependences. If any of the values in this dependency array are updated, then the callback function provided as the first argument is called, and the elements that the callback function returns are re-rendered.

So, useMemo() can be used to only re-render React elements if certain values specified in the dependency array are updated.

By wrapping these elements in useMemo(), and specifying theme as the only dependency, the elements only get re-rendered if theme is updated, but won't get re-rendered if any other context value is updated.

This solution is also particularly useful if we can’t split out context.

React Context API vs Redux

This is a very common and much-depated topic within the React community. React Context API and Redux are both tools for managing state in a React application, but they have different use cases, strengths, and limitations.

The Context API is a built-in feature of React, with the primary purpose of allowing state to be shared across a tree of React components without prop drilling.

The Context API has a simple API: React.createContext(), Provider, and the useContext() hook. And is good for small to medium-sized apps, as it is straightforward to use, and requires little setup and boilerplate code.

On the other hand, Redux is a state management library that has to be installed as a third-party package into an application. Its primary purpose is to manage application-wide state in a predictable way, especially in large and complex applications.

Why Context API is good for small-to-medium-sized apps:

• Simplicity: It's simpler than Redux.
• Built-in: It's part of React, so no need to install extra packages, making maintenance of the project easier.
• Minimal boilerplate: Requires less boilerplate and setup than Redux.

Why Redux is good for larger, more complex applications:

• Single Store: Maintains a single store for the entire application state, which makes debugging and testing easier.
• Predictable State Updates: Uses pure functions (reducers) to manage state updates, ensuring predictability and immutability.
• Middleware Support: Powerful middleware system (like redux-thunk or redux-saga) for handling asynchronous actions and side effects.
• DevTools Integration: Excellent developer tools for time-travel debugging and state inspection.
• Suitable for Large Apps: Designed to handle complex state logic and large-scale applications.

Redux maintainer, Mark Erikson, gives the following reasons for using Redux:

• Consistent architectural patterns
• Debugging capabilities
• Middleware
• Addons and extensibility
• Cross-platform and cross-framework usage
• Depending on your app's setup, much better performance than working with just Context (we don't have to worry about the rerender problem we get with Context, mentioned above – components only rerender when the value they are using updates)

In summary:

• Redux is a more complex state management tool that provides more features and tools. It provides a consistent way of managing state throughout an application, which is very helpful on larger projects with multiple developers (as they won't all be implementing their own styles of state management and making the codebase inconsistent).
• React Context API is more straightforward, requires less setup, and is a good solution for smaller to medium sized projects where the added complexity and overhead of using a tool like Redux isn't necessary.

Thank you for reading!

If you found this article useful, you can hear more from me by:

• Subscribing to my YouTube channel. I plan to turn it into a React/NextJS/Node-focused channel, with in-depth videos 😎.
• Following me on Twitter where I tweet about my freelancing journey, side projects and current learnings.
• Checking out my tech blog

Free React Hooks Course

Want to learn all the hooks in React? I created a free 2 hour video explaining all 9 core React Hooks with examples: React Hooks Tutorial — All React Hooks Explained with Examples. If you enjoy, consider subscribing to my channel.

Cheers!

This will be a great project to learn how to put together fullstack apps, and how to create an app where the backend can communicate with the frontend in real time.

Normally, using HTTP requests, the server cannot push data to the client in real time. But using Socket.io, the server is able to push real time information to the client about some events that happened on the server.

The app that we'll be building will have two pages:

A join-a-chat-room page:

And a chat-room page:

Here's what we'll be using to build this app:

• Frontend: React (A frontend JavaScript framework for building interactive applications)
• Backend: Node and Express (Express is very popular NodeJS framework that allows us to easily create APIs and backends)
• Database: HarperDB (a data + application platform that allows you to query data using either SQL or NoSQL. HarperDB also has a built-in API, saving us from having to write a lot of backend code)
• Realtime communication: Socket.io (see below!)

Here is the source code (remember to give it a star ⭐).

Table of Contents

1. What is Socket.io?
2. Project Setup
3. How to Build the "Join a Room" Page
4. How to Set Up the Server
5. How to Create our First Socket.io Event Listener on the Server
6. How Rooms Work in Socket.io
7. How to Build the Chat Page
8. How to Create the Messages Component (B)
9. How to Create a Schema and Table in HarperDB
10. How to Create the Send Message Component (C)
11. How to Set Up HarperDB Environment Variables
12. How to Allow Users to Send Messages to Each Other with Socket.io
13. How to Get Messages from HarperDB
14. How to Display the Last 100 Messages on the Client
15. How to Display the Room and Users (A)
16. How to Remove a User from a Socket.io Room
17. How to Add the Socket.io Disconnect Event Listener

What is Socket.IO?

Socket.IO allows the server to push information to the client in real time, when events occur on the server.

For example, if you were playing a multiplayer game, an event could be your "friend" scoring a spectacular goal against you.

With Socket.IO, you'd know (almost) instantly about conceding a goal.

Without Socket.IO, the client would have to make multiple polling AJAX calls to verify that the event has occurred on the server. For example, the client could use JavaScript to check for an event on the server every 5 seconds.

Socket.IO means that the client doesn't have to make multiple polling AJAX calls to verify if some event has occurred on the server. Instead, the server sends the info to the client as soon as it gets it. Much better. 👌

So, Socket.IO allows us to easily build real time applications, such as chat apps and multiplayer games.

Project Setup

1. How to set up our folders

Start a new project in your text editor of choice (VS Code for me), and create two folders at the root called client and server.

We will create our frontend React application in the client folder, and our Node/Express backend in the server folder.

2. How to install our client dependencies

Open up a terminal in the root of the project (in VS Code, you can do this by pressing Ctrl+' or by going to terminal->new terminal)

Next, we will install React into our client directory:

$ npx create-react-app client

After React has installed, change directories into the client folder, and install the following dependencies:

$ cd client
$ npm i react-router-dom socket.io-client

React-router-dom will allow us to set up routes to our different React components – essentially creating different pages.

Socket.io-client is the client version of socket.io, that allows us to "emit" events to the server. Once received by the server, we can use the server version of socket.io to do stuff like sending messages to users in the same room as the sender, or join a user to a socket room.

You will gain a better understanding of this later when we come to implement these ideas with code.

3. How to boot up the React app

Let's check to make sure everything is working by running the following command from the client directory:

$ npm start

Webpack will build the React app and serve it to http://localhost:3000:

Let's now set up our HarperDB database that we will use to permanently save messages sent by users.

How to set up HarperDB

First, create an account with HarperDB.

Then create a new HarperDB cloud instance:

To make things easy, select the cloud instance:

Select the cloud provider (I chose AWS):

Name your cloud instance, and create your instance credentials:

HarperDB has a generous free tier that we can use for this project, so select that:

Check your details are correct, then create the instance.

It will take a few minutes to create the instance, so let's crack on and make our first React component!

How to Build the "Join a Room" Page

Our homepage is going to end up looking like this:

The user will enter a username, select a chat room from the dropdown, then click "Join Room". The user will then be taken to the chat room page.

So, let's make this homepage.

1. How to create the HTML form and add styles

Create a new file at src/pages/home/index.js.

We will add basic styling to our app using CSS modules, so create a new file: src/pages/home/styles.module.css.

Our folder structure should now look like this:

Now let's create the basic form HTML:

// client/src/pages/home/index.js

import styles from './styles.module.css';

const Home = () => {
  return (
    <div className={styles.container}>
      <div className={styles.formContainer}>
        <h1>{`<>DevRooms</>`}</h1>
        <input className={styles.input} placeholder='Username...' />

        <select className={styles.input}>
          <option>-- Select Room --</option>
          <option value='javascript'>JavaScript</option>
          <option value='node'>Node</option>
          <option value='express'>Express</option>
          <option value='react'>React</option>
        </select>

        <button className='btn btn-secondary'>Join Room</button>
      </div>
    </div>
  );
};

export default Home;

Above, we have a simple text input to capture the username, and a select dropdown with some default options for the user to select a chat room to join.

Let's now import this component into App.js, and set up a route for the component using the react-router-dom package. This will be our home page, so the path will just be "/":

// client/src/App.js

import './App.css';
import { BrowserRouter as Router, Routes, Route } from 'react-router-dom';
import Home from './pages/home';

function App() {
  return (
    <Router>
      <div className='App'>
        <Routes>
          <Route path='/' element={<Home />} />
        </Routes>
      </div>
    </Router>
  );
}

export default App;

Now let's add some base styles to make our app look more presentable:

/* client/src/App.css */

html * {
  font-family: Arial;
  box-sizing: border-box;
}
body {
  margin: 0;
  padding: 0;
  overflow: hidden;
  background: rgb(63, 73, 204);
}
::-webkit-scrollbar {
  width: 20px;
}
::-webkit-scrollbar-track {
  background-color: transparent;
}
::-webkit-scrollbar-thumb {
  background-color: #d6dee1;
  border-radius: 20px;
  border: 6px solid transparent;
  background-clip: content-box;
}
::-webkit-scrollbar-thumb:hover {
  background-color: #a8bbbf;
}
.btn {
  padding: 14px 14px;
  border-radius: 6px;
  font-weight: bold;
  font-size: 1.1rem;
  cursor: pointer;
  border: none;
}
.btn-outline {
  color: rgb(153, 217, 234);
  border: 1px solid rgb(153, 217, 234);
  background: rgb(63, 73, 204);
}
.btn-primary {
  background: rgb(153, 217, 234);
  color: rgb(0, 24, 111);
}
.btn-secondary {
  background: rgb(0, 24, 111);
  color: #fff;
}

Let's also add the styles specific to our home page component:

/* client/src/pages/home/styles.module.css */

.container {
  height: 100vh;
  width: 100%;
  display: flex;
  justify-content: center;
  align-items: center;
  background: rgb(63, 73, 204);
}
.formContainer {
  width: 400px;
  margin: 0 auto 0 auto;
  padding: 32px;
  background: lightblue;
  border-radius: 6px;
  display: flex;
  flex-direction: column;
  align-items: center;
  gap: 28px;
}
.input {
  width: 100%;
  padding: 12px;
  border-radius: 6px;
  border: 1px solid rgb(63, 73, 204);
  font-size: 0.9rem;
}
.input option {
  margin-top: 20px;
}

Let's also make the "Join Room" button full width by adding a style attribute:

// client/src/pages/home/index.js

<button className='btn btn-secondary' style={{ width: '100%' }}>Join Room</button>

Our home page is now looking solid:

2. How to add functionality to the Join Room form

Now we have a basic form and styling, so it's time to add some functionality.

Here's what we want to happen when the user clicks the "Join Room" button:

1. Check that the username and room fields are filled in.
2. If so, we emit a socket event to our server.
3. Redirect the user to the Chat page (which we will create later).

We are going to need to create some state to store username and room values. We also need to create a socket instance.

We could create these states directly within our home component, but our Chat page will also need access to username, room and socket. So we will lift the state up to App.js, where we can then pass these variables down to both the Homepage and Chat page components.

So, let's create our state and set up a socket in App.js, and pass these variables down as props to the component. We'll also pass the set state functions so we can alter state from :

// client/src/App.js

import './App.css';
import { useState } from 'react'; // Add this
import { BrowserRouter as Router, Routes, Route } from 'react-router-dom';
import io from 'socket.io-client'; // Add this
import Home from './pages/home';

const socket = io.connect('http://localhost:4000'); // Add this -- our server will run on port 4000, so we connect to it from here

function App() {
  const [username, setUsername] = useState(''); // Add this
  const [room, setRoom] = useState(''); // Add this

  return (
    <Router>
      <div className='App'>
        <Routes>
          <Route
            path='/'
            element={
              <Home
                username={username} // Add this
                setUsername={setUsername} // Add this
                room={room} // Add this
                setRoom={setRoom} // Add this
                socket={socket} // Add this
              />
            }
          />
        </Routes>
      </div>
    </Router>
  );
}

export default App;

We can now access these props in our Home Component. We will use destructuring to get the props:

// client/src/pages/home/index.js

import styles from './style.module.css';

const Home = ({ username, setUsername, room, setRoom, socket }) => {
  return (
    // ...
  );
};

export default Home;

When the user types their username or selects a room, we need to update the username and room state variables:

// client/src/pages/home/index.js

// ...

const Home = ({ username, setUsername, room, setRoom, socket }) => {
  return (
    <div className={styles.container}>
      // ...
        <input
          className={styles.input}
          placeholder='Username...'
          onChange={(e) => setUsername(e.target.value)} // Add this
        />

        <select
          className={styles.input}
          onChange={(e) => setRoom(e.target.value)} // Add this
        >
         // ...
        </select>

        // ...
    </div>
  );
};

export default Home;

Now we are capturing the data entered by the user, we can create a joinRoom() callback function for when the user clicks the "Join Room" button:

// client/src/pages/home/index.js

// ...

const Home = ({ username, setUsername, room, setRoom, socket }) => {

  // Add this
  const joinRoom = () => {
    if (room !== '' && username !== '') {
      socket.emit('join_room', { username, room });
    }
  };

  return (
    <div className={styles.container}>
      // ...

        <button
          className='btn btn-secondary'
          style={{ width: '100%' }}
          onClick={joinRoom} // Add this
        >
          Join Room
        </button>
      // ...
    </div>
  );
};

export default Home;

Above, when the user clicks the button, a socket event called _joinroom is emitted, along with an object containing the user's username and selected room. This event will be received by our server a little later on where we will do some magic.

To finish our home page component, we need to add a redirect at the bottom of our joinRoom() function to take the user to the /chat page:

// client/src/pages/home/index.js

// ...
import { useNavigate } from 'react-router-dom'; // Add this

const Home = ({ username, setUsername, room, setRoom, socket }) => {
  const navigate = useNavigate(); // Add this

  const joinRoom = () => {
    if (room !== '' && username !== '') {
      socket.emit('join_room', { username, room });
    }

    // Redirect to /chat
    navigate('/chat', { replace: true }); // Add this
  };

 // ...

Test it out: type a username and select a room, then click Join Room. You should be taken to the route http://localhost:3000/chat – currently an empty page.

But before we create our Chat Page frontend, let's get some stuff running on the server.

How to Set Up the Server

On the server, we are going to listen out for socket events emitted from the frontend. Currently, we only have a join_room event being emitted from React, so we will add this event listener first.

But before that, we need to install our server dependencies and get the server up and running.

1. How to install the server dependencies

Open up a new terminal (in VS code: Terminal->New Terminal), change directory into our server folder, initialise a package.json file, and install the following dependencies:

$ cd server
$ npm init -y
$ npm i axios cors express socket.io dotenv

• Axios is a commonly used package to easily make requests to APIs.
• Cors allows our client to make requests to other origins – necessary for socket.io to work properly. See What is CORS? if you haven't heard of CORS before.
• Express is a NodeJS framework that allows us to write our backend more easily with less code.
• Socket.io is a library that allows the client and server to communicate in realtime – which isn't possible with standard HTTP requests.
• Dotenv is a module that allows us to store private keys and passwords safely, and load them into our code when needed.

We will also install nodemon as a dev dependency, so we don't have to restart our server every time we make a change to the code – saving us time and energy:

$ npm i -D nodemon

2. How to boot up our server

Create a folder called index.js in the root of our server directory, and add the following code to get a server up and running:

// server/index.js

const express = require('express');
const app = express();
const http = require('http');
const cors = require('cors');

app.use(cors()); // Add cors middleware

const server = http.createServer(app);

server.listen(4000, () => 'Server is running on port 4000');

Open up the package.json file on our server, and add a script that will allow us to use nodemon in development:

{
  ...
  "scripts": {
    "dev": "nodemon index.js"
  },
  ...
}

Now, let's boot up our server by running the following command:

$ npm run dev

We can quickly check that our server is running correctly by adding a get request handler:

// server/index.js

const express = require('express');
const app = express();
http = require('http');
const cors = require('cors');

app.use(cors()); // Add cors middleware

const server = http.createServer(app);

// Add this
app.get('/', (req, res) => {
  res.send('Hello world');
});

server.listen(4000, () => 'Server is running on port 3000');

Now go to http://localhost:4000/:

Our server is up and running. It's now time to do some server-side Socket.io stuff!

How to Create our First Socket.io Event Listener on the Server

Remember when we emitted a _joinroom event from the client? Well, we are soon going to be listening for that event on the server and adding the user to a socket room.

But first, we need to listen out for when a client connects to the server via socket.io-client.

// server/index.js

const express = require('express');
const app = express();
http = require('http');
const cors = require('cors');
const { Server } = require('socket.io'); // Add this

app.use(cors()); // Add cors middleware

const server = http.createServer(app); // Add this

// Add this
// Create an io server and allow for CORS from http://localhost:3000 with GET and POST methods
const io = new Server(server, {
  cors: {
    origin: 'http://localhost:3000',
    methods: ['GET', 'POST'],
  },
});

// Add this
// Listen for when the client connects via socket.io-client
io.on('connection', (socket) => {
  console.log(`User connected ${socket.id}`);

  // We can write our socket event listeners in here...
});

server.listen(4000, () => 'Server is running on port 3000');

Now, when the client connects from the frontend, the backend captures the connection event, and will log User connected with the unique socket id for that particular client.

Let's test if the server is now capturing the connection event from the client. Go to your React app at http://localhost:3000/ and refresh the page.

You should see the following log in your server terminal console:

Awesome, our client has connected to our server via socket.io. Our client and server can now communicate in real time!

How Rooms Work in Socket.io

From the Socket.io docs:

"A room is an arbitrary channel that sockets can join and leave. It can be used to broadcast events to a subset of clients."

So, we can join the user to a room, and then the server can send messages to all users in that room – allowing users to send messages to each other in real time. Cool!

How to join the user to a Socket.io room

Once the user has connected via Socket.io, we can add our socket event listeners on the server to listen for events emitted from the client. Also, we can emit events on the server, and listen for them on the client.

Let's now listen for the _joinroom event, capture the data (username and room), and add the user to a socket room:

// server/index.js

// Listen for when the client connects via socket.io-client
io.on('connection', (socket) => {
  console.log(`User connected ${socket.id}`);

  // Add this
  // Add a user to a room
  socket.on('join_room', (data) => {
    const { username, room } = data; // Data sent from client when join_room event emitted
    socket.join(room); // Join the user to a socket room
  });
});

How to send a message to users in a room

Let's now send a message to all users in the room, apart from the user that just joined, to notify them that a new user has joined:

// server/index.js

const CHAT_BOT = 'ChatBot'; // Add this
// Listen for when the client connects via socket.io-client
io.on('connection', (socket) => {
  console.log(`User connected ${socket.id}`);

  // Add a user to a room
  socket.on('join_room', (data) => {
    const { username, room } = data; // Data sent from client when join_room event emitted
    socket.join(room); // Join the user to a socket room

    // Add this
    let __createdtime__ = Date.now(); // Current timestamp
    // Send message to all users currently in the room, apart from the user that just joined
    socket.to(room).emit('receive_message', {
      message: `${username} has joined the chat room`,
      username: CHAT_BOT,
      __createdtime__,
    });
  });
});

Above, we are emitting a receive_message event to all clients in the room the current user has just joined, along with some data: the message, username who sent the message, and the time the message was sent.

We will add an event listener in our React application a little later to capture this event, and output the message on the screen.

Let's also send a welcome message to the newly-joined user:

// server/index.js

io.on('connection', (socket) => {
  // ...

    // Add this
    // Send welcome msg to user that just joined chat only
    socket.emit('receive_message', {
      message: `Welcome ${username}`,
      username: CHAT_BOT,
      __createdtime__,
    });
  });
});

When we add a user to a Socket.io room, Socket.io only stores the socket ids for each user. But we will need the usernames of everyone in the room, as well as the room name. So, let's store that data in variables on the server:

// server/index.js

// ...

const CHAT_BOT = 'ChatBot';
// Add this
let chatRoom = ''; // E.g. javascript, node,...
let allUsers = []; // All users in current chat room

// Listen for when the client connects via socket.io-client
io.on('connection', (socket) => {
    // ...

    // Add this
    // Save the new user to the room
    chatRoom = room;
    allUsers.push({ id: socket.id, username, room });
    chatRoomUsers = allUsers.filter((user) => user.room === room);
    socket.to(room).emit('chatroom_users', chatRoomUsers);
    socket.emit('chatroom_users', chatRoomUsers);
  });
});

Above, we are also sending an array of all the chatRoomUsers back to the client via the _chatroomusers event, so we can list all the usernames in the room on the frontend.

Before we add any more code to our server, let's go back to our frontend and create the Chat page – so we can test out if we are receiving the _receivemessage events.

How to Build the Chat Page

In your client folder, create two new files:

1. src/pages/chat/index.js
2. src/pages/chat/styles.module.css

Let's add some styles that we'll use in our chat page and components:

/* client/src/pages/chat/styles.module.css */

.chatContainer {
  max-width: 1100px;
  margin: 0 auto;
  display: grid;
  grid-template-columns: 1fr 4fr;
  gap: 20px;
}

/* Room and users component */
.roomAndUsersColumn {
  border-right: 1px solid #dfdfdf;
}
.roomTitle {
  margin-bottom: 60px;
  text-transform: uppercase;
  font-size: 2rem;
  color: #fff;
}
.usersTitle {
  font-size: 1.2rem;
  color: #fff;
}
.usersList {
  list-style-type: none;
  padding-left: 0;
  margin-bottom: 60px;
  color: rgb(153, 217, 234);
}
.usersList li {
  margin-bottom: 12px;
}

/* Messages */
.messagesColumn {
  height: 85vh;
  overflow: auto;
  padding: 10px 10px 10px 40px;
}
.message {
  background: rgb(0, 24, 111);
  border-radius: 6px;
  margin-bottom: 24px;
  max-width: 600px;
  padding: 12px;
}
.msgMeta {
  color: rgb(153, 217, 234);
  font-size: 0.75rem;
}
.msgText {
  color: #fff;
}

/* Message input and button */
.sendMessageContainer {
  padding: 16px 20px 20px 16px;
}
.messageInput {
  padding: 14px;
  margin-right: 16px;
  width: 60%;
  border-radius: 6px;
  border: 1px solid rgb(153, 217, 234);
  font-size: 0.9rem;
}

Now, let's see what our Chat page will end up looking like:

Adding all of the code and logic for this page in one file could get confusing and difficult to manage, so let's take advantage of the fact that we are using an awesome frontend framework (React) and split our page into components:

The chat page components:

A: Contains the room name, a list of users in that room, and a "Leave" button that removes the user from the room.

B: The sent messages. Upon initial render, the last 100 messages sent in that room will be fetched from the database and shown to the user.

C: An input and button to type and send a message.

We will first create component B, so we can display messages to the user.

How to Create the Messages Component (B)

Create a new file at src/pages/chat/messages.js and add the following code:

// client/src/pages/chat/messages.js

import styles from './styles.module.css';
import { useState, useEffect } from 'react';

const Messages = ({ socket }) => {
  const [messagesRecieved, setMessagesReceived] = useState([]);

  // Runs whenever a socket event is recieved from the server
  useEffect(() => {
    socket.on('receive_message', (data) => {
      console.log(data);
      setMessagesReceived((state) => [
        ...state,
        {
          message: data.message,
          username: data.username,
          __createdtime__: data.__createdtime__,
        },
      ]);
    });

    // Remove event listener on component unmount
    return () => socket.off('receive_message');
  }, [socket]);

  // dd/mm/yyyy, hh:mm:ss
  function formatDateFromTimestamp(timestamp) {
    const date = new Date(timestamp);
    return date.toLocaleString();
  }

  return (
    <div className={styles.messagesColumn}>
      {messagesRecieved.map((msg, i) => (
        <div className={styles.message} key={i}>
          <div style={{ display: 'flex', justifyContent: 'space-between' }}>
            <span className={styles.msgMeta}>{msg.username}</span>
            <span className={styles.msgMeta}>
              {formatDateFromTimestamp(msg.__createdtime__)}
            </span>
          </div>
          <p className={styles.msgText}>{msg.message}</p>
          <br />
        </div>
      ))}
    </div>
  );
};

export default Messages;

Above, we have a useEffect hook that runs whenever a socket event is received. We then get the message data passed into the _receivemessage event listener. From there, we set the messagesReceived state, which is an array of message objects containing the message, username of the sender, and the date the message was sent.

Let's import our new messages component into the Chat page, and then create a route for the Chat page in App.js:

// client/src/pages/chat/index.js

import styles from './styles.module.css';
import MessagesReceived from './messages';

const Chat = ({ socket }) => {
  return (
    <div className={styles.chatContainer}>
      <div>
        <MessagesReceived socket={socket} />
      </div>
    </div>
  );
};

export default Chat;

// client/src/App.js

import './App.css';
import { useState } from 'react';
import Home from './pages/home';
import Chat from './pages/chat';
import { BrowserRouter as Router, Routes, Route } from 'react-router-dom';
import io from 'socket.io-client';

const socket = io.connect('http://localhost:4000');

function App() {
  const [username, setUsername] = useState('');
  const [room, setRoom] = useState('');

  return (
    <Router>
      <div className='App'>
        <Routes>
          <Route
            path='/'
            element={
              <Home
                username={username}
                setUsername={setUsername}
                room={room}
                setRoom={setRoom}
                socket={socket}
              />
            }
          />
          {/* Add this */}
          <Route
            path='/chat'
            element={<Chat username={username} room={room} socket={socket} />}
          />
        </Routes>
      </div>
    </Router>
  );
}

export default App;

Let's test this out: go to the home page and join a room:

We should be taken to the Chat page, and receive a welcome message from ChatBot:

Users can now see the messages they receive. Awesome!

Next up: setting up our database so we can permanently save messages.

How to Create a Schema and Table in HarperDB

Go back to your HarperDB dashboard, and click "browse". Then create a new schema called "realtime_chat_app". A schema is simply a group of tables.

Within that schema, create a table called "messages", with a hash attribute of "id".

We now have somewhere to store messages, so let's create the SendMessage component.

How to Create the Send Message Component (C)

Create the file src/pages/chat/send-message.js and add the following code:

// client/src/pages/chat/send-message.js

import styles from './styles.module.css';
import React, { useState } from 'react';

const SendMessage = ({ socket, username, room }) => {
  const [message, setMessage] = useState('');

  const sendMessage = () => {
    if (message !== '') {
      const __createdtime__ = Date.now();
      // Send message to server. We can't specify who we send the message to from the frontend. We can only send to server. Server can then send message to rest of users in room
      socket.emit('send_message', { username, room, message, __createdtime__ });
      setMessage('');
    }
  };

  return (
    <div className={styles.sendMessageContainer}>
      <input
        className={styles.messageInput}
        placeholder='Message...'
        onChange={(e) => setMessage(e.target.value)}
        value={message}
      />
      <button className='btn btn-primary' onClick={sendMessage}>
        Send Message
      </button>
    </div>
  );
};

export default SendMessage;

Above, when the user clicks the "Send Message" button, a send_message socket event is emitted to the server, along with a message object. We will handle this event on the server shortly.

Import SendMessage into our Chat page:

// src/pages/chat/index.js

import styles from './styles.module.css';
import MessagesReceived from './messages';
import SendMessage from './send-message';

const Chat = ({ username, room, socket }) => {
  return (
    <div className={styles.chatContainer}>
      <div>
        <MessagesReceived socket={socket} />
        <SendMessage socket={socket} username={username} room={room} />
      </div>
    </div>
  );
};

export default Chat;

The chat page now looks like this:

Next we need to set up our HarperDB environment variables so we can start interacting with the database.

How to Set Up HarperDB Environment Variables

In order for you to be able to save messages in HarperDB, you'll need your HarperDB instance URL, and your API password.

In your HarperDB dashboard, click on your instance, then go to "config". You will find your instance URL, and your instance API Auth Header – that is, your "super_user" password that allows you to make any request to the database – FOR YOUR EYES ONLY!

We will store these variables in a .env file. Warning: don't push the .env file to GitHub! This file should not be publicly visible. The variables are loaded in via the server behind the scenes.

Create the following files and add your HarperDB URL and password:

// server/.env

HARPERDB_URL="<your url goes here>"
HARPERDB_PW="Basic <your password here>"

We'll also create a .gitignore file to prevent the .env from being pushed to GitHub, along with the node_modules folder:

// server/.gitignore

.env
node_modules

Note: being good with Git and GitHub is a 100% must for all developers. Check out my Git workflows article if you need to up your Git game.

Or if you find yourself constantly having to look up the same Git commands, and want a quick way to look up, revise, and copy/paste commands -- check out my popular Git commands cheat sheet PDF and physical Git cheat sheet poster.

Finally, let's load our environment variables into our server by adding this code to the top of our main server file:

// server/index.js

require('dotenv').config();
console.log(process.env.HARPERDB_URL); // remove this after you've confirmed it working
const express = require('express');
// ...

How to Allow Users to Send Messages to Each Other with Socket.io

On the server, we'll listen for the _sendmessage event, then send the message to all users within the room:

// server/index.js

const express = require('express');
// ...
const harperSaveMessage = require('./services/harper-save-message'); // Add this

// ...

// Listen for when the client connects via socket.io-client
io.on('connection', (socket) => {

  // ...

  // Add this
  socket.on('send_message', (data) => {
    const { message, username, room, __createdtime__ } = data;
    io.in(room).emit('receive_message', data); // Send to all users in room, including sender
    harperSaveMessage(message, username, room, __createdtime__) // Save message in db
      .then((response) => console.log(response))
      .catch((err) => console.log(err));
  });
});

server.listen(4000, () => 'Server is running on port 3000');

We now need to create the harperSaveMessage function. Create a new file at server/services/harper-save-message.js, and add the following:

// server/services/harper-save-message.js

var axios = require('axios');

function harperSaveMessage(message, username, room) {
  const dbUrl = process.env.HARPERDB_URL;
  const dbPw = process.env.HARPERDB_PW;
  if (!dbUrl || !dbPw) return null;

  var data = JSON.stringify({
    operation: 'insert',
    schema: 'realtime_chat_app',
    table: 'messages',
    records: [
      {
        message,
        username,
        room,
      },
    ],
  });

  var config = {
    method: 'post',
    url: dbUrl,
    headers: {
      'Content-Type': 'application/json',
      Authorization: dbPw,
    },
    data: data,
  };

  return new Promise((resolve, reject) => {
    axios(config)
      .then(function (response) {
        resolve(JSON.stringify(response.data));
      })
      .catch(function (error) {
        reject(error);
      });
  });
}

module.exports = harperSaveMessage;

Above, saving the data may take a little time, so we are returning a promise which will be resolved if the data saves successfully, or rejected if not.

If you're wondering where I got the above code, HarperDB provides an awesome "code examples" section in their studio dashboard, which makes life much easier:

Time to test! Join a room as a user, then send a message. Then go to HarperDB and click on "browse", then click on the "messages" table. You should see your message in the database:

Cool 😎. So what next? Well, it'd be great if the last 100 messages sent in the room were loaded when a user joins a room, wouldn't it?

How to Get Messages from HarperDB

On the server, let's create a function that fetches the last 100 messages sent in a particular room (notice how HarperDB also allows us to use SQL queries 👌):

// server/services/harper-get-messages.js

let axios = require('axios');

function harperGetMessages(room) {
  const dbUrl = process.env.HARPERDB_URL;
  const dbPw = process.env.HARPERDB_PW;
  if (!dbUrl || !dbPw) return null;

  let data = JSON.stringify({
    operation: 'sql',
    sql: `SELECT * FROM realtime_chat_app.messages WHERE room = '${room}' LIMIT 100`,
  });

  let config = {
    method: 'post',
    url: dbUrl,
    headers: {
      'Content-Type': 'application/json',
      Authorization: dbPw,
    },
    data: data,
  };

  return new Promise((resolve, reject) => {
    axios(config)
      .then(function (response) {
        resolve(JSON.stringify(response.data));
      })
      .catch(function (error) {
        reject(error);
      });
  });
}

module.exports = harperGetMessages;

We'll call this function whenever a user joins a room:

// server/index.js

// ...
const harperSaveMessage = require('./services/harper-save-message');
const harperGetMessages = require('./services/harper-get-messages'); // Add this

// ...

// Listen for when the client connects via socket.io-client
io.on('connection', (socket) => {
  console.log(`User connected ${socket.id}`);

  // Add a user to a room
  socket.on('join_room', (data) => {

    // ...

    // Add this
    // Get last 100 messages sent in the chat room
    harperGetMessages(room)
      .then((last100Messages) => {
        // console.log('latest messages', last100Messages);
        socket.emit('last_100_messages', last100Messages);
      })
      .catch((err) => console.log(err));
  });

 // ...

Above, if the messages are fetched successfully, we emit a Socket.io event called _last_100messages. We'll now listen for this event on the frontend.

How to Display the Last 100 Messages on the Client

Below, we add a useEffect hook that contains a Socket.io event listener for the _last_100messages event. From there, the messages are sorted in date order, with most recent at the bottom, and the messagesReceived state is updated.

When messagesReceived is updated, a useEffect runs to scroll the messageColumn div to the most recent message. This improves the user experience of our app 👍.

// client/src/pages/chat/messages.js

import styles from './styles.module.css';
import { useState, useEffect, useRef } from 'react';

const Messages = ({ socket }) => {
  const [messagesRecieved, setMessagesReceived] = useState([]);

  const messagesColumnRef = useRef(null); // Add this

  // Runs whenever a socket event is recieved from the server
  useEffect(() => {
    socket.on('receive_message', (data) => {
      console.log(data);
      setMessagesReceived((state) => [
        ...state,
        {
          message: data.message,
          username: data.username,
          __createdtime__: data.__createdtime__,
        },
      ]);
    });

    // Remove event listener on component unmount
    return () => socket.off('receive_message');
  }, [socket]);

  // Add this
  useEffect(() => {
    // Last 100 messages sent in the chat room (fetched from the db in backend)
    socket.on('last_100_messages', (last100Messages) => {
      console.log('Last 100 messages:', JSON.parse(last100Messages));
      last100Messages = JSON.parse(last100Messages);
      // Sort these messages by __createdtime__
      last100Messages = sortMessagesByDate(last100Messages);
      setMessagesReceived((state) => [...last100Messages, ...state]);
    });

    return () => socket.off('last_100_messages');
  }, [socket]);

  // Add this
  // Scroll to the most recent message
  useEffect(() => {
    messagesColumnRef.current.scrollTop =
      messagesColumnRef.current.scrollHeight;
  }, [messagesRecieved]);

  // Add this
  function sortMessagesByDate(messages) {
    return messages.sort(
      (a, b) => parseInt(a.__createdtime__) - parseInt(b.__createdtime__)
    );
  }

  // dd/mm/yyyy, hh:mm:ss
  function formatDateFromTimestamp(timestamp) {
    const date = new Date(timestamp);
    return date.toLocaleString();
  }

  return (
    // Add ref to this div
    <div className={styles.messagesColumn} ref={messagesColumnRef}>
      {messagesRecieved.map((msg, i) => (
        <div className={styles.message} key={i}>
          <div style={{ display: 'flex', justifyContent: 'space-between' }}>
            <span className={styles.msgMeta}>{msg.username}</span>
            <span className={styles.msgMeta}>
              {formatDateFromTimestamp(msg.__createdtime__)}
            </span>
          </div>
          <p className={styles.msgText}>{msg.message}</p>
          <br />
        </div>
      ))}
    </div>
  );
};

export default Messages;

How to Display the Room and Users (A)

We've made components B and C, so let's finish things off by making A.

On the server, when a user joins a room, we emit a _chatroomusers event that sends all of the users in the room to all clients in that room. Let's listen for that event in a component called RoomAndUsers.

Below, there's also a "Leave" button that, when pressed, causes the emission of a _leaveroom event to the server. It then redirects the user back to the Home page.

// client/src/pages/chat/room-and-users.js

import styles from './styles.module.css';
import { useState, useEffect } from 'react';
import { useNavigate } from 'react-router-dom';

const RoomAndUsers = ({ socket, username, room }) => {
  const [roomUsers, setRoomUsers] = useState([]);

  const navigate = useNavigate();

  useEffect(() => {
    socket.on('chatroom_users', (data) => {
      console.log(data);
      setRoomUsers(data);
    });

    return () => socket.off('chatroom_users');
  }, [socket]);

  const leaveRoom = () => {
    const __createdtime__ = Date.now();
    socket.emit('leave_room', { username, room, __createdtime__ });
    // Redirect to home page
    navigate('/', { replace: true });
  };

  return (
    <div className={styles.roomAndUsersColumn}>
      <h2 className={styles.roomTitle}>{room}</h2>

      <div>
        {roomUsers.length > 0 && <h5 className={styles.usersTitle}>Users:</h5>}
        <ul className={styles.usersList}>
          {roomUsers.map((user) => (
            <li
              style={{
                fontWeight: `${user.username === username ? 'bold' : 'normal'}`,
              }}
              key={user.id}
            >
              {user.username}
            </li>
          ))}
        </ul>
      </div>

      <button className='btn btn-outline' onClick={leaveRoom}>
        Leave
      </button>
    </div>
  );
};

export default RoomAndUsers;

Let's import this component into the Chat page:

// client/src/pages/chat/index.js

import styles from './styles.module.css';
import RoomAndUsersColumn from './room-and-users'; // Add this
import SendMessage from './send-message';
import MessagesReceived from './messages';

const Chat = ({ username, room, socket }) => {
  return (
    <div className={styles.chatContainer}>
      {/* Add this */}
      <RoomAndUsersColumn socket={socket} username={username} room={room} />

      <div>
        <MessagesReceived socket={socket} />
        <SendMessage socket={socket} username={username} room={room} />
      </div>
    </div>
  );
};

export default Chat;

How to Remove a User from a Socket.io Room

Socket.io provides a leave() method that you can use to remove a user from a Socket.io room. We are also keeping track of our users in an array on server memory, so we'll remove the user from this array too:

// server/index.js

const leaveRoom = require('./utils/leave-room'); // Add this

// ...

// Listen for when the client connects via socket.io-client
io.on('connection', (socket) => {

  // ...

  // Add this
  socket.on('leave_room', (data) => {
    const { username, room } = data;
    socket.leave(room);
    const __createdtime__ = Date.now();
    // Remove user from memory
    allUsers = leaveRoom(socket.id, allUsers);
    socket.to(room).emit('chatroom_users', allUsers);
    socket.to(room).emit('receive_message', {
      username: CHAT_BOT,
      message: `${username} has left the chat`,
      __createdtime__,
    });
    console.log(`${username} has left the chat`);
  });
});

server.listen(4000, () => 'Server is running on port 3000');

We now need to create the leaveRoom() function:

// server/utils/leave-room.js

function leaveRoom(userID, chatRoomUsers) {
  return chatRoomUsers.filter((user) => user.id != userID);
}

module.exports = leaveRoom;

Why put this short function in a separate utils folder, you ask? Because we'll be using it again later on and we don't want to repeat ourselves (keeping our code DRY).

Let's test things out: open up two windows side-by-side, and join the chat on both:

Then click the leave button on window 2:

The user is removed from the chat, and a message is sent to the other users – notifying them that they've left. Nice!

How to Add the Socket.io Disconnect Event Listener

What if the user is somehow disconnected from the server, like if their internet drops? Socket.io provides a built-in disconnect event listener for this. Let's add that into our server to remove a user from memory when they disconnect:

// server/index.js

// ...

// Listen for when the client connects via socket.io-client
io.on('connection', (socket) => {

  // ...

  // Add this
  socket.on('disconnect', () => {
    console.log('User disconnected from the chat');
    const user = allUsers.find((user) => user.id == socket.id);
    if (user?.username) {
      allUsers = leaveRoom(socket.id, allUsers);
      socket.to(chatRoom).emit('chatroom_users', allUsers);
      socket.to(chatRoom).emit('receive_message', {
        message: `${user.username} has disconnected from the chat.`,
      });
    }
  });
});

server.listen(4000, () => 'Server is running on port 3000');

And there you have it – you've just built a fullstack realtime chat application with a React frontend, a Node/Express backend, and a HarperDB database. Nice job!

Next time, I plan to check out HarperDB’s Custom Functions, which enable users to define their own API endpoints within HarperDB. This means that we can build our entire application in one place! See an example of how HarperDB is collapsing the stack in this article.

A challenge for you 💪

If you refresh the Chat page, the user's username and room will be lost. See if you can prevent this info from being lost when the user refreshes the page. Clue: local storage could be useful!

Thank you for reading!

If you found this article useful, you can:

• Subscribe to my YouTube channel. I will be uploading in-depth tutorials and project videos on React/NextJS/Node/Express.
• Follow me on Twitter where I tweet about my freelancing journey, side projects, and current learnings.
• Checkout my Gumroad store where I make useful and popular (8000 downloads as of writing) cheatsheets and posters.
• Checkout my web dev blog

So, in this article, I'll show you how to do all of those things using NextJS and HarperDB.

We'll be building a full stack task timer app that includes JSON Web Token Authentication, fetching data using HarperDB's built-in API, and rendering the data with NextJS. We will also make use of NextJS's API.

If you're wondering what HarperDB is, it's a database-as-a-service that allows you to query data using either SQL or NoSQL. HarperDB also has a built-in API, saving us from having to write a lot of backend code.

Here is what we'll be building.

Here is the source code (remember to give it a star ⭐).

Contents

• Setup
• Create the Layout component
• Create some reusable components
• Create the Signup Page
• How to log out the user
• The Login Page
• Create a Tasks Context
• Create the Task Timer Page
• Create the Add/Select Task Bar
• Create the Stats Page

Setup

1. Install NextJS with TypeScript:

npx create-next-app@latest --ts

You’ll then be asked for a project name. I’m calling it “task timer”.

We can then change to the project directory:

cd “task timer”

2. Install and set up TailwindCSS

We'll be styling this project with Tailwind, so let's install everything we'll need.

Install TailwindCSS and its peer dependencies via npm, and then run the init command to generate both tailwind.config.js and postcss.config.js:

npm install -D tailwindcss postcss autoprefixer
npx tailwindcss init -p

Add the paths to all of your React component files in your tailwind.config.js file:

module.exports = {
  content: [
    "./src/pages/**/*.{js,ts,jsx,tsx}",
    "./src/components/**/*.{js,ts,jsx,tsx}",
  ],
  theme: {
    extend: {},
  },
  plugins: [],
}

Next, create a src folder in the project root, and drag the styles and pages folders into src. In styles/global.css, add the following Tailwind directives to bring in the Tailwind classes:

@tailwind base;
@tailwind components;
@tailwind utilities;

Our NextJS project is now set up and ready to use with Tailwind.

Let's clear out our src/pages/index.tsx page, and add the following:

import type { NextPage } from "next"

const Home: NextPage = () => {
  return (
    <div>
      <h1 className="text-red-500">Hello World</h1>
    </div>
  )
}

export default Home

Run the build process and start the dev server with:

npm run dev

Our server will now be running on http://localhost:3000

3. Set up HarperDB

First, create an account with HarperDB.

Then create a new HarperDB cloud instance:

To make things easy, select the cloud instance:

Select the cloud provider (I chose AWS):

Name your cloud instance, and create your instance credentials:

HarperDB has a generous free tier that we can use for this project, so select that:

Check your details are correct, then create the instance.

It will take a few minutes to create the instance, so let's crack on and make the UI for our app!

Create a Layout Component to Wrap Every Page

Create the folder src/components. In here, we will create components that can be reused throughout the project.

First, let's create a file to hold any constants that will be used through our app, such as the site title. It's helpful to keep a single source of truth for values like this, so that if we want to change them, we only have to change them in one place.

// src/constants/constants.ts

export const SITE_TITLE = "Super Simple Task Timer"

Let's now create our navbar:

// src/components/layout/Navbar.tsx

import Link from "next/link"
import { SITE_TITLE } from "../../constants/constants"

const Navbar = () => {
  return (
    <header className="flex justify-between items-center bg-green-600 text-white py-4 px-4">
      <h2 className="text-lg">
        <Link href="/">
          <a>{SITE_TITLE}</a>
        </Link>
      </h2>
      <nav>
        <ul className="flex">
          <NavLink href="/login">Login</NavLink>
          <NavLink href="/signup">Signup</NavLink>
        </ul>
      </nav>
    </header>
  )
}

interface NavLinkProps {
  href: string
  children: string
}

const NavLink: React.FC<NavLinkProps> = ({ href, children }) => {
  return (
    <li className="ml-8">
      <Link href={href}>
        <a>{children}</a>
      </Link>
    </li>
  )
}

export default Navbar

Create the footer:

// src/components/layout/Footer.tsx

import { SITE_TITLE } from "../../constants/constants"

const Footer = () => {
  return (
    <footer className="bg-green-600 text-white text-center py-4">
      <p className="mb-1">{SITE_TITLE} &copy;</p>
      <p>Designed & developed by Danny Adams</p>
    </footer>
  )
}

export default Footer

Now we can create our layout component to wrap every page. Using flex-grow on the <main> tag ensures that the page content takes up all available space between the header and footer.

// src/components/layout/Layout.tsx

import Navbar from "./Navbar"
import Footer from "./Footer"

const Layout: React.FC = ({ children }) => {
  return (
    <div className="min-h-screen flex flex-col">
      <Navbar />
      <main className="flex flex-col grow">{children}</main>
      <div className="mt-auto">
        <Footer />
      </div>
    </div>
  )
}

export default Layout

Then, in src/pages/_app.tsx, we can wrap every page component with Layout:

import "../styles/globals.css"
import type { AppProps } from "next/app"
import Layout from "../components/layout/Layout"

function MyApp({ Component, pageProps }: AppProps) {
  return (
    <Layout>
      <Component {...pageProps} />
    </Layout>
  )
}

export default MyApp

And there we go! Every page now has a navbar, content area that takes up 100% of available space, and a footer that always sits at the bottom.

Create Some Reusable Components

We will now create some basic components that can be reused throughout the project.

Create a button component:

// src/components/Button.tsx

interface Props {
  children: React.ReactNode
  color: "primary" | "success" | "secondary" | "warning" | "danger"
  handleClick?: () => void
  type?: "button" | "submit"
  extraClasses?: string
}

const Button: React.FC<Props> = ({
  children,
  color,
  handleClick,
  type,
  extraClasses,
}) => {
  let colors: string
  switch (color) {
    case "primary":
      colors = "bg-blue-500 hover:bg-blue-600"
      break
    case "success":
      colors = "bg-green-500 hover:bg-green-600"
      break
    case "warning":
      colors = "bg-yellow-300 hover:bg-yellow-400 text-black"
      break
    case "secondary":
      colors = "bg-pink-500 hover:bg-pink-600"
      break
    default:
      colors = "bg-red-500 hover:bg-red-600"
  }
  const classes = `rounded text-white py-2 px-4 ${colors} ${extraClasses}`

  return (
    <button className={classes} onClick={handleClick} type={type}>
      {children}
    </button>
  )
}

export default Button

Create a link component that uses NextJS Link to automatically prefetch pages it links to in the background - making page loads quickly:

// src/components/Link.tsx

import NextLink from "next/link"

interface Props {
  href: string
  children: React.ReactNode
}

const Link = ({ href, children }: Props) => {
  return (
    <NextLink href={href}>
      <a className="underline underline-offset-1 text-blue-700">{children}</a>
    </NextLink>
  )
}

export default Link

Let's also create an Alert component to display alert messages, for example if a user enters invalid form data, a red error message will be displayed:

// src/components/Alert.tsx

interface Props {
  children: React.ReactNode
  type: "success" | "warning" | "danger"
  key?: number
  extraClasses?: string
}
const Alert = ({ children, type, key, extraClasses }: Props) => {
  let color
  switch (type) {
    case "success":
      color = "bg-blue-500"
      break
    case "warning":
      color = "bg-yellow-300 text-yellow-800"
      break
    default:
      color = "bg-red-500"
  }
  const classes = `text-white text-center p-2 rounded mt-4 ${color} ${extraClasses}`

  return (
    <div key={key} className={classes}>
      {children}
    </div>
  )
}

export default Alert

Create a main page heading component:

// src/components/PageHeading.tsx

interface Props {
  extraClasses: string
}

const PageHeading: React.FC<Props> = ({ children, extraClasses }) => {
  const classes = "text-4xl text-green-900 font-semibold " + extraClasses

  return <h1 className={classes}>{children}</h1>
}

export default PageHeading

Let's also create a component to reuse through our login and signup forms that contains a label and an input:

// src/components/Form.tsx

interface InputProps {
  inputType: "text" | "email" | "password"
  inputName: string
  handleChange: (e: React.ChangeEvent<HTMLInputElement>) => void
  value: string
}

interface LabelAndInputProps extends InputProps {
  label: string
}

export const LabelAndInput: React.FC<LabelAndInputProps> = ({
  label,
  inputType,
  inputName,
  handleChange,
  value,
}) => {
  return (
    <div className="flex flex-col mb-2">
      <label htmlFor="name">{label}</label>
      <Input
        inputType={inputType}
        inputName={inputName}
        handleChange={handleChange}
        value={value}
      />
    </div>
  )
}

export const Input: React.FC<InputProps> = ({
  inputType,
  inputName,
  handleChange,
  value,
}) => {
  return (
    <input
      className="px-3 py-2 border-gray-200 border-2 rounded"
      type={inputType}
      name={inputName}
      id={inputName}
      onChange={handleChange}
      value={value}
    />
  )
}

Create the Signup Page

Here is what the signup page will look like.

Signup page UI

First, let's create a signup form component at the location src/components/signup-page/SignupForm.tsx:

// src/components/signup-page/SignupForm.tsx

import { useState } from "react"
import { LabelAndInput } from "../Form"
import Button from "../Button"

const SignupForm = () => {
  const [username, setUsername] = useState("")
  const [password1, setPassword1] = useState("")
  const [password2, setPassword2] = useState("")

  return (
    <form className="w-full sm:w-96">
      <LabelAndInput
        label="Username"
        inputType="text"
        inputName="username"
        handleChange={e => setUsername(e.target.value)}
        value={username}
      />
      <LabelAndInput
        label="Password"
        inputType="password"
        inputName="password1"
        handleChange={e => setPassword1(e.target.value)}
        value={password1}
      />
      <LabelAndInput
        label="Confirm password"
        inputType="password"
        inputName="password2"
        handleChange={e => setPassword2(e.target.value)}
        value={password2}
      />
      <Button
        color="success"
        type="submit"
        extraClasses="w-full mt-3 py-3 font-semibold"
      >
        Create Account
      </Button>
    </form>
  )
}

export default SignupForm

We can create the signup page at src/pages/signup.tsx and import the above form:

// src/pages/signup.tsx

import type { NextPage } from "next"
import SignupForm from "../components/signup-page/SignupForm"
import PageHeading from "../components/PageHeading"

const Signup: NextPage = () => {
  return (
    <div className="mx-auto mt-20">
      <PageHeading extraClasses="text-center mb-8">
        Create an account
      </PageHeading>
      <SignupForm />
    </div>
  )
}

export default Signup

Our signup page UI is now complete:

Signup page logic

Back in our SignupForm component, add a handleSubmit callback function to be called when then form is submitted:

// src/components/signup-page/SignupForm.tsx

<form className='w-full sm:w-96' onSubmit={handleSubmit}>

In the handleSubmit function, we'll need to post the form data to our NextJS API. Our API will then forward this data on to HarperDB to create a new user in our HarperDB database.

Let's first write the beginning of our handleSubmit function:

// src/components/signup-page/SignupForm.tsx

// ...
import { postFormData } from "../../utils/postFormData"

const SignupForm = () => {
  // ...

  const handleSubmit = async (e: React.FormEvent) => {
    e.preventDefault();

    const formData = { username, password1, password2 };
    const { response, result } = await postFormData(formData, '/api/signup');

    console.log({ response, result });
  };

Now create a src/utils folder, and define a utility function that takes any data object and an API route, then returns the response and result:

// src/utils/postFormData.ts

export const postFormData = async (data: { [k: string]: any }, url: string) => {
  const requestOptions: RequestInit = {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
    },
    body: JSON.stringify(data),
  }
  const response = await fetch(url, requestOptions)
  const result = await response.json()
  return { response, result }
}

We need to create our first API route at src/pages/api/signup.

But before we do that, we will install the next-connect package, which allows us to write our APIs with expressJS-like syntax, and saves us some time with error handling:

npm install next-connect

Create a file at src/middleware/_defaultHandler.ts, and add the following:

// src/middleware/_defaultHandler.ts

import { NextApiRequest, NextApiResponse } from "next"
import nextConnect from "next-connect"

// This middleware function will run between every request and api handler
const handler = nextConnect<NextApiRequest, NextApiResponse>({
  onError: (err, req, res) => {
    res.status(501).json({ error: `Something went wrong! ${err.message}` })
  },
  onNoMatch: (req, res) => {
    res.status(405).json({ error: `Method ${req.method} Not Allowed` })
  },
})

export default handler

The above middleware function will run with every API request, and handle any request errors.

We can now create our API route at src/pages/api/signup. First, let's check for any errors in the posted form data, and send back an array of error messages to the client if so:

// src/pages/api/signup

import type { NextApiRequest, NextApiResponse } from "next"
import handler from "../../middleware/_defaultHandler"

export default handler.post(
  async (req: NextApiRequest, res: NextApiResponse) => {
    const { username, password1, password2 } = req.body

    const errors: string[] = getFormErrors(username, password1, password2)
    if (errors.length > 0) {
      return res.status(400).json({ error: errors })
    }
  }
)

const getFormErrors = (
  username: string,
  password1: string,
  password2: string
) => {
  const errors: string[] = []
  if (!username || !password1 || !password2) {
    errors.push("All fields are required")
  }
  if (password1.length < 6) {
    errors.push("Password must be at least 6 characters")
  }
  if (password1 !== password2) {
    errors.push("Passwords do not match")
  }
  return errors
}

Now, if we post some incorrect form data from the frontend, we get error messages logged to the console:

Once we know the form data is legit, we need to post it to the HarperDB API, which will create a new user for us. Let's write a function that will do this.

First, we need our HarperDB instance URL. If you click on your instance, then go to "config", you will find your instance URL, and your instance API Auth Header – that is, your "super_user" password that allows you to make any request to the database – FOR YOUR EYES ONLY!

We will be needing the instance URL on both frontend and backend, so let's store it in our constants file:

// src/constants/constants.ts

export const SITE_TITLE = "Super Simple Task Timer"
export const DB_URL = "Your_HDB_URL_Here"

Our password must be kept secret, so it should never be available on the frontend. Our password will be loaded into the server as an environment variable. Add your password to .env.local in your project root:

HARPERDB_PW=Basic yourpasswordgoeshere

HarperDB lists all of the operations that can be performed by category in the "example code" tab:

We want to use the HarperDB "add_user" operation, so let's create our own function to do just that:

// src/utils/harperdb/createNewUser.ts

import { DB_URL } from "../../constants/constants"

// This function can only be ran on the backend as it requires a "super_user" password
export const harperCreateNewUser = async (
  username: string,
  password: string
) => {
  const DB_PW = process.env.HARPERDB_PW
  if (!DB_URL || !DB_PW) {
    console.log("Error: .env variables are undefined")
    throw "Internal server error"
  }
  const myHeaders = new Headers()
  myHeaders.append("Content-Type", "application/json")
  myHeaders.append("Authorization", DB_PW)
  const raw = JSON.stringify({
    operation: "add_user",
    role: "standard_user",
    username: username.toLowerCase(),
    password: password,
    active: true,
  })
  const requestOptions: RequestInit = {
    method: "POST",
    headers: myHeaders,
    body: raw,
    redirect: "follow",
  }

  const response = await fetch(DB_URL, requestOptions)
  const result = await response.json()
  return { response, result }
}

Notice how the "role" is "standard_user". If we gave everyone that created an account a "super_user" role, then anybody would be able to delete your tables and wreak havoc on our database!

Let's now set up this "standard_user" role, and make the tables we will need.

Create a scheme called "productivity_timer" (a schema is a group of tables). In this schema, create a table called "tasks" with hash attribute (each entries unique key) "id":

We now need to create the "standard_user" role to limit the access that our users will have. Go to "roles", and create a standard role called "standard_user". Then change all the tasks table access permissions to true:

Let's also add some tasks to our table that we can fetch into our application later:

Add the following JSON to add some tasks:

[
  { "username": "dan", "task_name": "make header", "time_in_seconds": 0 },
  { "username": "dan", "task_name": "make footer", "time_in_seconds": 0 },
  { "username": "sally", "task_name": "learn NextJS", "time_in_seconds": 0 }
]

Back to our API route at src/pages/api/signup, we can now add the code to create a new user in HarperDB:

// src/pages/api/signup

import type { NextApiRequest, NextApiResponse } from "next"
import handler from "../../middleware/_defaultHandler"
import { harperCreateNewUser } from "../../utils/harperdb/createNewUser"

export default handler.post(
  async (req: NextApiRequest, res: NextApiResponse) => {
    const { username, password1, password2 } = req.body

    const errors: string[] = getFormErrors(username, password1, password2)
    if (errors.length > 0) {
      return res.status(400).json({ error: errors })
    }

    // Create new user with HarperDB, and send back result
    try {
      const { response, result } = await harperCreateNewUser(
        username,
        password1
      )
      return res.status(response.status).json(result)
    } catch (err) {
      return res.status(500).json({ error: err })
    }
  }
)

To test creating a new user, you will now need to stop the dev server with "ctrl + c", then restart with npm run dev – in order to load in the .env variables.

Go to the signup page, fill in the form, and submit. WOOHOO! We have created our first user!

And if we look in the users table on HarperDB, we see that the new user was added successfully:

Now, back on the frontend, we need to handle the response and result that is sent back from the server.

If the response status code sent back from the server is not 200, we know that something went wrong. So we can set the errors in a state variable, and return from handleSubmit early:

// src/components/signup-page/SignupForm.tsx

const [errors, setErrors] = useState<string | string[]>("")

const handleSubmit = async (e: React.FormEvent) => {
  e.preventDefault()
  setErrors("")

  const formData = { username, password1, password2 }
  const { response, result } = await postFormData(formData, "/api/signup")

  // Account not created successfully
  if (response.status !== 200) {
    setErrors(result.error)
    return
  }
}

Let's display these errors at the bottom of the form:

// src/components/signup-page/SignupForm.tsx

// ...
import Alert from "../Alert"

const SignupForm = () => {
  // ...
  const [errors, setErrors] = useState<string | string[]>("")

  // ...

  const displayErrors = () => {
    if (errors.length === 0) return

    return typeof errors === "string" ? (
      <Alert type="danger">{errors}</Alert>
    ) : (
      errors.map((err, i) => (
        <Alert key={i} type="danger">
          {err}
        </Alert>
      ))
    )
  }

  return (
    <form className="w-full sm:w-96" onSubmit={handleSubmit}>
      {/* form stuff... */}

      {displayErrors()}
    </form>
  )
}

export default SignupForm

Now if the user enters invalid form data, errors will be displayed:

And if the user already exists, HarperDB will send us an appropriate error message:

Nice!

But if the response status code is 200, then we know that the account was created successfully. So, we can get the user a JSON Web Token (JWT) which will be used to authenticate the user and allow them to access protected routes.

How to get the user a JSON Web Token

HarperDB can create JWTs for each user in the database, meaning we don't have to install any packages and handle the logic ourselves - nice!

How will our JWT auth work? When HarperDB sends back a JWT to the frontend, we will save the JWT in localStorage in the browser. Then, every time the user makes a request, we will get the JWT from localStorage and attach it to the request header. HarperDB will automatically check if there is a JWT in the request header, and check that it is valid. If so, it will go ahead with the request.

But first, we need to create a User context using React's context API so that the user's username is available throughout the whole of the app.

// src/contexts/UserContext.ts

import { createContext } from "react"

export const UserContext = createContext({
  username: "",
  setUsername: (username: string) => {},
})

We then need to wrap our whole application in the UserContext.Provider, so username and setUsername are available on every page. Initially, username will be an empty string.

// src/pages/_app.tsx

import { useState } from "react"
// ...
import { UserContext } from "../contexts/UserContext"

function MyApp({ Component, pageProps }: AppProps) {
  const [username, setUsername] = useState("")

  return (
    <UserContext.Provider value={{ username, setUsername }}>
      <Layout>
        <Component {...pageProps} />
      </Layout>
    </UserContext.Provider>
  )
}

export default MyApp

Let's now write a function that will fetch JWTs from HarperDB. HarperDB will check that the username and password are correct, then create the JWTs from the username, and send them back to our app:

// src/utils/harperdb/fetchJWTTokens.ts

import { DB_URL } from "../../constants/constants"

export const harperFetchJWTTokens = async (
  username: string,
  password: string
) => {
  if (!DB_URL) {
    console.log("Error: DB_URL undefined")
    throw "Internal server error"
  }

  const myHeaders = new Headers()
  myHeaders.append("Content-Type", "application/json")

  const raw = JSON.stringify({
    operation: "create_authentication_tokens",
    username: username,
    password: password,
  })

  const requestOptions: RequestInit = {
    method: "POST",
    headers: myHeaders,
    body: raw,
    redirect: "follow",
  }

  const response = await fetch(DB_URL, requestOptions)
  const result = await response.json()
  return { response, result }
}

Back to SignupForm.tsx, we need to fetch the JWTs using the above function, check if HarperDB created and sent them back successfully, and if so authenticate the user:

// src/components/signup-page/SignupForm.tsx

import { useState, useContext } from "react"
import { UserContext } from "../../contexts/UserContext"
import { useRouter } from "next/router"
import { harperFetchJWTTokens } from "../../utils/harperdb/fetchJWTTokens"
// ...

const SignupForm = () => {
  //...

  const user = useContext(UserContext)
  const router = useRouter()

  const handleSubmit = async (e: React.FormEvent) => {
    // ...

    // Account created successfully; get JWTs
    try {
      const { response, result } = await harperFetchJWTTokens(
        username,
        password1
      )
      const accessToken = result.operation_token
      if (response.status === 200 && accessToken) {
        authenticateUser(username, accessToken)
      } else {
        // Account created, but failed to get JWTs
        // Redirect to login page
        router.push("/login")
      }
    } catch (err) {
      console.log(err)
      setErrors("Whoops, something went wrong :(")
    }
  }

  const authenticateUser = (username: string, accessToken: string) => {
    user.setUsername(username)
    localStorage.setItem("access_token", accessToken)
  }

  // ...
}

export default SignupForm

Above, if HarperDB sends back the operation token successfully, we save it to localStorage so it can be used to authenticate the user for as long as the JWT hasn't expired, and set the username in context.

Let's test this out. When we create a new user we should get an access token stored in localStorage. Create a new user, open your chrome dev tools, then under "Application" you should see the access token.

Awesome!

In src/pages/signup.tsx, let's render a different component depending on if the username is set:

// src/pages/signup.tsx

import { useContext } from "react"
import { UserContext } from "../contexts/UserContext"
import Alert from "../components/Alert"
// ...

const Signup: NextPage = () => {
  const { username } = useContext(UserContext)

  return (
    <div className="mx-auto mt-20">
      {username ? (
        <Alert type="success">You are logged in as {username}</Alert>
      ) : (
        <>
          <PageHeading extraClasses="text-center mb-8">
            Create an account
          </PageHeading>
          <SignupForm />
        </>
      )}
    </div>
  )
}

export default Signup

Now when we create an account, we get this:

But we have a problem: context doesn't keep the username when we refresh the page, meaning when we refresh the page, the signup form will be displayed again, even though the user is logged in.

To solve this problem, we can create a custom hook called useUser.

Creating a useUser custom hook

The useUser hook will run once every time the user goes to a new page, or refreshes the current page.

Let's first create the hook. We will also move username and setUsername into this hook to keep things organized.

// src/custom-hooks/useUser.ts

import { useState, useEffect } from "react"
import { harperGetUsername } from "../utils/harperdb/getUsername"

export const useUser = () => {
  const [username, setUsername] = useState("")

  useEffect(() => {
    // User is logged in
    if (username) return

    // Check for access token and try to log user in
    const accessToken = localStorage.getItem("access_token")
    if (accessToken) {
      tryLogUserIn(accessToken)
    }

    async function tryLogUserIn(accessToken: string) {
      const username = await harperGetUsername(accessToken)
      if (username) {
        setUsername(username)
      }
    }
  })

  return { username, setUsername }
}

Now we need to create the harperGetUsername function. This function will send the access token to HarperDB. HarperDB will then check if the access token is valid, and check which user it belongs to. If all is good, then HarperDB will send back the corresponding user's info.

// src/utils/harperdb/getUsername.ts

import { DB_URL } from "../../constants/constants"

export const harperGetUsername = async (accessToken: string) => {
  const myHeaders = new Headers()
  myHeaders.append("Content-Type", "application/json")
  myHeaders.append("Authorization", "Bearer " + accessToken)

  const raw = JSON.stringify({
    operation: "user_info",
  })

  const requestOptions: RequestInit = {
    method: "POST",
    headers: myHeaders,
    body: raw,
    redirect: "follow",
  }

  try {
    const response = await fetch(DB_URL, requestOptions)
    const result = await response.json()
    if (response.status === 200) {
      return result.username
    }
  } catch (err) {
    console.log(err)
  }
  return null
}

Our useUser hook is made. Let's instantiate it in _app.tsx so that every time a new page is visited, the useEffect function will run and authenticate the user:

// src/pages/_app.tsx

// ...
import { useUser } from "../custom-hooks/useUser"

function MyApp({ Component, pageProps }: AppProps) {
  // Remove below line
  // const [username, setUsername] = useState('');
  const { username, setUsername } = useUser()

  return (
    <UserContext.Provider value={{ username, setUsername }}>
      <Layout>
        <Component {...pageProps} />
      </Layout>
    </UserContext.Provider>
  )
}

export default MyApp

Now when we refresh the page, the user's username is fetched using the access JWT stored in localStorage, keeping our user logged in. Awesome!

Logged in alert

How to Log Out the User

The auth system we are implementing is "stateless" – meaning that no information will be stored in the database or on the server that tells us who is logged in and who isn't. Just an access JWT is stored on the client to authenticate users.

The only way we have of logging out a user is by deleting the access token in the user’s localStorage. Of course, if they are logged in on multiple devices, then they can only log out of the device they are on.

Also, if the access token was stolen, then anybody could pretend to be that user and access their data. This is a major weakness in our auth system.

One way to solve this would be to use refresh tokens, but we'll keep things simple in this tutorial and just use one JWT for accessing protected routes.

In our Navbar components, let's add a logout button. We will use a ternary operator to display the "Login" and "Signup" links if username isn't set. If username is set, then the user is logged in so we can show them links to the "Timer" and "Stats" pages, as well as the "Logout" button.

// src/components/layout/Navbar.tsx

import Link from "next/link"
import { useContext } from "react"
import { SITE_TITLE } from "../../constants/constants"
import { UserContext } from "../../contexts/UserContext"

const Navbar = () => {
  const { username, setUsername } = useContext(UserContext)

  const handleLogout = () => {
    localStorage.removeItem("access_token")
    setUsername("")
  }

  return (
    <header className="flex justify-between items-center bg-green-600 text-white py-4 px-4">
      <h2 className="text-lg">
        <Link href="/">
          <a>{SITE_TITLE}</a>
        </Link>
      </h2>
      <nav>
        <ul className="flex items-center">
          {username ? (
            <>
              <NavLink href="/">Timer</NavLink>
              <NavLink href="/stats">Stats</NavLink>
              <button
                onClick={handleLogout}
                className="border py-1 px-3 ml-8 rounded hover:bg-green-700"
                type="button"
              >
                Logout
              </button>
            </>
          ) : (
            <>
              <NavLink href="/login">Login</NavLink>
              <NavLink href="/signup">Signup</NavLink>
            </>
          )}
        </ul>
      </nav>
    </header>
  )
}
// ...

The Login page

Here is the login page we'll be building in this section.

Login page UI

Let's make the UI for the login page. First:

// src/pages/login.tsx

import { useContext } from "react"
import type { NextPage } from "next"
import { UserContext } from "../contexts/UserContext"
import PageHeading from "../components/PageHeading"
import LoginForm from "../components/login-page/LoginForm"

const Login: NextPage = () => {
  const { username } = useContext(UserContext)

  return (
    <div className="grow flex flex-col items-center mt-20">
      {username ? (
        <p>
          You are logged in as{" "}
          <span className="text-green-600 font-semibold">{username}</span> 👋
        </p>
      ) : (
        <>
          <PageHeading extraClasses="text-center mb-8">Log in</PageHeading>
          <LoginForm />
        </>
      )}
    </div>
  )
}

export default Login

Next, create LoginForm:

// src/components/login-page/LoginForm.tsx

import { useState } from "react"
import { LabelAndInput } from "../Form"
import Button from "../Button"
import Alert from "../Alert"

const LoginForm = () => {
  const [username, setUsername] = useState("")
  const [password, setPassword] = useState("")

  return (
    <form className="w-full sm:w-96">
      <LabelAndInput
        label="Username"
        inputType="text"
        inputName="username"
        handleChange={e => setUsername(e.target.value)}
        value={username}
      />
      <LabelAndInput
        label="Password"
        inputType="password"
        inputName="password"
        handleChange={e => setPassword(e.target.value)}
        value={password}
      />
      <Button color="success" extraClasses="w-full mt-3 py-3 font-semibold">
        Login
      </Button>

      {error && <Alert type="danger">{error}</Alert>}
    </form>
  )
}

export default LoginForm

Now we can create a handleSubmit function on our login form:

// src/components/login-page/LoginForm.tsx

import { useState, useContext } from "react"
// ...
import { UserContext } from "../../contexts/UserContext"

const LoginForm = () => {
  // ...
  const [error, setError] = useState("")
  const user = useContext(UserContext)

  const handleSubmit = (e: React.FormEvent) => {
    e.preventDefault()
    setError("")
  }

  return (
    <form className="w-full sm:w-96" onSubmit={handleSubmit}>
      {/* ... */}
    </form>
  )
}

export default LoginForm

Completing the rest of our handleSubmit function:

// src/components/login-page/LoginForm.tsx

const handleSubmit = async (e: React.FormEvent) => {
  e.preventDefault()
  setError("")
  if (!username || !password) {
    setError("Username and password required")
    return
  }

  try {
    const { response, result } = await harperFetchJWTTokens(username, password)
    const { status } = response
    const accessToken = result.operation_token
    if (status === 200 && accessToken) {
      authenticateUser(username, accessToken)
    } else if (status === 401) {
      setError("Check your username and password are correct")
    } else {
      setError("Whoops, something went wrong :(")
    }
  } catch (err) {
    console.log(err)
    setError("Whoops, something went wrong :(")
  }
}

const authenticateUser = (username: string, accessToken: string) => {
  user.setUsername(username)
  localStorage.setItem("access_token", accessToken)
}

Now if we enter the details of a user not in our database, we get an error:

If we log in as a user that exists:

We can now create an account and log in to our app. Awesome!

Create a Tasks Context

Our timer page ('/') and our stats page ('/stats') will both need to know the tasks that the user has added, as well as the number of seconds the user has spent on each task. We can share the tasks state between pages using the context API.

First, let's create a type for tasks so that TypeScript can tell us if a task is missing a property, or if we try to access a property that doesn't exist on tasks, making our code more robust:

// src/types/Task.ts

export interface Task {
  __createdtime__: number
  __updatedtime__: number
  username: string
  time_in_seconds: number
  id: string
  task_name: string
}

Next, we can create our tasks context:

// src/contexts/TasksContext.ts

import React, { createContext } from "react"
import type { Task } from "../types/Task"

interface TasksContext {
  tasks: Task[]
  setTasks: React.Dispatch<React.SetStateAction<Task[]>>
  getAndSetTasks: (username: string) => Promise<void>
}

export const TasksContext = createContext({} as TasksContext)

Before we wrap our application with the tasks context provider, let's create a custom hook that will contain a useEffect hook that will run every time a new page is visited, or every time a page is refreshed. It will check if the user is logged in, and if the tasks state contains no tasks, it will try to fetch tasks from the database:

// src/custom-hooks/useTasks.ts

import { useState, useCallback, useEffect } from "react"
import type { Task } from "../types/Task"
import { harperGetTasks } from "../utils/harperdb/getTasks"

export const useTasks = (username: string) => {
  const [tasks, setTasks] = useState<Task[]>([])

  // Get tasks from db then set task state
  const getAndSetTasks = useCallback(
    async (username: string) => {
      try {
        const tasks: Task[] = await harperGetTasks(username)
        setTasks(tasks)
      } catch (err) {
        console.log(err)
      }
    },
    [setTasks]
  )

  useEffect(() => {
    if (!username || tasks.length > 0) return
    getAndSetTasks(username)
  }, [username, tasks.length, getAndSetTasks])

  return { tasks, setTasks, getAndSetTasks }
}

Now we need to define the harperGetTasks function to fetch all tasks from the database that have our user's username. As you can see, HarperDB supports both SQL and NoSQL operations. We are ordering the tasks with the ones the user most recently worked on at the top:

// src/utils/harperdb/getTasks.ts

import { harperFetch } from "./harperFetch"

export const harperGetTasks = async (username: string) => {
  const data = {
    operation: "sql",
    sql: `SELECT * FROM productivity_timer.tasks WHERE username = '${username}' ORDER BY __updatedtime__ DESC`,
  }

  const { result } = await harperFetch(data)
  return result
}

All of our HarperDB functions from now on include the same boilerplate, so I created a harperFetch utility function to keep the code DRY:

// src/utils/harperFetch.ts

import { DB_URL } from "../../constants/constants"

export const harperFetch = async (data: { [key: string]: any }) => {
  const accessToken = localStorage.getItem("access_token")
  if (!accessToken) throw { error: "You need to log in" }

  const myHeaders = new Headers()
  myHeaders.append("Content-Type", "application/json")
  myHeaders.append("Authorization", "Bearer " + accessToken)

  const raw = JSON.stringify(data)

  const requestOptions: RequestInit = {
    method: "POST",
    headers: myHeaders,
    body: raw,
    redirect: "follow",
  }

  const response = await fetch(DB_URL, requestOptions)
  const result = await response.json()
  return { response, result }
}

OK, let's now give all pages in our application access to the tasks state:

// src/pages/_app.tsx

// ...
import { TasksContext } from "../contexts/TasksContext"
import { useTasks } from "../custom-hooks/useTasks"

function MyApp({ Component, pageProps }: AppProps) {
  // ...
  const { tasks, setTasks, getAndSetTasks } = useTasks(username)

  console.log(tasks)

  return (
    <UserContext.Provider value={{ username, setUsername }}>
      <TasksContext.Provider value={{ tasks, setTasks, getAndSetTasks }}>
        <Layout>
          <Component {...pageProps} />
        </Layout>
      </TasksContext.Provider>
    </UserContext.Provider>
  )
}

export default MyApp

Now, I am logged in as "dan", so I should now see all of dan's tasks console.logged – and I do:

Create the Task Timer Page

The homepage UI needs to look like this:

The top row is where the user can select one of their tasks stored in the database from a dropdown menu. They can also add a new task to the database.

Then below, we have the timer that will track how long the user has spent on each task.

Here is the page we'll be building in this section.

Create the Add/Select Taskbar

Let's first create the select or add a task row, making it as a component to be imported into the home page:

// src/components/home-page/Taskbar.tsx

import { useState, useContext } from "react"
import { harperAddNewTask } from "../../utils/harperdb/addNewTask"
import { UserContext } from "../../contexts/UserContext"
import { TasksContext } from "../../contexts/TasksContext"
import Button from "../Button"

interface Props {
  selectedTaskId: string
  setSelectedTaskId: React.Dispatch<React.SetStateAction<string>>
  setErrorMessage: React.Dispatch<React.SetStateAction<string>>
  setSeconds: React.Dispatch<React.SetStateAction<number>>
  pauseTimer: () => void
}

const TaskBar = ({
  selectedTaskId,
  setSelectedTaskId,
  setErrorMessage,
  setSeconds,
  pauseTimer,
}: Props) => {
  const { username } = useContext(UserContext)
  const { tasks, getAndSetTasks } = useContext(TasksContext)

  const [isUserAddingNewTask, setIsUserAddingNewTask] = useState(false)
  const [taskInputValue, setTaskInputValue] = useState("")

  const handleChangeTaskInput = (e: { target: HTMLInputElement }) => {
    setTaskInputValue(e.target.value)
  }

  const handleSelectTask = (e: { target: HTMLSelectElement }) => {
    setErrorMessage("")
    setSelectedTaskId(e.target.value)
    setSeconds(0)
    pauseTimer()
  }

  const handleClickAddNewTask = () => {
    if (taskInputValue.trim() === "") {
      setErrorMessage("Type a task!")
      return
    }
    addNewTask()
    resetAddingNewTask()
  }

  const addNewTask = async () => {
    try {
      const { response } = await harperAddNewTask(username, taskInputValue)
      if (response.status === 200) {
        // Task added to db successfully
        getAndSetTasks(username)
      } else setErrorMessage("Whoops, something went wrong")
    } catch (err) {
      console.log(err)
      setErrorMessage("Whoops, something went wrong")
    }
  }

  const resetAddingNewTask = () => {
    setTaskInputValue("")
    setIsUserAddingNewTask(false)
  }

  return (
    <div>
      {isUserAddingNewTask ? (
        <>
          <input
            type="text"
            placeholder="Enter task here..."
            value={taskInputValue}
            onChange={handleChangeTaskInput}
            className="border p-2 mr-2"
          />
          <Button color="primary" handleClick={handleClickAddNewTask}>
            Add task
          </Button>
          <Button
            color="secondary"
            handleClick={() => setIsUserAddingNewTask(false)}
            extraClasses="ml-1"
          >
            Cancel
          </Button>
        </>
      ) : (
        <>
          <select
            className="mr-4 p-2 border"
            name="task"
            id="task"
            onChange={handleSelectTask}
          >
            {selectedTaskId === "" && (
              <option disabled selected value="" hidden>
                -- Select a task --
              </option>
            )}
            {tasks.map(task => (
              <option
                key={task.id}
                value={task.id}
                selected={task.id === selectedTaskId}
              >
                {task.task_name}
              </option>
            ))}
          </select>
          <Button
            handleClick={() => setIsUserAddingNewTask(true)}
            color="primary"
          >
            New Task
          </Button>
        </>
      )}
    </div>
  )
}

export default TaskBar

Above, in the JSX, when the user clicks the "New Task" button, isUserAddingNewTask is set to true, and the first part of the ternary statement is rendered. This allows the user to add a new task.

Let's create the harperAddNewTask function:

// src/utils/harperdb/addNewTask.ts

import { harperFetch } from "./harperFetch"

export const harperAddNewTask = async (username: string, taskName: string) => {
  const data = {
    operation: "insert",
    schema: "productivity_timer",
    table: "tasks",
    records: [
      {
        username: username,
        task_name: taskName,
        time_in_seconds: 0,
      },
    ],
  }

  const responseAndResult = await harperFetch(data)
  return responseAndResult
}

Now, if we import our Taskbar into the home page, we will see it:

// src/pages/index.tsx

import type { NextPage } from "next"
import Taskbar from "../components/home-page/Taskbar"

const Home: NextPage = () => {
  return (
    <div>
      <Taskbar />
    </div>
  )
}

export default Home

TypeScript is correctly telling us off because Taskbar is missing some props, but we will come back to that soon.

Create the timer

First, let's write a function that will take a task ID and time in seconds, and update the task in the database:

// src/utils/harperdb/saveTaskTime.ts

import { harperFetch } from "./harperFetch"

export const harperSaveTaskTime = async (
  taskId: string,
  newSeconds: number
) => {
  const data = {
    operation: "sql",
    sql: `UPDATE productivity_timer.tasks SET time_in_seconds = '${newSeconds}' WHERE id = '${taskId}'`,
  }

  const responseAndResult = await harperFetch(data)
  return responseAndResult
}

Next, create a custom hook to keep the state of the seconds (seconds), whether the timer is running (isTimerOn), and the functions needed to start and stop the timer from running:

// src/custom-hooks/useTimer.ts

import { useState, useRef } from "react"

const useTimer = () => {
  const [isTimerOn, setIsTimerOn] = useState(false)
  const [seconds, setSeconds] = useState(0)

  const intervalRef = useRef<NodeJS.Timer | null>(null)

  const startTimer = () => {
    setIsTimerOn(true)

    const intervalId = setInterval(() => {
      setSeconds(prev => prev + 1)
    }, 1000)

    intervalRef.current = intervalId
  }

  const pauseTimer = () => {
    setIsTimerOn(false)
    clearInterval(intervalRef.current as NodeJS.Timeout)
  }

  return {
    isTimerOn,
    seconds,
    setSeconds,
    startTimer,
    pauseTimer,
  }
}

export default useTimer

On our timer, we want to display the time in hours:mins:seconds, but we will be recording the time passed in seconds. So we need a way of converting seconds into HH:MM:SS. We will do this with a formatTime utility function:

// src/utils/formatTime.ts

const SECONDS_PER_HOUR = 3600
const SECONDS_PER_MINUTE = 60

// HH:MM:SS
export const formatTime = (seconds: number) => {
  const { hours, mins, secs } = calculateHoursMinsAndSecs(seconds)

  const formattedHours = prependZeroIfLessThanTen(hours)
  const formattedMins = prependZeroIfLessThanTen(mins)
  const formattedSecs = prependZeroIfLessThanTen(secs)

  return {
    formattedHours,
    formattedMins,
    formattedSecs,
  }
}

// Prefix time with 0 if less than 10. E.g. '1' => '01'.
const prependZeroIfLessThanTen = (time: number) => {
  const formattedTime: string = time < 10 ? `0${time}` : `${time}`
  return formattedTime
}

// Convert seconds into hours, mins, and secs
const calculateHoursMinsAndSecs = (seconds: number) => {
  const hours = calculateHours(seconds)
  const mins = calculateMins(seconds)
  const secs = calculateSecs(seconds)

  return {
    hours,
    mins,
    secs,
  }
}

const calculateHours = (seconds: number) => {
  const hours = Math.floor(seconds / SECONDS_PER_HOUR)
  return hours
}

const calculateMins = (seconds: number) => {
  const mins = Math.floor((seconds % SECONDS_PER_HOUR) / SECONDS_PER_MINUTE)
  return mins
}

const calculateSecs = (seconds: number) => {
  const secs = Math.floor((seconds % SECONDS_PER_HOUR) % SECONDS_PER_MINUTE)
  return secs
}

Let's now create our Timer component (note: don't panic, we will pass all of the props down next!):

// src/components/home-page/Timer.tsx

import { useContext } from "react"
import { TasksContext } from "../../contexts/TasksContext"
import { UserContext } from "../../contexts/UserContext"
import { formatTime } from "../../utils/formatTime"
import { harperSaveTaskTime } from "../../utils/harperdb/saveTaskTime"
import Button from "../Button"
import type { RecentTaskTime } from "../../types/RecentTaskTime"

interface TimerProps {
  seconds: number
  setSeconds: React.Dispatch<React.SetStateAction<number>>
  isTimerOn: boolean
  startTimer: () => void
  pauseTimer: () => void
  setErrorMessage: React.Dispatch<React.SetStateAction<string>>
  selectedTaskId: string
  selectedTaskName: string
  setRecentTaskTimes: React.Dispatch<React.SetStateAction<RecentTaskTime[]>>
}

export const Timer: React.FC<TimerProps> = ({
  seconds,
  setSeconds,
  isTimerOn,
  startTimer,
  pauseTimer,
  setErrorMessage,
  selectedTaskId,
  selectedTaskName,
  setRecentTaskTimes,
}) => {
  const { tasks, getAndSetTasks } = useContext(TasksContext)
  const { username } = useContext(UserContext)

  const { formattedHours, formattedMins, formattedSecs } = formatTime(seconds)

  const handleStartTimer = () => {
    setErrorMessage("")
    if (selectedTaskId == "") {
      setErrorMessage("Please select a task")
    } else {
      startTimer()
    }
  }

  const handleLogTime = async () => {
    pauseTimer()
    const prevTaskSeconds = getTaskTimeFromId(selectedTaskId)
    const newTaskSeconds = prevTaskSeconds + seconds
    const { response, result } = await harperSaveTaskTime(
      selectedTaskId,
      newTaskSeconds
    )
    if (response.status === 200) {
      getAndSetTasks(username)
      setSeconds(0)
      setRecentTaskTimes(prev => [
        { name: selectedTaskName, seconds: seconds },
        ...prev,
      ])
    } else setErrorMessage("Whoops, something went wrong :(")
    console.log({ response, result })
  }

  const getTaskTimeFromId = (id: string) => {
    const task = tasks.find(task => task.id === id)
    if (!task) return 0
    return task.time_in_seconds
  }

  const handleResetTimer = () => {
    pauseTimer()
    setSeconds(0)
  }

  return (
    <div>
      <div className="mt-8 border-2 border-gray-500 rounded p-14 text-5xl">
        {formattedHours} : {formattedMins} : {formattedSecs}
      </div>
      <div className="flex justify-center mt-10">
        {/* Pause and start the timer buttons */}
        {isTimerOn ? (
          <>
            <Button color="warning" handleClick={pauseTimer}>
              Pause
            </Button>
          </>
        ) : (
          <Button color="success" handleClick={handleStartTimer}>
            Start
          </Button>
        )}

        {/* Button to update the time in the db for the chosen task */}
        {(seconds > 0 || isTimerOn) && (
          <Button
            color="danger"
            handleClick={handleLogTime}
            extraClasses="ml-4"
          >
            Log time
          </Button>
        )}
      </div>

      {/* Stop timer and reset to 0 secs */}
      {(seconds > 0 || isTimerOn) && (
        <button
          onClick={handleResetTimer}
          className="underline underline-offset-2 mt-8 cursor-pointer text-gray-500 mx-auto block"
        >
          Reset
        </button>
      )}
    </div>
  )
}

interface TimerBtnProps {
  handleClick: () => void
  text: string
  extraClasses?: string
}

export const TimerBtn: React.FC<TimerBtnProps> = ({
  handleClick,
  text,
  extraClasses,
}) => {
  return (
    <button
      className={`${
        text === "Start" ? "bg-blue-500" : "bg-red-500"
      } rounded px-4 py-2 text-white mt-8 ${extraClasses}`}
      onClick={handleClick}
    >
      {text}
    </button>
  )
}

We can now add Taskbar and Timer to our index page, and pass down all necessary props to these components:

// src/pages/index.tsx

import { useState, useContext } from "react"
import type { NextPage } from "next"
import type { RecentTaskTime } from "../types/RecentTaskTime"
import { UserContext } from "../contexts/UserContext"
import useTimer from "../custom-hooks/useTimer"
import Taskbar from "../components/home-page/Taskbar"
import { Timer } from "../components/home-page/Timer"
import Alert from "../components/Alert"
import Link from "../components/Link"

const Home: NextPage = () => {
  const [selectedTaskId, setSelectedTaskId] = useState("")
  const [selectedTaskName, setSelectedTaskName] = useState("")
  const [errorMessage, setErrorMessage] = useState("")
  const [recentTaskTimes, setRecentTaskTimes] = useState<RecentTaskTime[]>([])

  const { isTimerOn, seconds, setSeconds, startTimer, pauseTimer } = useTimer()

  const { username } = useContext(UserContext)

  return (
    <div className="flex flex-col items-center justify-center pt-4 grow">
      {!username && (
        <Alert type="warning" extraClasses="mb-12">
          Please <Link href="/login">log in</Link> or{" "}
          <Link href="/signup">create an account</Link> to use Super
          Productivity Timer
        </Alert>
      )}

      <Taskbar
        selectedTaskId={selectedTaskId}
        setSelectedTaskId={setSelectedTaskId}
        setSelectedTaskName={setSelectedTaskName}
        setErrorMessage={setErrorMessage}
        setSeconds={setSeconds}
        pauseTimer={pauseTimer}
      />
      <Timer
        seconds={seconds}
        setSeconds={setSeconds}
        setRecentTaskTimes={setRecentTaskTimes}
        selectedTaskName={selectedTaskName}
        isTimerOn={isTimerOn}
        startTimer={startTimer}
        pauseTimer={pauseTimer}
        setErrorMessage={setErrorMessage}
        selectedTaskId={selectedTaskId}
      />

      {errorMessage && <div className="text-red-500 mt-4">{errorMessage}</div>}
    </div>
  )
}

export default Home

Our timer should now be working. Try adding a task, starting the timer, then logging the time. It should show up in your HarperDB database:

Add a recently completed times log

Let's finish off our timer page by adding a log to give the user feedback that the times have been recorded successfully. It will look like this:

Create a type called RecentTaskTime:

// src/types/RecentTaskTime.ts

export interface RecentTaskTime {
  name: string
  seconds: number
}

Then in index.tsx:

// ...
import LogOfRecentTaskTimes from "../components/home-page/LogOfRecentTaskTimes"

const Home: NextPage = () => {
  // ...
  const [recentTaskTimes, setRecentTaskTimes] = useState<RecentTaskTime[]>([])

  return (
    <div className="flex flex-col items-center justify-center pt-4 grow">
      {/* ... */}

      {recentTaskTimes.length > 0 && (
        <LogOfRecentTaskTimes recentTaskTimes={recentTaskTimes} />
      )}
    </div>
  )
}

Now let's create the LogOfRecentTaskTimes component:

// src/components/home-page/LogOfRecentTaskTimes.tsx

import type { RecentTaskTime } from "../../types/RecentTaskTime"

interface Props {
  recentTaskTimes: RecentTaskTime[]
}

const LogOfRecentTaskTimes = ({ recentTaskTimes }: Props) => {
  return (
    <div className="mt-8 max-h-56 overflow-y-auto px-8">
      {recentTaskTimes.map((t, i) => (
        <div key={i} className="flex shadow rounded px-8 py-4 mt-2">
          <p>
            <span className="text-green-600">{t.seconds}</span> seconds added to{" "}
            <span className="text-green-600">{t.name}</span>
          </p>
        </div>
      ))}
    </div>
  )
}

export default LogOfRecentTaskTimes

Our timer page is complete 🎉

The Stats Page

Well done if you made it this far! We only have one more page to go: the stats page.

In the stats page, we'll be fetching all of the user's tasks from the HarperDB tasks table, and displaying them nicely in a table.

First, we will need some utility functions to display time and date nicely in our stats page table. Add the following two functions to our formatTime utils file:

// src/utils/formatTime.ts

// ...

export const displayTimeString = (seconds: number) => {
  const { formattedHours, formattedMins, formattedSecs } = formatTime(seconds)
  return `${formattedHours}h ${formattedMins}m ${formattedSecs}s`
}

// timestamp => dd/mm/yyyy
export const timestampToDayMonthYear = (timestamp: number) => {
  const date = new Date(timestamp)
  const formattedDate = date.toLocaleDateString()
  return formattedDate
}

// ...

We can now create a table, and loop through tasks to display the data in the table rows. At the end of each row, I've added a delete button so the user can permanently delete tasks from the DB:

// src/pages/stats.tsx

import { useState, useContext } from "react"
import type { NextPage } from "next"
import { UserContext } from "../contexts/UserContext"
import { TasksContext } from "../contexts/TasksContext"
import Header from "../components/PageHeading"
import Link from "../components/Link"
import Alert from "../components/Alert"
import { displayTimeString, timestampToDayMonthYear } from "../utils/formatTime"
import { harperDeleteTask } from "../utils/harperdb/deleteTask"

const Stats: NextPage = () => {
  const [errorMessage, setErrorMessage] = useState("")

  const { username } = useContext(UserContext)
  const { tasks, getAndSetTasks } = useContext(TasksContext)

  const handleDeleteRow = async (taskId: string) => {
    setErrorMessage("")
    const areYouSure = confirm("Are you sure you want to delete this row?")
    if (!areYouSure) return

    try {
      // Delete task from db
      const { response } = await harperDeleteTask(taskId)
      if (response.status === 200) {
        // Get tasks from db and setTasks
        getAndSetTasks(username)
        return
      }
    } catch (err) {
      console.log(err)
    }
    setErrorMessage("Whoops, something went wrong :(")
  }

  return (
    <div>
      {!username && (
        <Alert type="warning" extraClasses="mb-12">
          Please <Link href="/login">log in</Link> or{" "}
          <Link href="/signup">create an account</Link> to use Super
          Productivity Timer
        </Alert>
      )}

      <Header extraClasses="mb-6 text-center mt-8">Stats</Header>

      {errorMessage && (
        <p className="text-center text-red-500 mb-8">{errorMessage}</p>
      )}

      <div className="overflow-x-auto ">
        <table className="table-auto border-collapse border border-slate-400 w-full sm:w-3/4 mx-auto">
          <thead className="bg-slate-100 text-left">
            <tr>
              <TH>Task</TH>
              <TH>Total Time</TH>
              <TH>Last Updated</TH>
              <TH>Start Date</TH>
              <TH>Delete</TH>
            </tr>
          </thead>
          <tbody>
            {tasks.length > 0 &&
              tasks.map(task => (
                <tr key={task.id}>
                  <TD>{task.task_name}</TD>
                  <TD>{displayTimeString(task.time_in_seconds)}</TD>
                  <TD>{timestampToDayMonthYear(task.__updatedtime__)}</TD>
                  <TD>{timestampToDayMonthYear(task.__createdtime__)}</TD>
                  <TD>
                    <button
                      onClick={() => handleDeleteRow(task.id)}
                      className="bg-red-500 text-white rounded px-3 py-1"
                    >
                      x
                    </button>
                  </TD>
                </tr>
              ))}
          </tbody>
        </table>
      </div>
    </div>
  )
}

const TH: React.FC<{ children: string }> = ({ children }) => {
  const classes = "border border-slate-300 rounded-top p-4"
  return <th className={classes}>{children}</th>
}

interface TDProps {
  children: React.ReactNode
}
const TD = ({ children }: TDProps) => {
  const classes = "border border-slate-300 p-4"
  return <td className={classes}>{children}</td>
}

export default Stats

And here is our stats page:

One last thing to do: create the harperDeleteTask function:

// src/utils/harperdb/deleteTask.ts

import { harperFetch } from "./harperFetch"

export const harperDeleteTask = async (taskId: string) => {
  const data = {
    operation: "delete",
    schema: "productivity_timer",
    table: "tasks",
    hash_values: [taskId],
  }

  const responseAndResult = await harperFetch(data)
  return responseAndResult
}

Now try deleting a task and checking your DB – it will be gone. Perfect!

Also, try adding a new task, then logging some time. Then go to the stats page and you'll see that the stats page is updated, too.

You now know how to build a full stack application with NextJS and HarperDB.

Thank you for reading!

If you found this article useful, feel free to:

• Subscribe to my YouTube channel. I plan to turn it into a React/NextJS/Node-focused channel.
• Follow me on Twitter where I tweet about my freelancing journey, side projects, and current learnings.

Cheers!

But don't be alarmed – if you already know JavaScript, you will be able to pick up TypeScript quickly.

Even if you don't plan on using TypeScript, learning it will give you a better understanding of JavaScript – and make you a better developer.

In this article, you will learn:

• What is TypeScript and why should I learn it?
• How to set up a project with TypeScript
• All of the main TypeScript concepts (types, interfaces, generics, type-casting, and more...)
• How to use TypeScript with React

I also made a TypeScript cheat sheet PDF and poster that summarizes this article down to one page. This makes it easy to look up and revise concepts/syntax quickly.

TypeScript cheat sheet PDF

What is TypeScript?

TypeScript is a superset of JavaScript, meaning that it does everything that JavaScript does, but with some added features.

The main reason for using TypeScript is to add static typing to JavaScript. Static typing means that the type of a variable cannot be changed at any point in a program. It can prevent a LOT of bugs!

On the other hand, JavaScript is a dynamically typed language, meaning variables can change type. Here's an example:

// JavaScript
let foo = "hello";
foo = 55; // foo has changed type from a string to a number - no problem

// TypeScript
let foo = "hello";
foo = 55; // ERROR - foo cannot change from string to number

TypeScript cannot be understood by browsers, so it has to be compiled into JavaScript by the TypeScript Compiler (TSC) – which we'll discuss soon.

Is TypeScript worth it?

Why you should use TypeScript

• Research has shown that TypeScript can spot 15% of common bugs.
• Readability – it is easier to see what the code it supposed to do. And when working in a team, it is easier to see what the other developers intended to.
• It's popular – knowing TypeScript will enable you to apply to more good jobs.
• Learning TypeScript will give you a better understanding, and a new perspective, on JavaScript.

Here's a short article I wrote demonstrating how TypeScript can prevent irritating bugs.

Drawbacks of TypeScript

• TypeScript takes longer to write than JavaScript, as you have to specify types, so for smaller solo projects it might not be worth using it.
• TypeScript has to be compiled – which can take time, especially in larger projects.

But the extra time that you have to spend writing more precise code and compiling will be more than saved by how many fewer bugs you'll have in your code.

For many projects – especially medium to large projects – TypeScript will save you lots of time and headaches.

And if you already know JavaScript, TypeScript won't be too hard to learn. It's a great tool to have in your arsenal.

How to Set Up a TypeScript Project

Install Node and the TypeScript Compiler

First, ensure you have Node installed globally on your machine.

Then install the TypeScript compiler globally on your machine by running the following command:

npm i -g typescript

To check if the installation is successful (it will return the version number if successful):

tsc -v

How to Compile TypeScript

Open up your text editor and create a TypeScript file (for example, index.ts).

Write some JavaScript or TypeScript:

let sport = 'football';

let id = 5;

We can now compile this down into JavaScript with the following command:

tsc index

TSC will compile the code into JavaScript and output it in a file called index.js:

var sport = 'football';
var id = 5;

If you want to specify the name of the output file:

tsc index.ts --outfile file-name.js

If you want TSC to compile your code automatically, whenever you make a change, add the "watch" flag:

tsc index.ts -w

An interesting thing about TypeScript is that it reports errors in your text editor whilst you are coding, but it will always compile your code – whether there are errors or not.

For example, the following causes TypeScript to immediately report an error:

var sport = 'football';
var id = 5;

id = '5'; // Error: Type 'string' is not assignable to 
type 'number'.

But if we try to compile this code with tsc index, the code will still compile, despite the error.

This is an important property of TypeScript: it assumes that the developer knows more. Even though there's a TypeScript error, it doesn't get in your way of compiling the code. It tells you there's an error, but it's up to you whether you do anything about it.

How to Set Up the ts config File

The ts config file should be in the root directory of your project. In this file we can specify the root files, compiler options, and how strict we want TypeScript to be in checking our project.

First, create the ts config file:

tsc --init

You should now have a tsconfig.json file in the project root.

Here are some options that are good to be aware of (if using a frontend framework with TypeScript, most if this stuff is taken care of for you):

{
    "compilerOptions": {
        ...
        /* Modules */
        "target": "es2016", // Change to "ES2015" to compile to ES6
        "rootDir": "./src", // Where to compile from
        "outDir": "./public", // Where to compile to (usually the folder to be deployed to the web server)

        /* JavaScript Support */
        "allowJs": true, // Allow JavaScript files to be compiled
        "checkJs": true, // Type check JavaScript files and report errors

        /* Emit */
        "sourceMap": true, // Create source map files for emitted JavaScript files (good for debugging)
         "removeComments": true, // Don't emit comments
    },
    "include": ["src"] // Ensure only files in src are compiled
}

To compile everything and watch for changes:

tsc -w

Note: when input files are specified on the command line (for example, tsc index), tsconfig.json files are ignored.

Types in TypeScript

Primitive types

In JavaScript, a primitive value is data that is not an object and has no methods. There are 7 primitive data types:

• string
• number
• bigint
• boolean
• undefined
• null
• symbol

Primitives are immutable: they can't be altered. It is important not to confuse a primitive itself with a variable assigned a primitive value. The variable may be reassigned a new value, but the existing value can't be changed in the ways that objects, arrays, and functions can be altered.

Here's an example:

let name = 'Danny';
name.toLowerCase();
console.log(name); // Danny - the string method didn't mutate the string

let arr = [1, 3, 5, 7];
arr.pop();
console.log(arr); // [1, 3, 5] - the array method mutated the array

name = 'Anna' // Assignment gives the primitive a new (not a mutated) value

In JavaScript, all primitive values (apart from null and undefined) have object equivalents that wrap around the primitive values. These wrapper objects are String, Number, BigInt, Boolean, and Symbol. These wrapper objects provide the methods that allow the primitive values to be manipulated.

Back to TypeScript, we can set the type we want a variable to be be adding : type (called a "type annotation" or a "type signature") after declaring a variable. Examples:

let id: number = 5;
let firstname: string = 'danny';
let hasDog: boolean = true;

let unit: number; // Declare variable without assigning a value
unit = 5;

But it's usually best to not explicitly state the type, as TypeScript automatically infers the type of a variable (type inference):

let id = 5; // TS knows it's a number
let firstname = 'danny'; // TS knows it's a string
let hasDog = true; // TS knows it's a boolean

hasDog = 'yes'; // ERROR

We can also set a variable to be able to be a union type. A union type is a variable that can be assigned more than one type:

let age: string | number;
age = 26;
age = '26';

Reference Types

In JavaScript, almost "everything" is an object. In fact (and confusingly), strings, numbers and booleans can be objects if defined with the new keyword:

let firstname = new String('Danny');
console.log(firstname); // String {'Danny'}

But when we talk of reference types in JavaScript, we are referring to arrays, objects and functions.

Caveat: primitive vs reference types

For those that have never studied primitive vs reference types, let's discuss the fundamental difference.

If a primitive type is assigned to a variable, we can think of that variable as containing the primitive value. Each primitive value is stored in a unique location in memory.

If we have two variables, x and y, and they both contain primitive data, then they are completely independent of each other:

X and Y both contain unique independent primitive data

let x = 2;
let y = 1;

x = y;
y = 100;
console.log(x); // 1 (even though y changed to 100, x is still 1)

This isn't the case with reference types. Reference types refer to a memory location where the object is stored.

point1 and point2 contain a reference to the address where the object is stored

let point1 = { x: 1, y: 1 };
let point2 = point1;

point1.y = 100;
console.log(point2.y); // 100 (point1 and point2 refer to the same memory address where the point object is stored)

That was a quick overview of primary vs reference types. Check out this article if you need a more thorough explanation: Primitive vs reference types.

Arrays in TypeScript

In TypeScript, you can define what type of data an array can contain:

let ids: number[] = [1, 2, 3, 4, 5]; // can only contain numbers
let names: string[] = ['Danny', 'Anna', 'Bazza']; // can only contain strings
let options: boolean[] = [true, false, false]; can only contain true or false
let books: object[] = [
  { name: 'Fooled by randomness', author: 'Nassim Taleb' },
  { name: 'Sapiens', author: 'Yuval Noah Harari' },
]; // can only contain objects
let arr: any[] = ['hello', 1, true]; // any basically reverts TypeScript back into JavaScript

ids.push(6);
ids.push('7'); // ERROR: Argument of type 'string' is not assignable to parameter of type 'number'.

You can use union types to define arrays containing multiple types:

let person: (string | number | boolean)[] = ['Danny', 1, true];
person[0] = 100;
person[1] = {name: 'Danny'} // Error - person array can't contain objects

If you initialise a variable with a value, it's not necessary to explicitly state the type, as TypeScript will infer it:

let person = ['Danny', 1, true]; // This is identical to above example
person[0] = 100;
person[1] = { name: 'Danny' }; // Error - person array can't contain objects

There is a special type of array that can be defined in TypeScript: Tuples. A tuple is an array with fixed size and known datatypes. They are stricter than regular arrays.

let person: [string, number, boolean] = ['Danny', 1, true];
person[0] = 100; // Error - Value at index 0 can only be a string

Objects in TypeScript

Objects in TypeScript must have all the correct properties and value types:

// Declare a variable called person with a specific object type annotation
let person: {
  name: string;
  location: string;
  isProgrammer: boolean;
};

// Assign person to an object with all the necessary properties and value types
person = {
  name: 'Danny',
  location: 'UK',
  isProgrammer: true,
};

person.isProgrammer = 'Yes'; // ERROR: should be a boolean


person = {
  name: 'John',
  location: 'US',
}; 
// ERROR: missing the isProgrammer property

When defining the signature of an object, you will usually use an interface. This is useful if we need to check that multiple objects have the same specific properties and value types:

interface Person {
  name: string;
  location: string;
  isProgrammer: boolean;
}

let person1: Person = {
  name: 'Danny',
  location: 'UK',
  isProgrammer: true,
};

let person2: Person = {
  name: 'Sarah',
  location: 'Germany',
  isProgrammer: false,
};

We can also declare function properties with function signatures. We can do this using old-school common JavaScript functions (sayHi), or ES6 arrow functions (sayBye):

interface Speech {
  sayHi(name: string): string;
  sayBye: (name: string) => string;
}

let sayStuff: Speech = {
  sayHi: function (name: string) {
    return `Hi ${name}`;
  },
  sayBye: (name: string) => `Bye ${name}`,
};

console.log(sayStuff.sayHi('Heisenberg')); // Hi Heisenberg
console.log(sayStuff.sayBye('Heisenberg')); // Bye Heisenberg

Note that in the sayStuff object, sayHi or sayBye could be given an arrow function or a common JavaScript function – TypeScript doesn't care.

Functions in TypeScript

We can define what the types the function arguments should be, as well as the return type of the function:

// Define a function called circle that takes a diam variable of type number, and returns a string
function circle(diam: number): string {
  return 'The circumference is ' + Math.PI * diam;
}

console.log(circle(10)); // The circumference is 31.41592653589793

The same function, but with an ES6 arrow function:

const circle = (diam: number): string => {
  return 'The circumference is ' + Math.PI * diam;
};

console.log(circle(10)); // The circumference is 31.41592653589793

Notice how it isn't necessary to explicitly state that circle is a function; TypeScript infers it. TypeScript also infers the return type of the function, so it doesn't need to be stated either. Although, if the function is large, some developers like to explicitly state the return type for clarity.

// Using explicit typing 
const circle: Function = (diam: number): string => {
  return 'The circumference is ' + Math.PI * diam;
};

// Inferred typing - TypeScript sees that circle is a function that always returns a string, so no need to explicitly state it
const circle = (diam: number) => {
  return 'The circumference is ' + Math.PI * diam;
};

We can add a question mark after a parameter to make it optional. Also notice below how c is a union type that can be a number or string:

const add = (a: number, b: number, c?: number | string) => {
  console.log(c);

  return a + b;
};

console.log(add(5, 4, 'I could pass a number, string, or nothing here!'));
// I could pass a number, string, or nothing here!
// 9

A function that returns nothing is said to return void – a complete lack of any value. Below, the return type of void has been explicitly stated. But again, this isn't necessary as TypeScript will infer it.

const logMessage = (msg: string): void => {
  console.log('This is the message: ' + msg);
};

logMessage('TypeScript is superb'); // This is the message: TypeScript is superb

If we want to declare a function variable, but not define it (say exactly what it does), then use a function signature. Below, the function sayHello must follow the signature after the colon:

// Declare the varible sayHello, and give it a function signature that takes a string and returns nothing.
let sayHello: (name: string) => void;

// Define the function, satisfying its signature
sayHello = (name) => {
  console.log('Hello ' + name);
};

sayHello('Danny'); // Hello Danny

Here's an interactive scrim to help you learn more about functions in TypeScript:

Dynamic (any) types

Using the any type, we can basically revert TypeScript back into JavaScript:

let age: any = '100';
age = 100;
age = {
  years: 100,
  months: 2,
};

It's recommended to avoid using the any type as much as you can, as it prevents TypeScript from doing its job – and can lead to bugs.

Type Aliases

Type Aliases can reduce code duplication, keeping our code DRY. Below, we can see that the PersonObject type alias has prevented repetition, and acts as a single source of truth for what data a person object should contain.

type StringOrNumber = string | number;

type PersonObject = {
  name: string;
  id: StringOrNumber;
};

const person1: PersonObject = {
  name: 'John',
  id: 1,
};

const person2: PersonObject = {
  name: 'Delia',
  id: 2,
};

const sayHello = (person: PersonObject) => {
  return 'Hi ' + person.name;
};

const sayGoodbye = (person: PersonObject) => {
  return 'Seeya ' + person.name;
};

The DOM and type casting

TypeScript doesn't have access to the DOM like JavaScript. This means that whenever we try to access DOM elements, TypeScript is never sure that they actually exist.

The below example shows the problem:

const link = document.querySelector('a');

console.log(link.href); // ERROR: Object is possibly 'null'. TypeScript can't be sure the anchor tag exists, as it can't access the DOM

With the non-null assertion operator (!) we can tell the compiler explicitly that an expression has value other than null or undefined. This is can be useful when the compiler cannot infer the type with certainty, but we have more information than the compiler.

// Here we are telling TypeScript that we are certain that this anchor tag exists
const link = document.querySelector('a')!;

console.log(link.href); // www.freeCodeCamp.org

Notice how we didn't have to state the type of the link variable. This is because TypeScript can clearly see (via Type Inference) that it is of type HTMLAnchorElement.

But what if we needed to select a DOM element by its class or id? TypeScript can't infer the type, as it could be anything.

const form = document.getElementById('signup-form');

console.log(form.method);
// ERROR: Object is possibly 'null'.
// ERROR: Property 'method' does not exist on type 'HTMLElement'.

Above, we get two errors. We need to tell TypeScript that we are certain form exists, and that we know it is of type HTMLFormElement. We do this with type casting:

const form = document.getElementById('signup-form') as HTMLFormElement;

console.log(form.method); // post

And TypeScript is happy!

TypeScript also has an Event object built in. So, if we add a submit event listener to our form, TypeScript will give us an error if we call any methods that aren't part of the Event object. Check out how cool TypeScript is – it can tell us when we've made a spelling mistake:

const form = document.getElementById('signup-form') as HTMLFormElement;

form.addEventListener('submit', (e: Event) => {
  e.preventDefault(); // prevents the page from refreshing

  console.log(e.tarrget); // ERROR: Property 'tarrget' does not exist on type 'Event'. Did you mean 'target'?
});

Here's an interactive scrim to help you learn more about types in TypeScript:

Classes in TypeScript

We can define the types that each piece of data should be in a class:

class Person {
  name: string;
  isCool: boolean;
  pets: number;

  constructor(n: string, c: boolean, p: number) {
    this.name = n;
    this.isCool = c;
    this.pets = p;
  }

  sayHello() {
    return `Hi, my name is ${this.name} and I have ${this.pets} pets`;
  }
}

const person1 = new Person('Danny', false, 1);
const person2 = new Person('Sarah', 'yes', 6); // ERROR: Argument of type 'string' is not assignable to parameter of type 'boolean'.

console.log(person1.sayHello()); // Hi, my name is Danny and I have 1 pets

We could then create a people array that only includes objects constructed from the Person class:

let People: Person[] = [person1, person2];

We can add access modifiers to the properties of a class. TypeScript also provides a new access modifier called readonly.

class Person {
  readonly name: string; // This property is immutable - it can only be read
  private isCool: boolean; // Can only access or modify from methods within this class
  protected email: string; // Can access or modify from this class and subclasses
  public pets: number; // Can access or modify from anywhere - including outside the class

  constructor(n: string, c: boolean, e: string, p: number) {
    this.name = n;
    this.isCool = c;
    this.email = e;
    this.pets = p;
  }

  sayMyName() {
    console.log(`Your not Heisenberg, you're ${this.name}`);
  }
}

const person1 = new Person('Danny', false, 'dan@e.com', 1);
console.log(person1.name); // Fine
person1.name = 'James'; // Error: read only
console.log(person1.isCool); // Error: private property - only accessible within Person class
console.log(person1.email); // Error: protected property - only accessible within Person class and its subclasses
console.log(person1.pets); // Public property - so no problem

We can make our code more concise by constructing class properties this way:

class Person {
  constructor(
    readonly name: string,
    private isCool: boolean,
    protected email: string,
    public pets: number
  ) {}

  sayMyName() {
    console.log(`Your not Heisenberg, you're ${this.name}`);
  }
}

const person1 = new Person('Danny', false, 'dan@e.com', 1);
console.log(person1.name); // Danny

Writing it the above way, the properties are automatically assigned in the constructor – saving us from having to write them all out.

Note that if we omit the access modifier, by default the property will be public.

Classes can also be extended, just like in regular JavaScript:

class Programmer extends Person {
  programmingLanguages: string[];

  constructor(
    name: string,
    isCool: boolean,
    email: string,
    pets: number,
    pL: string[]
  ) {
    // The super call must supply all parameters for base (Person) class, as the constructor is not inherited.
    super(name, isCool, email, pets);
    this.programmingLanguages = pL;
  }
}

For more on classes, refer to the official TypeScript docs.

Here's an interactive scrim to help you learn more about classes in TypeScript:

Modules in TypeScript

In JavaScript, a module is just a file containing related code. Functionality can be imported and exported between modules, keeping the code well organized.

TypeScript also supports modules. The TypeScript files will compile down into multiple JavaScript files.

In the tsconfig.json file, change the following options to support modern importing and exporting:

 "target": "es2016",
 "module": "es2015"

(Although, for Node projects you very likely want "module": "CommonJS" – Node doesn't yet support modern importing/exporting.)

Now, in your HTML file, change the script import to be of type module:

<script type="module" src="/public/script.js"></script>

We can now import and export files using ES6:

// src/hello.ts
export function sayHi() {
  console.log('Hello there!');
}

// src/script.ts
import { sayHi } from './hello.js';

sayHi(); // Hello there!

Note: always import as a JavaScript file, even in TypeScript files.

Interfaces in TypeScript

Interfaces define how an object should look:

interface Person {
  name: string;
  age: number;
}

function sayHi(person: Person) {
  console.log(`Hi ${person.name}`);
}

sayHi({
  name: 'John',
  age: 48,
}); // Hi John

You can also define an object type using a type alias:

type Person = {
  name: string;
  age: number;
};

function sayHi(person: Person) {
  console.log(`Hi ${person.name}`);
}

sayHi({
  name: 'John',
  age: 48,
}); // Hi John

Or an object type could be defined anonymously:

function sayHi(person: { name: string; age: number }) {
  console.log(`Hi ${person.name}`);
}

sayHi({
  name: 'John',
  age: 48,
}); // Hi John

Interfaces are very similar to type aliases, and in many cases you can use either. The key distinction is that type aliases cannot be reopened to add new properties, vs an interface which is always extendable.

The following examples are taken from the TypeScript docs.

Extending an interface:

interface Animal {
  name: string
}

interface Bear extends Animal {
  honey: boolean
}

const bear: Bear = {
  name: "Winnie",
  honey: true,
}

Extending a type via intersections:

type Animal = {
  name: string
}

type Bear = Animal & {
  honey: boolean
}

const bear: Bear = {
  name: "Winnie",
  honey: true,
}

Adding new fields to an existing interface:

interface Animal {
  name: string
}

// Re-opening the Animal interface to add a new field
interface Animal {
  tail: boolean
}

const dog: Animal = {
  name: "Bruce",
  tail: true,
}

Here's the key difference: a type cannot be changed after being created:

type Animal = {
  name: string
}

type Animal = {
  tail: boolean
}
// ERROR: Duplicate identifier 'Animal'.

As a rule of thumb, the TypeScript docs recommend using interfaces to define objects, until you need to use the features of a type.

Interfaces can also define function signatures:

interface Person {
  name: string
  age: number
  speak(sentence: string): void
}

const person1: Person = {
  name: "John",
  age: 48,
  speak: sentence => console.log(sentence),
}

You may be wondering why we would use an interface over a class in the above example.

One advantage of using an interface is that it is only used by TypeScript, not JavaScript. This means that it won't get compiled and add bloat to your JavaScript. Classes are features of JavaScript, so it would get compiled.

Also, a class is essentially an object factory (that is, a blueprint of what an object is supposed to look like and then implemented), whereas an interface is a structure used solely for type-checking.

While a class may have initialized properties and methods to help create objects, an interface essentially defines the properties and type an object can have.

Interfaces with classes

We can tell a class that it must contain certain properties and methods by implementing an interface:

interface HasFormatter {
  format(): string;
}

class Person implements HasFormatter {
  constructor(public username: string, protected password: string) {}

  format() {
    return this.username.toLocaleLowerCase();
  }
}

// Must be objects that implement the HasFormatter interface
let person1: HasFormatter;
let person2: HasFormatter;

person1 = new Person('Danny', 'password123');
person2 = new Person('Jane', 'TypeScripter1990');

console.log(person1.format()); // danny

Ensure that people is an array of objects that implement HasFormatter (ensures that each person has the format method):

let people: HasFormatter[] = [];
people.push(person1);
people.push(person2);

Literal types in TypeScript

In addition to the general types string and number, we can refer to specific strings and numbers in type positions:

// Union type with a literal type in each position
let favouriteColor: 'red' | 'blue' | 'green' | 'yellow';

favouriteColor = 'blue';
favouriteColor = 'crimson'; // ERROR: Type '"crimson"' is not assignable to type '"red" | "blue" | "green" | "yellow"'.

Here's an interactive scrim to help you learn more about literal types in TypeScript:

Generics

Generics allow you to create a component that can work over a variety of types, rather than a single one, which helps to make the component more reusable.

Let's go through an example to show you what that means...

The addID function accepts any object, and returns a new object with all the properties and values of the passed in object, plus an id property with random value between 0 and 1000. In short, it gives any object an ID.

 const addID = (obj: object) => {
  let id = Math.floor(Math.random() * 1000);

  return { ...obj, id };
};

let person1 = addID({ name: 'John', age: 40 });

console.log(person1.id); // 271
console.log(person1.name); // ERROR: Property 'name' does not exist on type '{ id: number; }'.

As you can see, TypeScript gives an error when we try to access the name property. This is because when we pass in an object to addID, we are not specifying what properties this object should have – so TypeScript has no idea what properties the object has (it hasn't "captured" them). So, the only property that TypeScript knows is on the returned object is id.

So, how can we pass in any object to addID, but still tell TypeScript what properties and values the object has? We can use a generic, <T> – where T is known as the type parameter:

// <T> is just the convention - e.g. we could use <X> or <A>
const addID = <T>(obj: T) => {
  let id = Math.floor(Math.random() * 1000);

  return { ...obj, id };
};

What does this do? Well, now when we pass an object into addID, we have told TypeScript to capture the type – so T becomes whatever type we pass in. addID will now know what properties are on the object we pass in.

But, we now have a problem: anything can be passed into addID and TypeScript will capture the type and report no problem:

let person1 = addID({ name: 'John', age: 40 });
let person2 = addID('Sally'); // Pass in a string - no problem

console.log(person1.id); // 271
console.log(person1.name); // John

console.log(person2.id);
console.log(person2.name); // ERROR: Property 'name' does not exist on type '"Sally" & { id: number; }'.

When we passed in a string, TypeScript saw no issue. It only reported an error when we tried to access the name property. So, we need a constraint: we need to tell TypeScript that only objects should be accepted, by making our generic type, T, an extension of object:

const addID = <T extends object>(obj: T) => {
  let id = Math.floor(Math.random() * 1000);

  return { ...obj, id };
};

let person1 = addID({ name: 'John', age: 40 });
let person2 = addID('Sally'); // ERROR: Argument of type 'string' is not assignable to parameter of type 'object'.

The error is caught straight away – perfect... well, not quite. In JavaScript, arrays are objects, so we can still get away with passing in an array:

let person2 = addID(['Sally', 26]); // Pass in an array - no problem

console.log(person2.id); // 824
console.log(person2.name); // Error: Property 'name' does not exist on type '(string | number)[] & { id: number; }'.

We could solve this by saying that the object argument should have a name property with string value:

const addID = <T extends { name: string }>(obj: T) => {
  let id = Math.floor(Math.random() * 1000);

  return { ...obj, id };
};

let person2 = addID(['Sally', 26]); // ERROR: argument should have a name property with string value

The type can also be passed in to <T>, as below – but this isn't necessary most of the time, as TypeScript will infer it.

// Below, we have explicitly stated what type the argument should be between the angle brackets.
let person1 = addID<{ name: string; age: number }>({ name: 'John', age: 40 });

Generics allow you to have type-safety in components where the arguments and return types are unknown ahead of time.

In TypeScript, generics are used when we want to describe a correspondence between two values. In the above example, the return type was related to the input type. We used a generic to describe the correspondence.

Another example: If we need a function that accepts multiple types, it is better to use a generic than the any type. Below shows the issue with using any:

function logLength(a: any) {
  console.log(a.length); // No error
  return a;
}

let hello = 'Hello world';
logLength(hello); // 11

let howMany = 8;
logLength(howMany); // undefined (but no TypeScript error - surely we want TypeScript to tell us we've tried to access a length property on a number!)

We could try using a generic:

function logLength<T>(a: T) {
  console.log(a.length); // ERROR: TypeScript isn't certain that `a` is a value with a length property
  return a;
}

At least we are now getting some feedback that we can use to tighten up our code.

Solution: use a generic that extends an interface that ensures every argument passed in has a length property:

interface hasLength {
  length: number;
}

function logLength<T extends hasLength>(a: T) {
  console.log(a.length);
  return a;
}

let hello = 'Hello world';
logLength(hello); // 11

let howMany = 8;
logLength(howMany); // Error: numbers don't have length properties

We could also write a function where the argument is an array of elements that all have a length property:

interface hasLength {
  length: number;
}

function logLengths<T extends hasLength>(a: T[]) {
  a.forEach((element) => {
    console.log(element.length);
  });
}

let arr = [
  'This string has a length prop',
  ['This', 'arr', 'has', 'length'],
  { material: 'plastic', length: 30 },
];

logLengths(arr);
// 29
// 4
// 30

Generics are an awesome feature of TypeScript!

Generics with interfaces

When we don't know what type a certain value in an object will be ahead of time, we can use a generic to pass in the type:

// The type, T, will be passed in
interface Person<T> {
  name: string;
  age: number;
  documents: T;
}

// We have to pass in the type of `documents` - an array of strings in this case
const person1: Person<string[]> = {
  name: 'John',
  age: 48,
  documents: ['passport', 'bank statement', 'visa'],
};

// Again, we implement the `Person` interface, and pass in the type for documents - in this case a string
const person2: Person<string> = {
  name: 'Delia',
  age: 46,
  documents: 'passport, P45',
};

Enums in TypeScript

Enums are a special feature that TypeScript brings to JavaScript. Enums allow us to define or declare a collection of related values, that can be numbers or strings, as a set of named constants.

enum ResourceType {
  BOOK,
  AUTHOR,
  FILM,
  DIRECTOR,
  PERSON,
}

console.log(ResourceType.BOOK); // 0
console.log(ResourceType.AUTHOR); // 1

// To start from 1
enum ResourceType {
  BOOK = 1,
  AUTHOR,
  FILM,
  DIRECTOR,
  PERSON,
}

console.log(ResourceType.BOOK); // 1
console.log(ResourceType.AUTHOR); // 2

By default, enums are number based – they store string values as numbers. But they can also be strings:

enum Direction {
  Up = 'Up',
  Right = 'Right',
  Down = 'Down',
  Left = 'Left',
}

console.log(Direction.Right); // Right
console.log(Direction.Down); // Down

Enums are useful when we have a set of related constants. For example, instead of using non-descriptive numbers throughout your code, enums make code more readable with descriptive constants.

Enums can also prevent bugs, as when you type the name of the enum, intellisense will pop up and give you the list of possible options that can be selected.

TypeScript strict mode

It is recommended to have all strict type-checking operations enabled in the tsconfig.json file. This will cause TypeScript to report more errors, but will help prevent many bugs from creeping into your application.

 // tsconfig.json
 "strict": true

Let's discuss a couple of the things that strict mode does: no implicit any, and strict null checks.

No implicit any

In the function below, TypeScript has inferred that the parameter a is of any type. As you can see, when we pass in a number to this function, and try to log a name property, no error is reported. Not good.

function logName(a) {
  // No error??
  console.log(a.name);
}

logName(97);

With the noImplicitAny option turned on, TypeScript will instantly flag an error if we don't explicitly state the type of a:

// ERROR: Parameter 'a' implicitly has an 'any' type.
function logName(a) {
  console.log(a.name);
}

Strict null checks

When the strictNullChecks option is false, TypeScript effectively ignores null and undefined. This can lead to unexpected errors at runtime.

With strictNullChecks set to true, null and undefined have their own types, and you'll get a type error if you assign them to a variable that expects a concrete value (for example, string).

let whoSangThis: string = getSong();

const singles = [
  { song: 'touch of grey', artist: 'grateful dead' },
  { song: 'paint it black', artist: 'rolling stones' },
];

const single = singles.find((s) => s.song === whoSangThis);

console.log(single.artist);

Above, singles.find has no guarantee that it will find the song – but we have written the code as though it always will.

By setting strictNullChecks to true, TypeScript will raise an error because we haven't made a guarantee that single exists before trying to use it:

const getSong = () => {
  return 'song';
};

let whoSangThis: string = getSong();

const singles = [
  { song: 'touch of grey', artist: 'grateful dead' },
  { song: 'paint it black', artist: 'rolling stones' },
];

const single = singles.find((s) => s.song === whoSangThis);

console.log(single.artist); // ERROR: Object is possibly 'undefined'.

TypeScript is basically telling us to ensure single exists before using it. We need to check if it isn't null or undefined first:

if (single) {
  console.log(single.artist); // rolling stones
}

Narrowing in TypeScript

In a TypeScript program, a variable can move from a less precise type to a more precise type. This process is called type narrowing.

Here's a simple example showing how TypeScript narrows down the less specific type of string | number to more specific types when we use if-statements with typeof:

function addAnother(val: string | number) {
  if (typeof val === 'string') {
    // TypeScript treats `val` as a string in this block, so we can use string methods on `val` and TypeScript won't shout at us
    return val.concat(' ' + val);
  }

  // TypeScript knows `val` is a number here
  return val + val;
}

console.log(addAnother('Woooo')); // Woooo Woooo
console.log(addAnother(20)); // 40

Another example: below, we have defined a union type called allVehicles, which can either be of type Plane or Train.

interface Vehicle {
  topSpeed: number;
}

interface Train extends Vehicle {
  carriages: number;
}

interface Plane extends Vehicle {
  wingSpan: number;
}

type PlaneOrTrain = Plane | Train;

function getSpeedRatio(v: PlaneOrTrain) {
  // In here, we want to return topSpeed/carriages, or topSpeed/wingSpan
  console.log(v.carriages); // ERROR: 'carriages' doesn't exist on type 'Plane'
}

Since the function getSpeedRatio is working with multiple types, we need a way of distinguishing whether v is a Plane or Train. We could do this by giving both types a common distinguishing property, with a literal string value:

// All trains must now have a type property equal to 'Train'
interface Train extends Vehicle {
  type: 'Train';
  carriages: number;
}

// All trains must now have a type property equal to 'Plane'
interface Plane extends Vehicle {
  type: 'Plane';
  wingSpan: number;
}

type PlaneOrTrain = Plane | Train;

Now we, and TypeScript, can narrow down the type of v:

function getSpeedRatio(v: PlaneOrTrain) {
  if (v.type === 'Train') {
    // TypeScript now knows that `v` is definitely a `Train`. It has narrowed down the type from the less specific `Plane | Train` type, into the more specific `Train` type
    return v.topSpeed / v.carriages;
  }

  // If it's not a Train, TypeScript narrows down that `v` must be a Plane - smart!
  return v.topSpeed / v.wingSpan;
}

let bigTrain: Train = {
  type: 'Train',
  topSpeed: 100,
  carriages: 20,
};

console.log(getSpeedRatio(bigTrain)); // 5

Bonus: TypeScript with React

TypeScript has full support for React and JSX. This means we can use TypeScript with the three most common React frameworks:

• create-react-app (TS setup)
• Gatsby (TS setup)
• Next.js (TS setup)

If you require a more custom React-TypeScript configuration, you could setup Webpack (a module bundler) and configure the tsconfig.json yourself. But most of the time, a framework will do the job.

To setup up create-react-app with TypeScript, for example, simply run:

npx create-react-app my-app --template typescript

# or

yarn create react-app my-app --template typescript

In the src folder, we can now create files with .ts (for regular TypeScript files) or .tsx (for TypeScript with React) extensions and write our components with TypeScript. This will then compile down into JavaScript in the public folder.

React props with TypeScript

Below, we are saying that Person should be a React functional component that accepts a props object with the props name, which should be a string, and age, which should be a number.

// src/components/Person.tsx
import React from 'react';

const Person: React.FC<{
  name: string;
  age: number;
}> = ({ name, age }) => {
  return (
    <div>
      <div>{name}</div>
      <div>{age}</div>
    </div>
  );
};

export default Person;

But most developers prefer to use an interface to specify prop types:

interface Props {
  name: string;
  age: number;
}

const Person: React.FC<Props> = ({ name, age }) => {
  return (
    <div>
      <div>{name}</div>
      <div>{age}</div>
    </div>
  );
};

We can then import this component into App.tsx. If we don't provide the necessary props, TypeScript will give an error.

import React from 'react';
import Person from './components/Person';

const App: React.FC = () => {
  return (
    <div>
      <Person name='John' age={48} />
    </div>
  );
};

export default App;

Here are a few examples for what we could have as prop types:

interface PersonInfo {
  name: string;
  age: number;
}

interface Props {
  text: string;
  id: number;
  isVeryNice?: boolean;
  func: (name: string) => string;
  personInfo: PersonInfo;
}

React hooks with TypeScript

useState()

We can declare what types a state variable should be by using angle brackets. Below, if we omitted the angle brackets, TypeScript would infer that cash is a number. So, if want to enable it to also be null, we have to specify:

const Person: React.FC<Props> = ({ name, age }) => {
  const [cash, setCash] = useState<number | null>(1);

  setCash(null);

  return (
    <div>
      <div>{name}</div>
      <div>{age}</div>
    </div>
  );
};

useRef()

useRef returns a mutable object that persists for the lifetime of the component. We can tell TypeScript what the ref object should refer to – below we say the prop should be a HTMLInputElement:

const Person: React.FC = () => {
  // Initialise .current property to null
  const inputRef = useRef<HTMLInputElement>(null);

  return (
    <div>
      <input type='text' ref={inputRef} />
    </div>
  );
};

For more information on React with TypeScript, checkout these awesome React-TypeScript cheatsheets.

Useful resources & further reading

• The official TypeScript docs
• The Net Ninja's TypeScript video series (awesome!)
• Ben Awad's TypeScript with React video
• Narrowing in TypeScript (a very interesting feature of TS that you should learn)
• Function overloads
• Primitive values in JavaScript
• JavaScript objects

Thanks for reading!

Hope that was useful. If you made it to here, you now know the main fundamentals of TypeScript and can start using it in your projects.

Again, you can also download my one-page TypeScript cheat sheet PDF or order a physical poster.

For more from me, you can find me on Twitter and YouTube.

Cheers!