In order to make our app a bit more performant, we will utilize the browser’s local storage to store already scraped data so that we don’t trigger new scraping requests every time the browser is refreshed.

Here’s what it will look like:

Table of Contents

• How to Spin Up the App with Vite

• How to Build the Server

• How to Build the Front End

• How to Deploy to render.com

• Conclusion

If you want to jump straight into the code, here 💁 is the GitHub repository with a detailed README 🙌, and here you can see the live demo.

Now if you’re ready, let’s go step by step and see how to build and the deploy the app.

First, let’s get everything set up and ready to go.

How to Spin Up the App with Vite

We will use the Vite build tool to quickly spin up a bare bones React application, equipped with TailwindCSS for styling. In order to do that, run this in your terminal app:

npm create vite@latest web-scraper -- --template react

And then install and configure TailwindCSS as follows:

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

Add the paths to all of your template files in your tailwind.config.js file like this:

/** @type {import('tailwindcss').Config} */
export default {
  content: [
    "./index.html",
    "./src/**/*.{js,ts,jsx,tsx}",
  ],
  theme: {
    extend: {},
  },
  plugins: [],
}

Now you should have a brand new React application with Tailwind installed and configured.

Let’s start our work with the server.

How to Build the Server

Since we are building a full stack application, the bare minimum we need to have in place is a server, a client, and an API. The API will live in the server world and the client app will call the endpoints it exposes in order to fetch the data we need to display on the front end.

Set Up the HTTP Server with Express.js

We are going to use the Express.js library to spin up an HTTP server that will handle our API requests. To do so, follow these steps:

First, install the necessary packages with this command:

npm install express cors playwright

Then create an empty server.js file in the project's root folder and add the following code:

import express from "express";
import { chromium } from "playwright";
import cors from "cors";
import { scrapeListings } from "./utils/scraper.js";

const app = express();
const PORT = 5001;

app.use(cors());

app.get("/scrape", async (req, res) => {
  let browser;
  try {
    browser = await chromium.launch();
    const listings = await scrapeListings({ browser, retryCount: 3 });
    res.json(listings);
  } catch (error) {
    res.status(500).json({ error: error.message });
  }
});

app.listen(PORT, () => {
  console.log(`Scraper server running on http://localhost:${PORT}`);
});

Before we continue with the scraper, let me first explain what we are doing here.

This is a pretty simple setup of an Express server that is exposing an endpoint called “scrape“. Our client-side application (the front end) can send GET requests to this endpoint and receive the data returned as a result.

What’s important here is the async callback function that we pass to the app.get method. This is where we call our scraping function within a try/catch block. It will return the scraped data or an error if something goes wrong.

The last few lines indicate that our server will listen on the specified PORT, which is set to 5001 here, and display a message in the terminal to show that the server is running.

What is Web Scraping?

Before diving into the code, I want to briefly explain web scraping if you’re unfamiliar with it. Web scraping involves automatically reading content from websites using a piece of software. This software is called a “web scraper“. In our case, the scraper is what’s in the scrapeListing function.

An essential part of the scraping process is finding something in the DOM tree of the target website that you can use to select the data we want to scrape. This something is known as a selector. Selectors can be different HTML elements, such as tags (h3, p, table) or attributes, like class names or IDs.

You can use various programming techniques or features of the programming language you’re using to create the scraper, aiming for better results when implementing the selecting part of the scraper.

In our case, we’re using [itemprop="itemListElement"] as the selector. But you might wonder, how did we figure this out and decide to use that? How do you know which selector to use?

This is where it gets tricky. You have to manually inspect the DOM tree of the target website and determine what would work best. That’s the case unless the site provides an API specifically designed for scrapers.

Here is how this looks like in practice. This is a screenshot from the Airbnb website:

Usually, you’ll need the information you’re scraping for some particular purpose, which means you’ll need to store it somewhere and then process it. This processing often involve some kind of visualization of the data. This is where our client application comes into play.

We will store the results of our scraping in the browser's local storage. Then, we will easily display those results in a grid layout using React and TailwindCSS. But before we get to all this, let’s go back to the code to understand how the scraping process is done.

Set Up Playwright

For the scraping functionality, we will use another library that has gotten pretty famous over the last few years: Playwright. It mainly serves as an e2e testing solution, but, as you’ll see now, we can use it for scraping the web as well.

We will put the scraping function in a separate file so that we have it all in order and keep the separation of concerns in place.

Create a new folder in the root directory and name it utils. Inside this folder, add a new file named scraper.js and include the following code:

const MAX_RETRIES = 3;

const validateListing = (listing) => {
  return (
    typeof listing.title === "string" &&
    typeof listing.price === "string" &&
    typeof listing.link === "string"
  );
};

export const scrapeListings = async ({ browser, retryCount }) => {
  try {
    const page = await browser.newPage();

    try {
      await page.goto("https://www.airbnb.com/", { waitUntil: "load" });

      await page.waitForSelector('[itemprop="itemListElement"]', {
        timeout: 10000,
      });

      const listings = await page.$$eval(
        '[itemprop="itemListElement"]',
        (elements) => {
          return elements.slice(0, 10).map((element) => {
            const title =
              element.querySelector(".t1jojoys")?.innerText || "N/A";
            const price =
              element.querySelector("._11jcbg2")?.innerText || "N/A";
            const link = element.querySelector("a")?.href || "N/A";
            return { title, price, link };
          });
        }
      );

      const validListings = listings.filter(validateListing);

      if (validListings.length === 0) {
        throw new Error("No listings found");
      }

      return validListings;
    } catch (pageError) {
      if (retryCount < MAX_RETRIES) {
        console.log(`Retrying... (${retryCount + 1}/${MAX_RETRIES})`);
        return await scrapeListings(retryCount + 1);
      } else {
        throw new Error(
          `Failed to scrape data after ${MAX_RETRIES} attempts: ${pageError.message}`
        );
      }
    } finally {
      await page.close();
    }
  } catch (browserError) {
    throw new Error(`Failed to launch browser: ${browserError.message}`);
  } finally {
    if (browser) {
      await browser.close();
    }
  }
};

Retry Mechanism

At the top of the file, there's a constant called MAX_RETRIES used to implement a retry mechanism. This tactic is often used by web scrapers to bypass or overcome protections that some websites have against scraping. We will see how to use it below.

It's important to mention the legal aspect here as well. Always respect the terms and conditions along with the privacy policy of the website you plan to scrape. Use these techniques only to handle technical challenges, not to break the law.

A small helper function follows that you can use to validate the received data. Nothing interesting here.

Next is the main scraping function. We’re passing the browser object, provided by Playwright, and the number of retry attempts as arguments to the function.

There are two try/catch blocks to handle possible failures: one for launching the browser (in headless mode, meaning you won't see anything) and one for the scraping process. In the latter, we’ll use Playwright's features to request the website, wait until the page is fully loaded, and then locate the selector we defined.

In the callback function we pass to $$eval, we access the elements returned by the scraping, allowing us to process them and get the data we want. In this case, I’m using three selectors to fetch the title, price, and link of the property. The first two are class names, and the last is the HTML tag <a>.

Then we return an object, { title, price, link }, with the fetched data, that is the values of the three properties. And in the end of the try part, we validate the results before returning them to the front end.

What follows in the catch part is the implementation of the retry mechanism we talked about a minute ago:

 } catch (pageError) {
      if (retryCount < MAX_RETRIES) {
        console.log(`Retrying... (${retryCount + 1}/${MAX_RETRIES})`);
        return await scrapeListings(retryCount + 1);
      } else {
        throw new Error(
          `Failed to scrape data after ${MAX_RETRIES} attempts: ${pageError.message}`
        );
      }
    }

If an error occurs during the reading process, we enter the catch phase and check if the retry count is below the maximum limit we set. If it is, we try again by running the function recursively. Otherwise, we throw an error indicating that the scraping failed and the maximum retry attempts have been reached.

That's all you need to set up basic web scraping of the Airbnb homepage.

You can see all this in the Github repo of the project so don’t worry if you missed something here.

How to Build the Front End

Now it's time to put the scraped data to use.

Let's display the last 10 properties in a grid layout, allowing you (or anyone) to open them by clicking on their links. We will also add a Refresh feature that lets you perform a new scrape to get the most up-to-date data.

This is how the structure of the front end part of the project looks:

We have a simple app structure: one main container (App.jsx) that holds all the components and includes some logic for making requests to the API and storing the data in local storage.

import { useEffect, useState } from "react";
import { useLocalStorage } from "@uidotdev/usehooks";
import axios from "axios";
import Footer from "./components/Footer";
import Header from "./components/Header";
import RefreshButton from "./components/RefreshButton";
import Grid from "./components/Grid";
import Loader from "./components/Loader";

function App() {
  const [listings, setListings] = useLocalStorage("properties", []);
  const [loading, setLoading] = useState(false);
  const [error, setError] = useState("");

  const fetchListings = async () => {
    setLoading(true);
    setError("");
    setListings([]);

    try {
      const response = await axios.get("http://localhost:5001/scrape");
      if (response.data.length === 0) {
        throw new Error("No listings found");
      }
      setListings(response.data);
    } catch (err) {
      setError(
        err.response?.data?.error ||
          "Failed to fetch listings. Please try again."
      );
    } finally {
      setLoading(false);
    }
  };

  useEffect(() => {
    if (listings.length === 0) {
      fetchListings();
    }
  }, []);

  return (
    <div className="flex flex-col items-center justify-center min-h-screen bg-gray-100">
      <Header />
      <RefreshButton callback={fetchListings} loading={loading} />
      <main className="flex flex-col items-center justify-center flex-1 w-full px-4 relative">
        {error && <p className="text-red-500">{error}</p>}
        {loading ? <Loader /> : <Grid listings={listings} />}
      </main>
      <Footer />
    </div>
  );
}

export default App;

All components are placed in the components directory (this is what I call a surprise, ah:)). Most of the components are quite simple, and I included them to give the app a more complete appearance.

The Header displays the top bar. The RefreshButton is used to send a new request and get the latest data. In the <main> section, we either show an error message if fetching fails, or we display a Loader component and a Grid component.

The loading part is straightforward. The Grid component is the interesting one. We pass the scraping results to it using a prop called 'listings'. Inside, we use a simple map() function to go through them and display the properties. We use Tailwind to style the grid, ensuring the properties are neatly listed and look good on both desktop and mobile screens.

And in the end with we have the Footer component that renders a simple bar with text. Again, I’ve added it just for completeness.

How to Deploy to render.com

Maybe a little over a year ago, I needed a place to deploy full-stack applications, ideally for free, since they were just for educational purposes.

After some research, I found a platform called Render and managed to deploy an app with both client and server parts, getting it to work online. I left it there until now. Since our scraper requires both parts to function properly, we will deploy it there and have it working online, as you can see here.

To do this, you need to create an account with Render and use their dashboard application. The process is simple, but I'll include a few screenshots below for clarity.

This is the Overview page where you can see all your projects:

Here is the Project page where you can view and manage your projects. In our case, we can see both the server and the client app as separate services.

You can click on each service to open its page, where you can view the deployments and the commits that triggered them. You can find even more details if you explore further.

You should be able to manage the deployment process on your own, as everything is clearly explained. But if you need help, feel free to reach out.

I should mention that I am not affiliated with Render in any way and I am not receiving any benefits for mentioning them here. I just found it to be a useful tool and wanted to share it with you – so I’ve used it here.

Conclusion

A web scraper app can be a powerful tool for gathering data, but there are several areas for improvement and important considerations to keep in mind here.

Firstly, you can enhance the app's performance and efficiency by optimizing the scraping process and ensuring that the data is stored and processed effectively. You can also implement more robust error handling and retry mechanisms to improve the reliability of the scraper.

Also, keep in mind that ethical scraping is crucial, and it's important to always respect the terms of service and privacy policies of the websites you are scraping. This includes not overloading the website with requests and ensuring that the data is used responsibly. Always seek permission from the site if required and consider using APIs provided by the website as a more ethical and reliable alternative.

Lastly, respecting the law is paramount. Ensure that your scraping activities comply with legal regulations and guidelines to avoid any potential legal issues. By focusing on these aspects, you can build a more effective, ethical, and legally compliant web scraper app.

This inspired me to build a similar game for her. Since she's currently into anime, I decided to create the game using cute anime-style images.

In this article, I'll walk you through the process of building the game for yourself or your kids 🎮.

We'll begin by exploring the game features, then cover the tech stack and project structure—both of which are straightforward. Finally, we'll discuss optimizations and ensuring smooth gameplay on mobile devices 📱.

If you want to skip the reading, here 💁 is the GitHub repository 🙌. And here you can see the live demo.

Table of Contents

• Project Description

• Let’s Build the Game

• Testing the App

• API Fallback Mechanism

• Optimizations

• Future Improvements

• Conclusion

Project Description

In this tutorial, we’ll build a challenging memory card game with React that tests your recall abilities. Your goal is to click unique anime images without clicking the same one twice. Each unique click earns you points, but be careful—clicking an image twice resets your progress.

Game features:

• 🎯 Dynamic gameplay that challenges your memory

• 🔄 Cards shuffle after each click to increase difficulty

• 🏆 Score tracking with best score persistence

• 😺 Adorable anime images from The Nekosia API

• ✨ Smooth loading transitions and animations

• 📱 Responsive design for all devices

• 🎨 Clean, modern UI

The game will help you test your memory skills while enjoying cute anime pictures. Can you achieve the perfect score?

How to Play

1. Click on any card to start

2. Remember which cards you've clicked

3. Try to click all cards exactly once

4. Watch your score grow with each unique selection

5. Then keep playing to try to beat your best score

The Tech Stack

Here’s a list of the main technologies we’ll be using:

• NPM – A package manager for JavaScript that helps manage dependencies and scripts for the project.

• Vite – A build tool that provides a fast development environment, particularly optimized for modern web projects.

• React – A popular JavaScript library for building user interfaces, enabling efficient rendering and state management.

• CSS Modules – A styling solution that scopes CSS to individual components, preventing style conflicts and ensuring maintainability.

Let’s Build the Game

From this point onward, I will guide you through the process I followed when building this game.

Project Structure and Architecture

When building this memory card game, I carefully organized the codebase to ensure maintainability, scalability, and clear separation of concerns. Let's explore the structure and the reasoning behind each decision:

Component-Based Architecture

I chose a component-based architecture for several reasons:

• Modularity: Each component is self-contained with its own logic and styles

• Reusability: Components like Card and Loader can be reused across the application

• Maintainability: Easier to debug and modify individual components

• Testing: Components can be tested in isolation

Component Organization

1. Card Component

• Separated into its own directory because it's a core game element

• Contains both JSX and SCSS modules for encapsulation

• Handles individual card rendering, loading states, and click events

2. CardsGrid Component

• Manages the game board layout

• Handles card shuffling and distribution

• Controls the responsive grid layout for different screen sizes

3. Loader Component

• Reusable loading indicator

• Improves user experience during image loading

• Can be used by any component that needs loading states

4. Header/Footer/Subtitle Components

• Structural components for app layout

• Header displays game title and scores

• Footer shows copyright and version info

• Subtitle provides game instructions

CSS Modules Approach

I used CSS Modules (.module.scss files) for several benefits:

• Scoped Styling: Prevents style leaks between components

• Name Collisions: Automatically generates unique class names

• Maintainability: Styles are co-located with their components

• SCSS Features: Leverages SCSS features while keeping styles modular

Custom Hooks

The hooks directory contains custom hooks like useFetch:

• Separation of Concerns: Isolates data fetching logic

• Reusability: Can be used by any component needing image data

• State Management: Handles loading, error, and data states

• Performance: Implements optimizations like image size control

Root Level Files

App.jsx:

• Acts as the application's entry point

• Manages global state and routing (if needed)

• Coordinates component composition

• Handles top-level layouts

Performance Considerations

The structure supports performance optimizations:

• Code Splitting: Components can be lazy-loaded if needed

• Memoization: Components can be memoized effectively

• Style Loading: CSS Modules enable efficient style loading

• Asset Management: Images and resources are properly organized

Scalability

This structure allows for easy scaling:

• New features can be added as new components

• Additional hooks can be created for new functionality

• Styles remain maintainable as the app grows

• Testing can be implemented at any level

Development Experience

The structure enhances developer experience:

• Clear file organization

• Intuitive component locations

• Easy to find and modify specific features

• Supports efficient collaboration

This architecture proved particularly valuable when optimizing the game for tablet use, as it allowed me to:

1. Easily identify and optimize performance bottlenecks

2. Add tablet-specific styles without affecting other devices

3. Implement loading states for better mobile experience

4. Maintain clean separation between game logic and UI components

Alright, now let’s get coding.

Step-by-Step Build Guide

1. Project Setup

Set Up the Development Environment

In order to start with a clean React project, open your terminal app and run the following commands (you may name your project folder as you like – in my case the name is ‘memory-card’):

npm create vite@latest memory-card -- --template react
cd memory-card
npm install

Install the Required Dependencies

The only dependencies we will use in this project are the hook package from UI.dev (by the way, here you can find a well-explained article on how rendering in React works).

The other dependency is the famous CSS preprocessor, SASS, that we’ll need to be able to write our CSS modules in SASS instead of regular CSS.

npm install @uidotdev/usehooks sass

Configure Vite and Project Setting

When setting up our project, we need to make some specific configuration adjustments to handle SASS warnings and improve our development experience. Here's how you can configure Vitest:

// vitest.config.js
import { defineConfig } from 'vitest/config';
import react from '@vitejs/plugin-react';

export default defineConfig({
  plugins: [react()],
  test: {
    environment: 'jsdom',
    globals: true,
    setupFiles: ['./src/setupTests.js'],
    css: {
      modules: {
        classNameStrategy: 'non-scoped'
      }
    },
    preprocessors: {
      '**/*.scss': 'sass'
    },
    coverage: {
      provider: 'v8',
      reporter: ['text', 'json', 'html'],
      exclude: [
        'node_modules/',
        'src/setupTests.js',
        'src/main.jsx',
        'src/vite-env.d.ts',
      ],
    },
  },
  css: {
    preprocessorOptions: {
      scss: {
        quietDeps: true,  // Silences SASS dependency warnings
        charset: false    // Prevents charset warning in recent SASS versions
      }
    }
  }
});

Keep in mind that most of these configurations are auto-generated for you when you create the project with Vite. Here’s what’s going on:

1. SASS Configuration:

   • quietDeps: true: This silences the warnings about deprecated dependencies in SASS modules. Particularly useful when working with third-party SASS/SCSS files.

   • charset: false: Prevents the "@charset" warning that appears in newer versions of SASS when using special characters in your stylesheets.

2. Test Configuration:

   • globals: true: Makes test functions globally available in test files

   • environment: 'jsdom': Provides a DOM environment for testing

   • setupFiles: Points to our test setup file

These configurations help create a cleaner development experience by removing unnecessary warning messages in the console, setting up proper test environment configurations, and ensuring SASS/SCSS processing works smoothly.

You might see warnings in your console without these configurations when:

• Using SASS/SCSS features or importing SASS files

• Running tests that require DOM manipulation

• Using special characters in your stylesheets

2. Building the Components

Create the Card Component

First, let's create our basic card component that will display individual images:

// src/components/Card/Card.jsx
import React, { useState, useCallback } from "react";
import Loader from "../Loader";
import styles from "./Card.module.scss";

const Card = React.memo(function Card({ imgUrl, imageId, categoryName, processTurn }) {
  const [isLoading, setIsLoading] = useState(true);

  const handleImageLoad = useCallback(() => {
    setIsLoading(false);
  }, []);

  const handleClick = useCallback(() => {
    processTurn(imageId);
  }, [processTurn, imageId]);

  return (
    <div className={styles.container} onClick={handleClick}>
      {isLoading && (
        <div className={styles.loaderContainer}>
          <Loader message="Loading..." />
        </div>
      )}
      <img
        src={imgUrl}
        alt={categoryName}
        onLoad={handleImageLoad}
        className={`${styles.image} ${isLoading ? styles.hidden : ''}`}
      />
    </div>
  );
});

export default Card;

The Card component is a fundamental building block of our game. It's responsible for displaying individual images and handling player interactions. Let's break down its implementation:

Props breakdown:

1. image: (string)

   • The URL of the image to be displayed that’s received from our API service.

   • It’s used directly in the img tag's src attribute.

2. id: (string)

   • Unique identifier for each card that’s critical for tracking which cards have been clicked.

   • It’s passed to the processTurn callback when a card is clicked.

3. category: (string)

   • Describes the type of image (for example, "anime", "neko"), and it’s used in the alt attribute for better accessibility.

   • It helps with SEO and screen readers.

4. processTurn: (function)

   • Callback function passed from the parent component that handles the game logic when a card is clicked.

   • It also manages score updates and game state changes and determines if a card has been clicked before.

5. isLoading: (boolean)

   • Controls whether to show a loading state. When true, it displays a Loader component instead of the image.

   • It improves the user experience during image loading.

Component styling:

// src/components/Card/Card.module.scss
.container {
  display: flex;
  flex-direction: column;
  justify-content: center;
  align-items: center;
  background-color: rgba(255, 255, 255, 0.8);
  border: 1px solid rgba(0, 0, 0, 0.8);
  padding: 20px;
  font-size: 30px;
  text-align: center;
  min-height: 200px;
  position: relative;
  cursor: pointer;
  transition: transform 0.2s ease;

  &:hover {
    transform: scale(1.02);
  }

  .image {
    width: 10rem;
    height: auto;
    opacity: 1;
    transition: opacity 0.3s ease;

    &.hidden {
      opacity: 0;
    }
  }

  .loaderContainer {
    position: absolute;
    top: 50%;
    left: 50%;
    transform: translate(-50%, -50%);
  }
}

Usage in the component:

<Card
    key={getKey()}
    imgUrl={item?.image?.original?.url || ""}
    imageId={item?.id}
    categoryName={item?.category}
    processTurn={(imageId) => processTurn(imageId)} 
/>

Key features:

1. Performance Optimization:

   • Uses React.memo to prevent unnecessary re-renders

   • Implements useCallback for event handlers

   • Manages loading state internally for better UX

2. Loading State Management:

   • Internal isLoading state tracks image loading

   • Shows a Loader component with a message while loading

   • Hides the image until it's fully loaded using CSS classes

3. Event Handling:

   • handleImageLoad: Manages the loading state transition

   • handleClick: Processes player moves via the processTurn callback

Build the CardsGrid Component

This is our main game component that manages the game state, scoring logic, and card interactions. Let's break down its implementation:

// src/components/CardsGrid/CardsGrid.jsx
import React, { useState, useEffect } from "react";
import { useLocalStorage } from "@uidotdev/usehooks";
import Card from "../Card";
import Loader from "../Loader";
import styles from "./CardsGrid.module.scss";
import useFetch from "../../hooks/useFetch";

function CardsGrid(data) {
  // State Management
  const [images, setImages] = useState(data?.data?.images || []);
  const [clickedImages, setClickedImages] = useLocalStorage("clickedImages", []);
  const [score, setScore] = useLocalStorage("score", 0);
  const [bestScore, setBestScore] = useLocalStorage("bestScore", 0);
  const [isLoading, setIsLoading] = useState(!data?.data?.images?.length);

  // Custom hook for fetching images
  const { data: fetchedData, fetchData, error } = useFetch();

  // Update images when new data is fetched
  useEffect(() => {
    if (fetchedData?.images) {
      setImages(fetchedData.images);
      setIsLoading(false);
      // Reset clicked images when new batch is loaded
      setClickedImages([]);
    }
  }, [fetchedData]);

  // Helper function to update best score
  function updateBestScore(currentScore) {
    if (currentScore > bestScore) {
      setBestScore(currentScore);
    }
  }

  // Core game logic
  function processTurn(imageId) {
    const newClickedImages = [...clickedImages, imageId];
    setClickedImages(newClickedImages);

    // If clicking the same image twice, reset everything
    if (clickedImages.includes(imageId)) {
      // Update the best score if necessary
      updateBestScore(score);

      setClickedImages([]);
      setScore(0);
    } else {
      // Handle successful card selection
      const newScore = score + 1;
      setScore(newScore);

      // Check for perfect score (all cards clicked once)
       if (newClickedImages.length === images.length) {
        updateBestScore(newScore);
        fetchData();
        setClickedImages([]);
      } else {
        // Shuffle the images
        const shuffled = [...images].sort(() => Math.random() - 0.5);
        setImages(shuffled);
      }
    }
  }

 if (error) {
    return <p>Failed to fetch data</p>;
  }

  if (isLoading) {
    return <Loader message="Loading new images..." />;
  }

  return (
    <div className={styles.container}>
      {images.map((item) => (
        <Card
          key={getKey()}
          imgUrl={item?.image?.original?.url || ""}
          imageId={item?.id}
          categoryName={item?.category}
          processTurn={(imageId) => processTurn(imageId)}
        />
      ))}
    </div>
  );
}

export default React.memo(CardsGrid);

Component styling:

.container {
  display: grid;
  gap: 1rem 1rem;
  grid-template-columns: auto; /* Default: one column for mobile-first */
  background-color: #2196f3;
  padding: 0.7rem;
  cursor: pointer;
}

@media (min-width: 481px) {
  .container {
    grid-template-columns: auto auto; /* Two columns for tablets and up */
  }
}

@media (min-width: 769px) {
  .container {
    grid-template-columns: auto auto auto; /* Three columns for desktops and larger */
  }
}

Key Features Breakdown:

1. State Management:

   • Uses useState for component-level state

   • Implements useLocalStorage for persistent game data:

     • clickedImages: Tracks which cards have been clicked

     • score: Current game score

     • bestScore: Highest score achieved

   • Manages loading state for image fetching

   • Shuffle the cards

2. Game Logic:

   • processTurn: Handles player moves

     • Tracks duplicate clicks

     • Updates scores

     • Manages perfect score scenarios

   • updateBestScore: Updates high score when necessary

   • Automatically fetches new images when a round is completed

3. Data Fetching:

   • Uses custom useFetch hook for image data

   • Handles loading and error states

   • Updates images when new data is fetched

4. Performance Optimization:

   • Component wrapped in React.memo

   • Efficient state updates

   • Responsive grid layout

5. Persistence:

   • Game state persists across page reloads

   • Best score tracking

   • Current game progress saving

Usage Example:

...
...

function App() {
  const { data, loading, error } = useFetch();

  if (loading) return <Loader />;
  if (error) return <p>Error: {error}</p>;

  return (
    <div className={styles.container}>
      <Header />
      <Subtitle />
      <CardsGrid data={data} />
      <Footer />
    </div>
  );
}
export default App;

The CardsGrid component serves as the heart of our memory card game, managing:

• Game state and logic

• Score tracking

• Card interactions

• Image loading and display

• Responsive layout

• Data persistence

This implementation provides a smooth gaming experience while maintaining code readability and maintainability through clear separation of concerns and proper state management.

3. Implementing the API Layer

Our game uses a robust API layer with multiple fallback options to ensure reliable image delivery. Let's implement each service and the fallback mechanism.

Set Up the Primary API Service:

// src/services/api/nekosiaApi.js
const NEKOSIA_API_URL = "https://api.nekosia.cat/api/v1/images/catgirl";

export async function fetchNekosiaImages() {
  const response = await fetch(
    `${NEKOSIA_API_URL}?count=21&additionalTags=white-hair,uniform&blacklistedTags=short-hair,sad,maid&width=300`
  );

  if (!response.ok) {
    throw new Error(`Nekosia API error: ${response.status}`);
  }

  const result = await response.json();

  if (!result.images || !Array.isArray(result.images)) {
    throw new Error('Invalid response format from Nekosia API');
  }

  const validImages = result.images.filter(item => item?.image?.original?.url);

  if (validImages.length === 0) {
    throw new Error('No valid images received from Nekosia API');
  }

  return { ...result, images: validImages };
}

Create the First Fallback API Service:

// src/services/api/nekosBestApi.js
const NEKOS_BEST_API_URL = "https://nekos.best/api/v2/neko?amount=21";

export async function fetchNekosBestImages() {
  const response = await fetch(NEKOS_BEST_API_URL, {
    method: "GET",
    mode: "no-cors"
  });

  if (!response.ok) {
    throw new Error(`Nekos Best API error: ${response.status}`);
  }

  const result = await response.json();

  // Transform the response to match our expected format
  const transformedImages = result.results.map(item => ({
    id: item.url.split('/').pop().split('.')[0], // Extract UUID from URL
    image: {
      original: {
        url: item.url
      }
    },
    artist: {
      name: item.artist_name,
      href: item.artist_href
    },
    source: item.source_url
  }));

  return { images: transformedImages };
}

Create the Second Fallback API Service:

// src/services/api/nekosApi.js
const NEKOS_API_URL = "https://api.nekosapi.com/v3/images/random?limit=21&rating=safe";

export async function fetchNekosImages() {
  const response = await fetch(NEKOS_API_URL, {
    method: "GET",
  });

  if (!response.ok) {
    throw new Error(`Nekos API error: ${response.status}`);
  }

  const result = await response.json();

  // Transform the response to match our expected format
  const transformedImages = result.items.map(item => ({
    id: item.id,
    image: {
      original: {
        url: item.image_url
      }
    }
  }));

  return { images: transformedImages };
}

Build the API Fallback Mechanism:

// src/services/api/imageService.js
import { fetchNekosiaImages } from "./nekosiaApi";
import { fetchNekosImages } from "./nekosApi";
import { fetchNekosBestImages } from "./nekosBestApi";

export async function fetchImages() {
  try {
    // Try primary API first
    return await fetchNekosiaImages();
  } catch (error) {
    console.warn("Primary API failed, trying fallback:", error);

    // Try first fallback API
    try {
      return await fetchNekosBestImages();
    } catch (fallbackError) {
      console.warn("First fallback API failed, trying second fallback:", fallbackError);

      // Try second fallback API
      try {
        return await fetchNekosImages();
      } catch (secondFallbackError) {
        console.error("All image APIs failed:", secondFallbackError);
        throw new Error("All image APIs failed");
      }
    }
  }
}

Use the Image Service:

// src/hooks/useFetch.js
import { useState, useEffect } from "react";
import { fetchImages } from "../services/api/imageService";

export default function useFetch() {
  const [data, setData] = useState([]);
  const [loading, setLoading] = useState(true);
  const [error, setError] = useState(null);

  const fetchData = async () => {
    setLoading(true);
    setError(null);

    try {
      const result = await fetchImages();
      setData(result);
    } catch (err) {
      setError(err.message || 'An error occurred');
    } finally {
      setLoading(false);
    }
  };

  useEffect(() => {
    fetchData();
  }, []);

  return {
    data,
    loading,
    error,
    fetchData,
  };
}

Key Features of Our API Implementation:

1. Multiple API Sources:

   • Primary API (Nekosia): Provides high-quality anime images

   • First Fallback (Nekos Best): Includes artist information

   • Second Fallback (Nekos): Simple and reliable backup

2. Consistent Data Format:

   • All APIs transform their responses to match our expected format:

    {
      images: [
        {
          id: string,
          image: {
            original: {
              url: string
            }
          }
        }
      ]
    }

3. Robust Error Handling:

   • Validates API responses

   • Checks for valid image URLs

   • Provides detailed error messages

   • Graceful fallback mechanism

4. Safety Features:

   • Safe content filtering (rating=safe)

   • Image count limitation (21 images)

   • URL validation

   • Response format validation

5. Performance Considerations:

   • Optimized image sizes

   • Filtered content tags

   • Efficient data transformation

   • Minimal API calls

This implementation ensures our game has a reliable source of images while handling potential API failures gracefully. The consistent data format across all APIs makes it easy to switch between them without affecting the game's functionality.

Testing the App

Testing is a crucial part of any application development, and for our Memory Card Game, we implemented a comprehensive testing strategy using modern tools and practices. Let's dive into how we structured our tests and some key testing patterns we used.

Testing Stack

• Vitest: Our primary testing framework, chosen for its speed and seamless integration with Vite

• React Testing Library: For testing React components with a user-centric approach

• @testing-library/user-event: For simulating user interactions

• jsdom: For creating a DOM environment in our tests

Key Testing Patterns

Testing was a crucial part of ensuring the reliability and maintainability of this Memory Card Game. I implemented a comprehensive testing strategy using React Testing Library and Vitest, focusing on several key areas:

1. Component Testing

I wrote extensive tests for my React components to ensure they render correctly and behave as expected. For example, the CardsGrid component, which is the heart of the game, has thorough test coverage including:

• Initial rendering states

• Loading states

• Error handling

• Score tracking

• Card interaction behavior

2. Test Mocking

To ensure reliable and fast tests, I implemented several mocking strategies:

• Local storage operations using useLocalStorage hook

• API calls using the useFetch hook

• Event handlers and state updates

3. Testing Best Practices

Throughout my testing implementation, I followed several best practices:

• Using beforeEach and afterEach hooks to reset state between tests

• Testing user interactions using fireEvent from React Testing Library

• Writing tests that resemble how users interact with the app

• Testing both success and error scenarios

• Isolating tests using proper mocking

4. Testing Tools

The project leverages modern testing tools and libraries:

• Vitest: As the test runner

• React Testing Library: For testing React components

• @testing-library/jest-dom: For enhanced DOM testing assertions

• @testing-library/user-event: For simulating user interactions

This comprehensive testing approach helped me catch bugs early, ensured code quality, and made refactoring safer and more manageable.

Optimizations

To ensure smooth performance, especially on mobile devices, we implemented several optimization techniques:

1. Response Transformation

   • Standardized data format across all APIs

   • Efficient ID extraction from URLs

   • Structured image metadata for quick access

2. Network Optimization

   • Using no-cors mode where appropriate to handle CORS issues efficiently

   • Error handling with specific status codes for better debugging

   • Consistent response structure across all API implementations

3. Mobile-First Considerations

   • Optimized image loading strategy

   • Efficient error handling to prevent unnecessary retries

   • Streamlined data transformation to reduce processing overhead

Future Improvements

There are a few ways that we could further improve this project:

1. API Response Caching

   • Implement local storage caching for frequently used images

   • Add cache invalidation strategy for fresh content

   • Implement progressive image loading

2. Performance Optimizations

   • Add image lazy loading for better initial load time

   • Implement request queuing for better bandwidth management

   • Add response compression for faster data transfer

3. Reliability Enhancements

   • Add API health checking before attempts

   • Implement retry mechanisms with exponential backoff

   • Add circuit breaker pattern for failing APIs

4. Analytics and Monitoring

   • Track API success rates

   • Monitor response times

   • Implement automatic API switching based on performance metrics

This robust implementation ensures that our game remains functional and performant even under adverse network conditions or API unavailability, while still maintaining room for future improvements and optimizations.

Conclusion

Building this Memory Card Game has been more than just creating a fun, ad-free alternative for kids—it's been an exercise in implementing modern web development best practices while solving a real-world problem.

The project demonstrates how combining thoughtful architecture, robust testing, and reliable fallback mechanisms can result in a production-ready application that's both entertaining and educational.

🗝️ Key Takeaways

1. User-Centric Development

   • Started with a clear problem (ad-filled games affecting user experience)

   • Implemented features that enhance gameplay without interruptions

   • Maintained focus on performance and reliability across devices

2. Technical Excellence

   • Leveraged modern React patterns and hooks for clean, maintainable code

   • Implemented comprehensive testing strategy ensuring reliability

   • Created a robust API fallback system for uninterrupted gameplay

3. Performance First

   • Adopted mobile-first approach with responsive design

   • Optimized image loading and handling

   • Implemented efficient state management and caching strategies

📚 Learning Outcomes

This project showcases how seemingly simple games can be excellent vehicles for implementing complex technical solutions. From component architecture to API fallbacks, each feature was built with scalability and maintainability in mind, proving that even hobby projects can maintain professional-grade code quality.

🔮 Moving Forward

While the game successfully achieves its primary goal of providing an ad-free, enjoyable experience, the documented future improvements provide a clear roadmap for evolution. Whether it's implementing additional optimizations or adding new features, the foundation is solid and ready for expansion.

The Memory Card Game stands as a testament to how personal projects can both solve real-world problems and serve as platforms for implementing best practices in modern web development. Feel free to explore the code, contribute, or use it as inspiration for your own projects!

Last week, I came across one that involved building a "Wheel of Names." It reminded me of a similar project I built years ago using Flash and ActionScript 3—technologies that have since fallen out of use. So, I thought it would be fun to recreate the wheel, but this time using a modern tech stack.

In this tutorial, I’ll walk you through how I built it from scratch.

Table of Contents

• Project Description

• Why Would I Need a Wheel of Names?

• The Plan for the App

  • Application Features

  • The Tech Stack

• Let’s Build the App

  • Project Structure

  • How to Build the Components

• How to Deploy the App to Vercel

• Wrapping Up

Project Description

This will be an app that I presume is inspired by the TV show Wheel of Fortune. In the TV show, contestants try to figure out a short phrase by guessing letters. If they guess correctly, the letter will be revealed. They spin the wheel to determine how much money each correct letter is worth.

Wheel of Names is similar, but allows us to create a virtual wheel, putting our own names on it. We can then virtually spin it to determine a winner.

GitHub Repo

If you want to skip the reading, here 💁 is the GitHub repository with a detailed README 🙌. Here you can see the live demo.

Why Would I Need a Wheel of Names?

First of all, it’s a lot of fun to build your own! A practical, real-life use case would be for running lottery-style games where you need to pick a random winner.

For example, imagine you’re part of an agile team that holds retrospectives every two weeks, and you need to randomly choose a team member to lead each session. Just add everyone’s name to the participants list, spin the wheel, and let it decide for you! 🎡

The Plan for the App

The app is made up of several components, with the main feature being the spinning wheel. The wheel will have a section for each participant, and each section will be uniquely coloured, with its size proportionally calculated based on the number of participants. Once the spinning animation finishes, the winner will be revealed with a fun, confetti-style popup.

Other parts of the app include a section to enter the question or phrase that the spin is for, as well as controls for adding participant names and displaying them in a neatly organised list.

The list will offer options to sort and shuffle the names. The sorting will arrange the names alphabetically, while the shuffle option will randomise them. You can also delete any previously added participant.

All of these changes are dynamically reflected on the wheel component, ensuring that the wheel stays up-to-date with the latest participant list.

Here are a few screenshots that showcase what the app will look like once it's complete.

Here are some YouTube videos I recorded after completing the app, showcasing its features in action.

Application features:

I. Question

1. This is where users can submit a question or phrase that will determine the focus of the spins.

2. Any changes made in the input field are saved when the user clicks outside of it (on focus out).

II. Wheel

1. The wheel component spins with an easing animation and determines the winner.

2. The spin direction can be adjusted using the buttons, for either clockwise or counterclockwise rotation.

3. Each adjacent sector is uniquely coloured, and their sizes are calculated proportionally to the number of participants.

III. Add Participants

1. The participant entry area includes an input field for entering a participant's name and an 'ADD' button to add it to the participants list.

2. To add participants more quickly, the user can press the ENTER key on the keyboard.

IV. Participants List

1. This section displays all the participants' names.

2. The list offers options to sort the names alphabetically or shuffle them randomly, with both actions dynamically updating the wheel component.

The Tech Stack

Here’s a list of the main technologies we’ll be using:

• Bun – A fast JavaScript bundler and package manager, known for its speed and simplicity.

• Vite – A build tool that provides a fast development environment, particularly optimised for modern web projects.

• React – A popular JavaScript library for building user interfaces, enabling efficient rendering and state management.

• TypeScript – A superset of JavaScript that adds static typing, improving code quality and maintainability.

• styled-components – A library for writing CSS-in-JS, allowing styles to be scoped to components and providing a more dynamic approach to styling.

• canvas – A powerful HTML element used to draw graphics, animations, and other dynamic content directly on the web page.

• canvas-confetti – A JavaScript library for adding fun, celebratory confetti animations to the canvas, perfect for announcing winners.

Let’s Build the App

From this point onward I will guide you through the process I followed when building this app.

Project Structure

The project structure is quite straightforward, thanks to React and styled-components, which make this modular approach easy to implement. You can check out the project structure in my GitHub repo.

Below, I’ll walk you through the reasoning behind the structure and explain the decisions I made for each part.

• main.tsx: The entry point of the React app created with Vite.

• App.tsx: The parent component that includes all other components and handles participant name management (adding, removing, sorting, shuffling).

• Header.tsx: Top part of the app, which renders the app title.

• Participants.tsx: Renders the controls for adding and displaying participants. It includes a validation function to prevent empty or invalid names.

• Question.tsx: Displays the question section, managing state and basic keyboard and click functionality.

• Wheel.tsx: The core component containing the animation logic, sector size/colouring, and rendering participant names. It uses the canvas element for smooth spinning and integrates confetti to announce the winner.

• utils.ts: A file with helper functions used across the app.

• styles.ts: Contains shared styled components, exported for use throughout the app.

CSS Files and Configs

The remaining files in the project include standard boilerplate CSS styles from the initial Vite setup, along with configuration files for Vite, TypeScript, Prettier, and ESLint. These configurations are commonly used in modern projects and are not specific to this app, so I won't dive into them here. You can easily find documentation for each online.

How to Build the Components

In this section, we will go through the process of building each component of the application, step by step. By the end, you’ll have a fully functional app with modular, self-contained components.

1. App component

The App component serves as the central container for the entire application. It encapsulates all the core building blocks and is responsible for managing the state of the participants' names. Beyond rendering the UI, it handles key application logic, such as adding, removing, sorting, and shuffling participants.

The component uses local state to hold the list of names. This state is updated through callback functions that are triggered by interactions in the child components — specifically, the Participants and Wheel components.

The primary handler functions, handleAddName and handleRemoveName, manage adding and removing names from the list. Additionally, there are two other handlers dedicated to manipulating the order of the names: one for sorting (handleSortNames) and one for shuffling (handleShuffleNames). These handlers provide flexibility in how the list of participants is displayed and interacted with in the app.

const [names, setNames] = useState<string[]>([]);

  const handleAddName = (name: string) => {
    if (names.length < MAX_PARTICIPANTS) {
      setNames([...names, name]);
    }
  };

  const handleRemoveName = (index: number) => {
    setNames(names.filter((_, i) => i !== index));
  };

  const shuffleNames = () => {
    const shuffledNames = [...names].sort(() => Math.random() - 0.5);
    setNames(shuffledNames);
  };

  const sortNames = () => {
    const sortedNames = [...names].sort((a, b) => a.localeCompare(b));
    setNames(sortedNames);
  };

A crucial part of the component is the MAX_PARTICIPANTS constant, which sets a limit on the number of participants allowed. This ensures that the app doesn't exceed a certain number of entries, maintaining performance and usability.

The rendering structure of this component looks as follows:

 return (
    <>
      <Header />
      <Question />
      <Main>
        <Participants
          handleAddName={handleAddName}
          handleRemoveName={handleRemoveName}
          shuffleNames={shuffleNames}
          sortNames={sortNames}
          names={names}
        />
        <Wheel participants={names} />
      </Main>
    </>
  );

2. Header component

The Header component is the simplest part of the application. Its primary role is to display the title at the top of the page. This component is essential for setting the tone and branding of the application. Despite its simplicity, it lays the foundation for structuring the UI and can be easily customised or extended in the future.

Here is how it looks:

3. Question component

The component that displays the input for entering a question or phrase is relatively simple. It renders a text field and utilises a few handler functions to enhance the user experience. These handlers manage focus behaviour: setting focus when the input field is clicked, removing focus when the user clicks outside the field, and allowing the user to use the ENTER or ESCAPE keys to submit or cancel their input, respectively.

4. Participants

In this part of the app, we render the list of all added participants. The component includes a local validation function that runs each time before adding a new participant, ensuring that the input meets the necessary criteria (for example, no duplicates or empty names).

We also leverage built-in HTML attributes to dynamically enable or disable buttons based on the state of the participants list. For example, the "Sort" and "Shuffle" buttons are disabled when the list is empty, while the "Add" button is disabled once the maximum participant limit (MAX_PARTICIPANTS) has been reached. This ensures a smooth and intuitive user experience by preventing invalid actions.

You’ve probably already noticed how we use a utility function from the utils.ts file to capitalise the participant names before displaying them. This ensures that all names are presented in a consistent and user-friendly format.

This happens inside a map() loop, where we iterate over the names data structure and display each participant's name in a separate row within the list component. The utility function is applied during this iteration to ensure that the names are properly capitalised before rendering.

5. Wheel component

This is the largest component in our app. At the top, you'll find the styles required to position the winning popup, which is accompanied by confetti when a winner is selected. Below that, we define an array containing all the possible colours used to color the wheel sectors. Afterward, we move into the component code itself.

The component utilises several states to ensure the spinning animation behaves as expected. Additionally, it manages when to trigger and display the winner popup, with the winner's name shown inside. These states and handlers work together to create a smooth and interactive experience.

 const [spinning, setSpinning] = useState(false);
  const [rotation, setRotation] = useState(0);
  const [spinDirection, setSpinDirection] = useState<
    'clockwise' | 'counterclockwise'
  >('clockwise');
  const [showPopup, setShowPopup] = useState(false);
  const [popupWinner, setPopupWinner] = useState<string | null>(null);

The drawWheel() method is responsible for rendering the wheel with the specified number of sectors on the canvas. This method relies heavily on the canvas element and its associated API to draw each sector and participant's name. We also use our helper function to capitalise the participants' names in the wheel, ensuring consistency with the list component.

When the "Spin" button is clicked, the startSpin() method is triggered. This is where the animation logic is implemented. We generate a random number of rotations, ranging from 5 to 10 full rotations, to make the spin feel unpredictable.

The direction of the spin is determined by the user's selection, allowing the wheel to spin either clockwise or counterclockwise. We also set the spin duration to 6000ms (6 seconds) for a smooth and engaging animation.

To enhance the realism of the animation, we apply an easing function that implements the "Ease-out cubic" effect, which causes the wheel to gradually slow down as it reaches the end of the spin.

 const easing = (t: number) => {
      // Ease-out cubic
      return 1 - Math.pow(1 - t, 3);
    };

The animation is handled by an inner function called animate(), which utilises the requestAnimationFrame API, a feature supported by all modern browsers for smooth, high-performance animations. Inside this function, we calculate the elapsed time and the current rotation, updating the component's state accordingly to ensure the wheel spins smoothly.

During each animation frame, we also invoke the determineWinner() function, which is defined below. This function calculates the winning sector by determining which sector the wheel lands on at the end of the spin. It then updates the popup state to display the winner’s name inside the popup.

const determineWinner = (finalRotation: number) => {
    const sliceAngle = 360 / numSectors;
    const normalizedRotation = ((finalRotation % 360) + 360) % 360;
    const winningSector = Math.floor(normalizedRotation / sliceAngle);

    setPopupWinner(participants[winningSector]);
    setShowPopup(true);
  };

Changing the direction of the spin is straightforward. We simply update the component’s state based on the value of the button’s label, which toggles between "Clockwise" and "Counterclockwise." By setting the state accordingly, we can easily control the spin direction with a single click of the button.

The remaining code before the rendering part of this component includes an effect that controls the visibility of the confetti popup. The startConfetti function is responsible for initiating the confetti animation when a winner is selected. This effect ensures that the confetti animation is triggered and displayed at the right moment, adding a celebratory touch to the experience.

And with all that we are ready to render our Wheel component as it follows:

return (
    <div>
      <canvas
        ref={canvasRef}
        width={400}
        height={400}
        style={{ borderRadius: '50%', border: '2px solid black' }}
      />
      <ButtonsContainer>
        <Button
          onClick={changeSpinDirection}
          disabled={participants.length === 0 || spinning}
        >
          {capitalize(spinDirection)}
        </Button>
        <Button
          onClick={startSpin}
          disabled={participants.length === 0 || spinning}
        >
          Spin
        </Button>
      </ButtonsContainer>
      {showPopup && popupWinner && (
        <Popup>
          <h2>Congratulations!</h2>
          <h3>{capitalize(popupWinner)}</h3>
        </Popup>
      )}
    </div>

How to Deploy the App to Vercel

Finally 🎉 we’re ready to deploy our app.

I used Vercel for this deployment because it offers a fast, free, and easy way to deploy web apps. If you'd like a more detailed guide on how to deploy with Vercel, check out my previous tutorial for step-by-step instructions.

Wrapping Up

I hope you found this process as interesting and enjoyable to follow as it was for me to create!

Now, let’s take a moment to reflect on what we’ve accomplished and highlight a few key takeaways that could prove useful for future projects.

1. Modular Design: Breaking the app into small, manageable components made it easier to maintain and scale.

2. React and Styled-Components: These tools streamlined the development, allowing for dynamic styling and efficient UI management.

3. Canvas for Animations: Leveraging the canvas element enabled smooth and visually appealing animations.

4. Vercel Deployment: Vercel's simplicity and speed made it the ideal choice for quickly deploying the app.

This project highlighted the power of modern tools like React, TypeScript, and canvas, all while ensuring the app stayed modular and easy to maintain.

Thanks for reading! 🙏

We'll talk about the technology stack and the features it will have in a minute. I'll also walk you through the process step-by-step. But first, let me show you what it's going to look like.

Let’s sketch 🙃

Product List

We are going to make our app mobile friendly by implementing a decent level of responsiveness.

Product List - Mobile

Cart Desktop

Cart Mobile

This time, before going directly into building this project, I decided to go more traditional. I took a pen and paper and drew these ugly sketches, just to make sure I had a visual idea of what I would be building.

And honestly, it really did the trick ✨. This technique helps when you are about to sit at your computer and ask the question:

What do I start with now?

TL;DR

💡 If you want to skip the reading, here 💁 is the GitHub repository with a detailed README 🙌, and here you can see the live demo.

What’s a Shopping Cart?

Shopping Carts

A shopping cart lets people carry or store their goods while they're shopping – either online or in real life.

In ecommerce apps, the shopping cart is a place where the user can store and view the items they are considering purchasing. Typically, this is a separate page or part of the page where people can view a list of the items they have chosen to buy before actually paying for them.

The Plan for Our App

We will build an application consisting of two pages: a product list page and a cart page.

The app will fetch the data from a 3rd party RESTful API and it'll use the browser’s localStorage to store selected items that should be displayed in the cart.

Application features

The shopping cart application must fetch and display products from the API endpoint https://dummyjson.com/products.

The Products List page should display the available items along with some specific information. For example, it should show 3 products per row for large viewports. Each item should display at least a thumbnail image, a title, the price (formatted as GBP, for example £100.23), and an “Add to Cart” button which adds the item to the cart.

Cart page should display the customer's chosen items. Each item should display at least a thumbnail image, a title, plus and minus buttons (for adding/removing items) and the current quantity of the item in the cart, like this:

Plus and minus buttons

If there is a quantity of 1 item in the cart, hitting minus removes it from the cart. The cart should also display the total price of all items added (formatted as GBP, for example, £100.23).

In addition to these basic features, the UI/UX should be as sleek as possible. We also want to make sure we unit test the application.

Tech Stack

If you've had the chance to take a look at some of my others tutorials, the tech stack I chose won’t surprise you much.

I picked these technologies taking into account the requirements for the application – that it would be performant, well tested, and have a sleek look and feel.

• React / TypeScript / Vite – for the UI library we're going again with a React and Vite development environment. But this time we will use it with TypeScript instead of JavaScript.

• SASS / CSS Modules – for styling our app, we'll bet on the battle-tested solution of CSS Modules with SASS/SCSS.

• react-testing-library / Vitest – for testing the app, we'll use react-testing-library and Vitest.

If you want to learn more about RTL, here is an insightful tutorial by a very knowledgable guy that can help you out.

How to Build the App

In this section we will take a look at the project structure and I'll explain why I chose it.

Then I'll go briefly through each of the components and describe its role.

Once you understand how the components work together to create a functioning application, we'll explore how to utilize the browser's local storage to store data that can be used in other parts of the app.

📦 Dependencies

Let's take a brief look at our project's dependencies. These are external packages we need to install in order to ensure the successful execution of our project.

Along with Vite and Vitest, I have installed SASS, React Testing Library, and use-local-storage-state. See below my package.json file.

{
  "name": "shopping-cart-app",
  "private": false,
  "version": "1.0.0",
  "author": "Mihail Gaberov",
  "type": "module",
  "scripts": {
    "dev": "vite",
    "test": "vitest",
    "build": "tsc && vite build",
    "lint": "eslint src --ext ts,tsx --report-unused-disable-directives --max-warnings 0",
    "preview": "vite preview"
  },
  "dependencies": {
    "react": "^18.2.0",
    "react-dom": "^18.2.0",
    "react-router-dom": "^6.13.0"
  },
  "devDependencies": {
    "@testing-library/jest-dom": "^5.16.5",
    "@testing-library/react": "^14.0.0",
    "@types/react": "^18.0.37",
    "@types/react-dom": "^18.0.11",
    "@typescript-eslint/eslint-plugin": "^5.59.0",
    "@typescript-eslint/parser": "^5.59.0",
    "@vitejs/plugin-react": "^4.0.0",
    "eslint": "^8.38.0",
    "eslint-plugin-react-hooks": "^4.6.0",
    "eslint-plugin-react-refresh": "^0.3.4",
    "jsdom": "^22.1.0",
    "sass": "^1.63.4",
    "typescript": "^5.0.2",
    "use-local-storage-state": "^18.3.3",
    "vite": "^4.3.9",
    "vitest": "^0.32.0"
  }
}

🧑🏻‍💻 Installation

In this step I assume you are starting from scratch. We are going to use Vite for scaffolding the project. In order to do that you need to have Node.js installed on your system – at least version 14.18. I suggest that you update it to the latest stable version. And as a package manager you may go with either npm or yarn.

Once you have one of these installed on your system, open your Terminal app and run the following:

yarn create vite your-app-name --template react-ts

This command will install the initial application files in a folder named 'your-app-name'. After that step you will be able to open it in your favorite IDE and start working on it.

One last thing you should do here is to install to additional packages I mentioned in the previous section. You can do that by running the following:

yarn add -D sass @testing-library/react use-local-storage-state

🏗️ Project Structure

Project Structure

This won't be much of a surprise for those of you who have some experience in building React applications. The structure I've chosen is pretty standard.

The root level of the app contains files related to configurations and setup, as well as the HTML index file. This is where the main JavaScript module is loaded and the app is launched.

index.html

The src folder (short for "source") contains two sub-folders: one for assets and one for components.

The public and screenshots folders have straightforward purposes. The .github folder contains the YAML configuration file that is used by GitHub Actions. We will discuss this in more detail later on.

🛠️Components

App Components

All components are organized into separate folders. Within each folder, you'll find an index.ts file that exports the component. This file uses named exports, as shown below.

Named export - Header component

We'll start by examining the components from a top-to-bottom approach, as they are seen and used within the application. To help clarify, let me provide a visualization.

App Components Visualized in Order

Here's what each of these components does in more detail:

Header – holds the top part of the app. On the left side is the logo image, an SVG I have downloaded from Iconify. On the right side sits the CartWidget component.

CartWidget – renders a button composed of an SVG image depicting a shopping cart and a number value indicating the count of products currently added to the cart. When clicked, the button takes the user to the cart page.

Products – this component is responsible for rendering the main content of the page, which consists of a list of products. On larger viewports, the products are displayed in three columns per row. Each product is represented by a thumbnail image, a title, price information, and an "Add to Cart" button. The price of each product is formatted to GBP using the CurrencyFormatter component.

CurrencyFormatter – formats given numeric amount to GBP – that is, 499 would become £499.00.

App Components Visualized

Cart – this component is responsible for rendering the main content of the page. It displays one product per row and includes a quantifier component that allows the user to update the quantity of the product. At the bottom of the page, it also shows the total price of the selected products, which is formatted as GBP using the CurrencyFormatter component.

Quantifier – this component displays plus and minus buttons along with an input field positioned between them. It serves the purpose of indicating the current quantity of a product and enables the user to modify this value. Additionally, it offers functionality to remove the product entirely from the shopping cart.

Footer – this component is designed to provide a simple and visually representative way to display information about the author and copyrights.

Loader – this component is not visible on the screenshots above, but it represents a simple loading animation that becomes visible once the user opens the app for first time and the products data is still being loaded.

🧩 How to Build the Header

As mentioned earlier, the upper section of the application, commonly referred to as the 'hat', is known as the header. In our specific case, the header comprises two elements: the logo positioned on the left and the CartWidget on the right.

Application Header

Now, let's go through the process of constructing the application together 🙌. The steps outlined below are applicable to every component we incorporate into the app.

To begin, I create a dedicated folder for the component and include an index.ts file within it. This file will serve as the export module for the component.

Creating Header Component

This is where we export the actual component like that:

export { Header } from'./Header'

Then we implement the component itself. This code will go into a file named the same thing – Header.tsx

import { FunctionComponent } from 'react'


export const Header: FunctionComponent = () => {

  return (
    <header>
      header content here...
    </header>
  )
}

We're starting simple.

Currently, this component only displays the text 'header content here...' on the page. Our goal is to gradually enhance it until we achieve the final result depicted in the picture above.

To do this, it is important to incorporate styling into the process. By utilizing CSS Modules, we can import a separate SCSS file containing the styles required for our component.

import { FunctionComponent } from 'react'
import classes from './header.module.scss' // <---- imports the styles

export const Header: FunctionComponent = () => {

  return (
    <header>
      header content here...
    </header>
  )
}

This file must exist in our component's folder. After including the tests file, the folder structure for this component will resemble the following:

Header Component's Folder

Let's enhance the component's code by incorporating the necessary elements. On the left side, we'll add the logo element, which will function as a clickable link. We'll also include the CartWidget component that displays the count of the selected products.

import { FunctionComponent } from 'react'


export const Header: FunctionComponent = () => {

  return (
    <header className={classes.header}>
      <div>
        <Link to="/">
          <img src={logo} className={classes.logo} alt="Shopping Cart Application" />
        </Link>
      </div>
      <div>
        <CartWidget productsCount={productsCount} />
      </div>
    </header>
  )
}

To achieve a nice look and feel, and a decent level of responsiveness, we'll use the following styles:

.header {
  width: 100%;
  display: flex;
  align-items: center;
  background-color: #213547;
  transition: height 0.3s ease;
  position: fixed;
  right: 0;
  left: 0;
  top: 0;
  opacity: 0.9;
  backdrop-filter: saturate(180%) blur(20px);
  justify-content: space-between;
  z-index: 1;

  .logo {
    height: 6em;
    padding: 1.5em;
    will-change: filter;
    transition: filter 300ms;
    transform: scaleX(-1);


    &:hover {
      filter: drop-shadow(0 0 2em #646cffaa);
    }
  }
}

I will show you the code for the widget component below, but before that I want you to notice how we pass the products count value a prop. This way we can free ourselves from implementing any logic in the component itself and use it only for representational purposes.

That being said, here is the code of the component:

import { FunctionComponent } from 'react'
import { useNavigate } from 'react-router-dom'

import shoppingCart from '../../assets/shopping-cart.svg'
import classes from './cart-widget.module.scss'

interface Props {
  productsCount: number
}

export const CartWidget: FunctionComponent<Props> = ({ productsCount }) => {
  const navigate = useNavigate()

  const navigateToCart = () => {
    navigate('/cart')
  }

  return (
    <button className={classes.container} onClick={navigateToCart}>
      <span className={classes.productsCount}>{productsCount}</span>
      <img src={shoppingCart} className={classes.shoppingCart} alt="Go to Cart" />
    </button>
  )
}

And its styling:

.container {
  margin: 1rem;
  padding: 0 1rem;
  display: flex;
  border: none;
  background: none;
  cursor: pointer;
  align-items: center;
  flex-direction: row-reverse;
  justify-content: space-between;

  &:hover {
    outline: 1px solid white;
  }


  .shoppingCart {
    height: 3em;
    padding: 1.5rem .4rem;
    will-change: filter;
    transition: filter 300ms;
  }

  .productsCount {
    z-index: 1;
    font-size: 2em;
    top: 38px;
    color: orange;
  }
}

Header Shrinking

Before we proceed, there is one more aspect to discuss: the smooth shrinking animation of the header that you can see while scrolling down.

Header Shrinking

To accomplish this, I used React hooks along with a technique involving manual manipulation of styles for various DOM elements.

I implemented this functionality within a component method called shrinkHeader, which is invoked whenever a user scrolls. Within this method, I check if the current vertical scroll position exceeds a specified threshold value, DISTANCE_FROM_TOP, and accordingly apply different styles based on the outcome of this comparison.

One aspect we haven't discussed yet is using the hook for managing local storage, which we'll talk about later.

Here is the completed version of the component:

import { FunctionComponent, useEffect } from 'react'
import { Link } from 'react-router-dom'
import useLocalStorageState from 'use-local-storage-state'

import logo from '/logo.svg'
import { CartWidget } from '../CartWidget'
import { CartProps } from '../Products/Products.tsx'
import classes from './header.module.scss'

export const Header: FunctionComponent = () => {
  useEffect(() => {
    window.addEventListener("scroll", () => shrinkHeader(), false)

    return () => {
      window.removeEventListener("scroll", () => shrinkHeader())
    }
  }, [])

  const shrinkHeader = () => {
    const DISTANCE_FROM_TOP = 140
    const headerElement = document.querySelector("header") as HTMLElement
    const logoElement = document.querySelectorAll("img")[0] as HTMLElement
    const cartWidgetElement = document.querySelectorAll("img")[1] as HTMLElement
    const productsCountElement = document.querySelector("span") as HTMLElement
    const scrollY = document.body.scrollTop || document.documentElement.scrollTop

    if (scrollY > DISTANCE_FROM_TOP) {
      headerElement.style.transition = "height 200ms ease-in"
      headerElement.style.height = "80px"
      logoElement.style.transition = "height 200ms ease-in"
      logoElement.style.height = "4rem"
      cartWidgetElement.style.transition = "height 200ms ease-in"
      cartWidgetElement.style.height = "2rem"
      productsCountElement.style.transition = "font-size 200ms ease-in"
      productsCountElement.style.fontSize = "1.5em"
    } else {
      headerElement.style.height = "150px"
      logoElement.style.height = "6rem"
      cartWidgetElement.style.height = "3rem"
      productsCountElement.style.fontSize = "2em"
    }
  }
  const [cart,] = useLocalStorageState<CartProps>('cart', {})

  const productsCount: number = Object.keys(cart || {}).length

  return (
    <header className={classes.header}>
      <div>
        <Link to="/">
          <img src={logo} className={classes.logo} alt="Shopping Cart Application" />
        </Link>
      </div>
      <div>
        <CartWidget productsCount={productsCount} />
      </div>
    </header>
  )
}

🧩 How to Build the Product List

Product List

To construct the product list component, I followed the same approach as above. Initially, I established the foundational structure, which involved creating the component code, exporting the component in the index file, and implementing a separate SCSS file to define the component's styles.

As a result, the folder structure after completing these steps should resemble the following:

Product List Component Folder

One interesting aspect of this component is that it handles sending a request to a REST API in order to fetch the product data. This is accomplished through the fetchData method, which is invoked within a useEffect hook.

By specifying an empty dependency array, the code inside the useEffect hook is executed only once when the component is initially loaded. This ensures that redundant requests are avoided, optimizing the performance of our application and reducing bandwidth usage.

 useEffect(() => {
    fetchData(API_URL)
  }, [])


  async function fetchData(url: string) {
    try {
      const response = await fetch(url)
      if (response.ok) {
        const data = await response.json()
        setProducts(data.products)
        setIsLoading(false)
      } else {
        setError(true)
        setIsLoading(false)
      }
    } catch (error) {
      setError(true)
      setIsLoading(false)
    }
  }

The rendering aspect of the component is relatively straightforward. Once we have successfully fetched the product data, we can iterate through it using a regular map() function. For each product, we can render its thumbnail image, title, price, and a button for adding it to the cart.

To ensure that each row displays three items when viewed on large viewports, we utilize CSS (SCSS) styles. We'll do this by harnessing the capabilities of Flexbox, as demonstrated in the following snippet:

.productPage {
  padding: 1rem;
  margin-top: 8rem;

  .container {
    display: flex;
    flex-wrap: wrap;
    justify-content: space-between;

    .product {
      flex-basis: 33.33%;
      margin-bottom: 5rem;
      text-align: center;

      h3 {
        color: #007185;
        font-weight: 700;
        line-height: 20px;
        margin: 0;
      }

      img {
        height: 6rem;
      }

      button {
        background-color: #fbd815;
        width: 13rem;
        padding: .5rem;
        font-size: 1.1em;
        border-radius: 25px;
        border-color: #D5D9D9;
        border-style: solid;
        border-width: 1px;

        &:hover:not([disabled]) {
          background-color: #eecf1d;
          cursor: pointer;
        }

        &:disabled {
          opacity: .5;
          background-color: lightgray;
        }
      }
    }

    @media (max-width: 767px) {
      .product {
        flex-basis: 50%;
      }
    }

    @media (max-width: 400px) {
      .product {
        flex-basis: 100%;
      }
    }
  }
}

.error {
  color: red;
  text-align: center;
}

In addition to these features, the component code also includes functionality for handling the "Add to Cart" button click event, specifically adding the selected item to the local storage. We also implement basic error handling logic to display an error message in case the request to the third-party API fails.

Here is the completed component:

import { FunctionComponent, useEffect, useState } from 'react'
import useLocalStorageState from 'use-local-storage-state'

import { CurrencyFormatter } from '../CurrencyFormatter'
import classes from './products.module.scss'
import { Loader } from '../Loader'

const API_URL = 'https://dummyjson.com/products'

export type Product = {
  id: number
  title: string
  price: number
  thumbnail: string
  image: string
  quantity: number
}

export interface CartProps {
  [productId: string]: Product
}

export const Products: FunctionComponent = () => {
  const [isLoading, setIsLoading] = useState(true)
  const [products, setProducts] = useState<Product[]>([])
  const [error, setError] = useState(false)
  const [cart, setCart] = useLocalStorageState<CartProps>('cart', {})


  useEffect(() => {
    fetchData(API_URL)
  }, [])


  async function fetchData(url: string) {
    try {
      const response = await fetch(url)
      if (response.ok) {
        const data = await response.json()
        setProducts(data.products)
        setIsLoading(false)
      } else {
        setError(true)
        setIsLoading(false)
      }
    } catch (error) {
      setError(true)
      setIsLoading(false)
    }
  }

  const addToCart = (product: Product):void => {
    product.quantity = 1

    setCart((prevCart) => ({
      ...prevCart,
      [product.id]: product,
    }))
  }

  const isInCart = (productId: number):boolean => Object.keys(cart || {}).includes(productId.toString())

  if (error) {
    return <h3 className={classes.error}>An error occurred when fetching data. Please check the API and try again.</h3>
  }

  if (isLoading) {
    return <Loader />
  }


  return (
    <section className={classes.productPage}>
      <h1>Products</h1>

      <div className={classes.container}>
        {products.map(product => (
          <div className={classes.product} key={product.id}>
            <img src={product.thumbnail} alt={product.title} />
            <h3>{product.title}</h3>
            <p>Price: <CurrencyFormatter amount={product.price} /></p>
            <button disabled={isInCart(product.id)} onClick={() => addToCart(product)}>Add to Cart</button>
          </div>
        ))}
      </div>
    </section>
  )
}

🧩 How to Build the Cart

Cart Component

This component bears some resemblance to the Product List component in that it also lists products, but in a different manner with only one item per row.

It also introduces additional functionality by incorporating another component for updating the quantity of selected products. And it calculates the total price of all products in the cart.

 <section className={classes.cart}>
      <h1>Cart</h1>

      <div className={classes.container}>
        {getProducts().map(product => (
          <div className={classes.product} key={product.id}>
            <img src={product.thumbnail} alt={product.title} />
            <h3>{product.title}</h3>
            <Quantifier
              removeProductCallback={() => handleRemoveProduct(product.id)}
              productId={product.id}
              handleUpdateQuantity={handleUpdateQuantity} />
          </div>
        ))}
      </div>
      <TotalPrice amount={totalPrice} />
    </section>

The main distinction here is that instead of fetching the product data from an API, we retrieve it from the local storage. This is where we store the data for each selected product from the product list component.

const [cart, setCart] = useLocalStorageState<CartProps>('cart', {}) // reading the local storage value via the hook here

....
....

  const getProducts = () => Object.values(cart || {}) // method for getting all products data as an array data structure, that will allow us easier iteration later

....
....

In this case, we use the useEffect hook once again, but this time to reset the scroll position of the window whenever the user visits the page. This ensures that all relevant data is consistently visible to the user, regardless of how far they have scrolled on the product list page.

  useEffect(() => {
    window.scrollTo(0, 0)
  }, [location])

Indeed, you can see that the methods for decreasing or increasing the quantity of a product are passed to the component as callbacks through its props. This approach is useful as it helps maintain a relatively clean component by elevating the responsibility of state management to a higher level.

By lifting the logic for managing the state outside of the component, it allows for better separation of concerns and promotes reusability.

const handleRemoveProduct = (productId: number): void => {
    setCart((prevCart) => {
      const updatedCart = { ...prevCart }
      delete updatedCart[productId]
      return updatedCart
    })
  }

  const handleUpdateQuantity = (productId: number, operation: Operation) => {
    setCart((prevCart) => {
      const updatedCart = { ...prevCart }
      if (updatedCart[productId]) {
        if (operation === 'increase') {
          updatedCart[productId] = { ...updatedCart[productId], quantity: updatedCart[productId].quantity + 1 }
        } else {
          updatedCart[productId] = { ...updatedCart[productId], quantity: updatedCart[productId].quantity - 1 }
        }
      }
      return updatedCart
    })
  }

We can style the component using Flexbox to get our desired layout:

.cart {
  padding: 1rem;
  margin-top: 8rem;

  .container {
    display: flex;
    flex-direction: column;

    .product {
      display: flex;
      border-top: 1px dotted;
      border-left: 1px dotted;
      border-right: 1px dotted;
      padding: .3rem .5rem;
      align-items: center;

      h3 {
        color: #007185;
        font-weight: 700;
        font-size: 1em;
        line-height: 20px;
        margin: .3rem;
        flex: 1;
      }

      img {
        max-width: 3rem;
        height: auto;
        margin: .875rem;
      }
    }
  }
}

Here is the final version of the component's code:

import { FunctionComponent, useEffect } from 'react'
import useLocalStorageState from 'use-local-storage-state'

import { Quantifier } from '../Quantifier'
import { CartProps } from '../Products/Products.tsx'
import { TotalPrice } from '../TotalPrice'
import { Operation } from '../Quantifier/Quantifier.tsx'
import classes from './cart.module.scss'
import { useLocation } from 'react-router-dom'


export const Cart: FunctionComponent = () => {
  const [cart, setCart] = useLocalStorageState<CartProps>('cart', {})
  const location = useLocation()

  useEffect(() => {
    window.scrollTo(0, 0)
  }, [location])

  const handleRemoveProduct = (productId: number): void => {
    setCart((prevCart) => {
      const updatedCart = { ...prevCart }
      delete updatedCart[productId]
      return updatedCart
    })
  }

  const handleUpdateQuantity = (productId: number, operation: Operation) => {
    setCart((prevCart) => {
      const updatedCart = { ...prevCart }
      if (updatedCart[productId]) {
        if (operation === 'increase') {
          updatedCart[productId] = { ...updatedCart[productId], quantity: updatedCart[productId].quantity + 1 }
        } else {
          updatedCart[productId] = { ...updatedCart[productId], quantity: updatedCart[productId].quantity - 1 }
        }
      }
      return updatedCart
    })
  }


  const getProducts = () => Object.values(cart || {})

  const totalPrice = getProducts().reduce((accumulator, product) => accumulator + (product.price * product.quantity), 0)

  return (
    <section className={classes.cart}>
      <h1>Cart</h1>

      <div className={classes.container}>
        {getProducts().map(product => (
          <div className={classes.product} key={product.id}>
            <img src={product.thumbnail} alt={product.title} />
            <h3>{product.title}</h3>
            <Quantifier
              removeProductCallback={() => handleRemoveProduct(product.id)}
              productId={product.id}
              handleUpdateQuantity={handleUpdateQuantity} />
          </div>
        ))}
      </div>
      <TotalPrice amount={totalPrice} />
    </section>
  )
}

🧩 How to Build the Footer

To enhance the overall appearance of the application, I have included a footer component. Here is an example of how it looks:

The implementation of the footer component is relatively straightforward. It consists of two links to social platforms and a copyright text.

import { FunctionComponent } from 'react'
import classes from "./footer.module.scss"
import packageJson from '../../../package.json'

export const Footer: FunctionComponent = () => {
  const currentYear = new Date().getFullYear()

  return (
    <footer className={classes.footer} data-cy="footer">
      <ul>
        <li className={classes.footerLinks}>
          <a
            href="https://twitter.com/mihailgaberov"
            target="_blank"
            rel="noopener noreferrer"
            data-cy="twitterLink"
          >
            twitter
          </a>{" "}
          &bull;{" "}
          <a
            href="https://github.com/mihailgaberov"
            target="_blank"
            rel="noopener noreferrer"
            data-cy="githubLink"
          >
            github
          </a>
        </li>
        <li className={classes.footerCopyrights}>
          © {packageJson.author} {currentYear}. All rights reserved.
        </li>
        <li>
          <div className={classes.version}>v.{packageJson.version}</div>
        </li>
      </ul>
    </footer>
  )
}

Again, in the component folder you will find the other files that are necessary for applying the styles and the tests for that component.

🧪 Testing the App

I am sure you've already noticed that in all components folders, except the Loader one, we have .test.tsx files. These are the files containing the component tests that we run on the front end.

In order to do a test run, open your CLI and run the following command from the root directory of your project:

yarn test

This should run all tests and give you the following output:

Application Tests

Now that we've built all the necessary components, let's delve into a more detailed discussion about local storage and how we can leverage it to manage the application state more effectively.

🧠 What is LocalStorage?

Before we dive into the details, let's begin with a brief explanation of what local storage is. This will ensure that everyone, including those who are unfamiliar with it, can easily understand how we use this in the app.

App LocalStorage

LocalStorage is a feature provided by web browsers that allows web applications to store data locally on the user's device. It provides a simple key-value storage mechanism, similar to a dictionary or associative array.

Unlike session storage, which is temporary and gets cleared when the browser session ends, local storage persists even after the browser is closed and reopened. The data stored in local storage remains available until explicitly removed by the application or cleared by the user.

Local storage is primarily used for client-side data storage, enabling web applications to save user preferences, session data, or any other relevant information. This makes it a useful tool for creating personalized experiences and maintaining state across multiple visits to a website.

With that being said, you may have already guessed that local storage can be utilized to store the data of items added to the cart by the user. By doing so, when we navigate to the cart page, our application will be aware of which items should be displayed there.

To accomplish this, I utilized a React hook called use-local-storage-state.

In the Product List component, we added products to the LocalStorage whenever the user clicked on the Add to Cart button for each item. This ensured that the selected products were stored persistently.

Then, when the user navigates to the cart page, we retrieve the stored data from the LocalStorage and render the products accordingly. By doing so, the user can easily view and interact with the products they previously added to their cart.

Here is a snippet from the code itself.

We add the items to the LocalStorage like this:

const [cart, setCart] = useLocalStorageState<CartProps>('cart', {})
...
...
...

const addToCart = (product: Product):void => {
    product.quantity = 1

    setCart((prevCart) => ({
      ...prevCart,
      [product.id]: product,
    }))
  }

And then read the data like this:

const [cart, setCart] = useLocalStorageState<CartProps>('cart', {})
...
...
...

const getProducts = () => Object.values(cart || {})

And then render them like this:

<div className={classes.container}>
        {getProducts().map(product => (
          <div className={classes.product} key={product.id}>
            <img src={product.thumbnail} alt={product.title} />
            <h3>{product.title}</h3>
            <Quantifier
              removeProductCallback={() => handleRemoveProduct(product.id)}
              productId={product.id}
              handleUpdateQuantity={handleUpdateQuantity} />
          </div>
        ))}
      </div>

How to Automate Unit Testing with GitHub Actions

GitHub Actions is a powerful automation tool provided by GitHub. It allows you to define and execute workflows directly within your GitHub repository.

With GitHub Actions, you can automate various tasks and processes, such as building, testing, and deploying your code, as well as performing code analysis, generating documentation, and more.

GitHub Actions workflows are defined using YAML syntax. A workflow consists of one or more jobs, and each job consists of a series of steps to be executed. Steps can include actions (reusable units of code), shell commands, or scripts.

name: Shopping Cart CI

on:
  push:
    branches: [ "main" ]
  pull_request:
    branches: [ "main" ]

jobs:
  build:

    runs-on: ubuntu-latest

    strategy:
      matrix:
        node-version: [19.x]
        # See supported Node.js release schedule at https://nodejs.org/en/about/releases/

    steps:
      - uses: actions/checkout@v3
      - uses: actions/setup-node@v3
        with:
          node-version: '19'
          cache: 'yarn'
      - run: yarn install
      - run: yarn test

In our case, I utilized GitHub Actions to create a workflow that automatically runs the unit test suite whenever a new change is committed to the main branch. This ensures that no production build is triggered in the event of a test failure.

Implementing this workflow is straightforward and highly beneficial. It provides the reassurance that any issues inadvertently introduced into the main branch will be caught before reaching production. This level of reliability and peace of mind is easily achieved by leveraging the capabilities of GitHub Actions.

Shopping Cart app - GitHub Actions

Conclusion

The topic covered in this tutorial may not be novel or unfamiliar, but its scope of application is remarkably extensive.

Nearly every online application that involves trading or purchasing goods incorporates a shopping cart or basket functionality in some form. Because of this, if you're a software engineer working in this domain, you'll need to possess a solid understanding of how to implement this functionality and its underlying principles.

By acquiring a high-level knowledge of these concepts and understanding how things operate in general, we can effectively contribute to the development of robust and efficient e-commerce systems.

📘 You now understand the purpose and functionality of a shopping cart in an online application.

📘 You have learned how to implement a product list page by fetching data from a third-party REST API.

📘 You have learned how to create a cart component that retrieves and renders data from the browser's local storage.

📘 You have discovered the benefits of GitHub Actions and how they can provide confidence when promoting your code to production.

📘 And most importantly, you have embraced the mindset of continuous learning, understanding that there is always more to explore and discover in the vast world of software engineering.

By combining these newfound skills with a commitment to ongoing learning, you are well-equipped to create efficient and robust e-commerce systems while continuously improving your abilities in this dynamic field. Remember, the journey of knowledge acquisition never ends! 🎓

I hope you found this tutorial enjoyable and engaging. Most importantly, I hope you were able to actively follow along and even experiment with the code. Feel free to make your own modifications and observe the resulting changes in the end product. Hands-on exploration and experimentation are fantastic ways to solidify your understanding and expand your skills.

Remember, the best way to enhance your skills and understanding is through practice and experimentation. So feel free to dive into the code, make it your own, and observe the exciting results you can achieve. Happy coding and exploring!

Thanks for reading! 🙏

The idea behind it is simple, but powerful. We have senders called publishers. Their sole role is to send or publish messages. They don’t care about who is going to receive them or if someone will receive them at all. They just shoot and forget the messages. And they do that via channels.

Think of them as, for example, TV channels. We have Sports channels, Weather Forecasting channels, Cooking channels, and so on. Every publisher sends its messages to a certain channel, and whoever is subscribed for this channel will be able to receive these messages.

Here is where the subscribers come in play. They can subscribe to one or more channels and start receiving the messages broadcasted in there.

As we already mentioned, the messages are to be sent and forgotten. This means that if a subscriber subscribes for a certain channel, all the messages that were sent previously in that channel are not going to be available to this subscriber.

Due to the nature of this kind of architecture, we can easily achieve low coupling between the different components and provide a solid foundation for building robust and easy-to-maintain applications.

For example, imagine a situation where we need to replace or improve the publishing part of our system – say add more publishers, more channels or so on. Since the two parts are isolated, meaning publishers don’t care about subscribers and vice versa, we could easily do that without worrying whether we are breaking some other part of the system. We just add the new publishers. Then later, when a subscriber comes to the relevant channels, it just starts using them.

What is Redis?

The initial idea behind Redis was to serve as an in-memory cache solution, as an alternative to its ancestor Memcached.

But nowadays it's a many-in-one solution, providing an in-memory data structure store, key-value database, message brokering, and so on. This makes it perfect candidate when building an application that needs a really fast caching solution as well as some of the other features mentioned before. Especially if the performance of the app is crucial for its regular usage.

Redis performance comparison (source: google)

One of the biggest advantages when using Redis is the huge community and technical resources you can find online. A lot of these resources are free, and there are online platforms that have free tier offerings.

Redis includes in its arsenal a cloud solution as well. If you want to try it yourself, you may go here and register a free account or use their initial coupon offering.

Redis Enterprise Cloud Sign Up / Sign In page

Pub/Sub in Redis

What is pub/sub?

Publish/Subscribe channels in Redis is one of the features I haven’t mentioned above but it’s included in the last versions of Redis. This is their implementation of the pub/sub messaging pattern, where we have publishers and subscribers that exchange messages via channels.

We'll go briefly through it below and then see it in practice in a small demo app I have prepared for you.

How does Redis pub/sub work?

We have publishers (the producers of messages), channels (that the messages are going through), and subscribers (the receivers of the messages). Who receives what depends solely on who is subscribed to which channel.

Let's see how this works in an example:

If we have created three publishers which will be publishing messages to three different channels. Let’s call them channels 1, 2 and 3. We also have three subscribers, let’s call them subscribers A, B and C.

Now, let’s imagine subscriber A is listening for messages on all three channels, that is, it's subscribed to them. And subscribers B and C are subscribed to channels 2 and 3. This means that when either of the three publishers sends a message, subscriber A will receive it. And subscribers B and C will be receiving messages sent only by publishers 2 and 3, because they are listening only for messages on these channels (2 and 3).

Notice that we have two entities using a channel – one is sending, the other is receiving – but they are totally independent. And the messages being sent are not persisted. Once they are sent by the publisher they are forgotten. The only entities that are subscribed at the moment of sending will get them.

How to use pub/sub in Redis

There are a plethora of client libraries that you can use with Redis. There is a dedicated page where everybody can go and pick one, depending on the specific project needs or just on your preferred programming language.

People at Redis also marked some of these repositories as recommended which makes the choice easier, if you are new to all this.

For our demo below, I used ioredis, a full-featured Redis client for Node.js. I chose this because the demo app UI is built with React and Node.js and my server code goes pretty well with it.

Redis Pub/Sub Demo

Redis Pub/Sub Visualizer app

Show time!

The idea behind the demo application is to show visually how the pattern works.

What you will see when you open it for first the time is three buttons for publishing simple messages (news) in the three imaginary TV channels: Weather, Sports and Music.

The cards below the publish buttons are the subscribers. Once you move your mouse cursor over any of them, it will flip to its back side and you will see three buttons. You may use each of these buttons to subscribe to the relevant channel.

Once a subscriber is signed over a channel and you click on the icon or the publish button for this channel, you will see a sample news appearing on the front side of the card.

Play with different publishers/subscribers combinations and see the result.

I hope this will give you a better understanding of what I explained in the example above.

How to run the demo app locally

In order to install and run the demo application locally, follow the steps below (all commands are considered to be run from the root project directory):

Run frontend:

cd client yarn && yarn dev

Run backend:

cd server && yarn yarn start

And finally, use your local installation of Docker (if don’t have one, you may get it from here) to run this:

docker run -p 6379:6379 redislabs/redismod:preview

That’s probably the easiest way to have a running copy of Redis locally. The other option would be to use Redis Cloud directly and deploy the application online. This is an option I am still investigating and if I manage to do it, I will deploy the whole app and will let you know.

Closing

This article introduced you to the pub/sub messaging pattern subject. It's important to remember that whenever we want to build a highly performant application with a low coupled architecture and real-time like messaging features, consider using the Publish/Subscribe pattern and Redis in particular.

In fact a lot of the real life applications that use Redis are dashboard-based. This means that usually there is a nice dashboard screen, showing different data, often being updated in real time.

Imagine, for example, a system showing traffic in a specific area. This kind of software is a perfect candidate for leveraging the advantages of pub/sub. And in many cases this is achieved by using Redis.

In any case, as developers and engineers, we should always be guided by the specific needs of the project we are working on. Whenever we decide to introduce a new pattern or technology, we should do it carefully and back it up with serious research.

You will also learn how to leverage React hooks, built as an abstraction of the native JavaScript timeouts and time intervals. For styling the application we will use CSS Modules with SASS.

Here's what we'll be building:

Football live scoreboard - current games screen

💡If you want to skip the reading, 💁 here is the GitHub repository, and here you can see the live demo 📺.

What is a Scoreboard?

Football scoreboard

A live scoreboard is a digital sport scoreboard that automatically displays up-to-the-minute sports scores and data from a certain game – for example a football game. This way it’s much easier for the users to follow the game, make predictions or bets, and so on.

Our application is going to reflect such a board, but in the browser.

The Project

Our application has just a few dependencies and several components. It also uses JavaScript timeouts and intervals to simulate real-time score updates.

⚙️ Application features

Before going into the technical part of the tutorial, let's talk about the application features we will implement.

It’s always better (if possible, of course) to have clear project requirements laid out before writing a single line of code. But folks with some experience in the software engineering and development world know that the reality is often completely different.

The beauty of such small projects that you build for educational purposes is exactly this – you have the freedom to define your own requirements and to meet them in a feasible manner.

So here it the summary of the requirements/features:

Live Football World Cup Scoreboard that shows matches and scores.

The board supports the following operations:

1. Start a game. When a game starts, it should capture the home team and away team (with an initial score of 0 – 0).

2. Finish game. It will remove a match from the scoreboard.

3. Update score. Receiving the pair's score. When the home team or away team scores, it updates the game score.

4. Get a summary of games by total score. Those games with the same total score will be returned ordered by the most recently added to our system.

✍️ As an example, if this is the current data in the system:

a. Mexico - Canada: 0 - 5
b. Spain - Brazil: 10 – 2
c. Germany - France: 2 – 2
d. Uruguay - Italy: 6 – 6
e. Argentina - Australia: 3 - 1

The summary would give us the following information:

1. Uruguay 6 - Italy 6
2. Spain 10 - Brazil 2
3. Mexico 0 - Canada 5
4. Argentina 3 - Australia 1
5. Germany 2 - France 2

🏗️ Project Structure

Project Structure

Let me go through each of the files and give a short explanation of what they are and why we need them:

• package.json – the configuration file of every Node.js app, created with npm or yarn, or any other package manager that uses the same approach.

• README.md – not much to say here – it's a simple text file that uses Markdown and contains the description of the project, plus any other information you want to put there.

• vite.config.js – the main configuration file that Vite uses, which you get when you do the installation from the previous step. The content of this file by default looks like this:

import { defineConfig } from 'vite'
import react from '@vitejs/plugin-react'

// <https://vitejs.dev/config/>
export default defineConfig({
  plugins: [react()],
})

But in my case, I had to add the test configurations so that we could run the tests. You will read more about this later in the article.

• setupTests.js – this one is used for configuring the unit tests. We put here any of the things we would like to have available in the tests we write.

For example, in order to be able to use unique keys when rendering multiple elements (because we React needs it), I am using the randomUUID()method of the Crypto interface to generate a v4 UUID using a cryptographically secure random number generator. And to make it available in my tests, I need to add it here, like this:

import { expect, afterEach } from 'vitest';
import { cleanup } from '@testing-library/react';
import matchers from '@testing-library/jest-dom/matchers';
import {randomUUID} from 'node:crypto';

// extends Vitest's expect method with methods from react-testing-library
expect.extend(matchers);

// runs a cleanup after each test case (e.g. clearing jsdom)
afterEach(() => {
    cleanup();
});

window.crypto.randomUUID = randomUUID;

• yarn.lock – this is generated automatically when run yarn installation and lock the version of the packages being used.

• .gitignore – comes out of the box from Vite installation. Here you define which files and folders you want Git to ignore, that is not get committed to your repo.

• index.html – this the app’s entry point. It's a simple HTML document that has a few meta tags, and includes the logo and the main script file.

• /src – contains a few different things we need to discuss:

1. First, it has the main.jsx file, which is where React and ReactDOM come in play. We also load here the default styles file I mentioned earlier.

2. It also has index.css which I have explained already.

3. Then we have App.jsx which is where our actual application code begins. This file can be considered as the main component in our application, as it contains all ‘inner’ parts of our app.

4. Then we have app.module.scss which contains styles for App component, using the CSS module convention to name the files with ‘module’ prefix and ‘scss’ extension.

5. Finally, we have App.test.jsx which contains a simple test for App component, using Vitest for testing framework.

🛠️ Components

Let me walk you quickly through each of the components in the application. They are located in the components folder.

/components folder contents:

• Footer – self-explanatory, contains the footer part of the app.

• GameStatus – used to show if a game has started, that is if it's being played.

• Header – self-explanatory, contains the header part of the app.

• MessageBoard – a small component used to display text messages that state when the games are starting or if we are looking at the “Summary” screen or the “Current Games”.

• Result – another small component showing game scores.

• Scoreboard – kind a parent component, serving as container that holds all the small ones in place.

• ScoreboardGrid – this is the most important component in the app, as it contains all the logic related to the timers. It holds all child components and it’s responsible for passing the necessary data to them via their props.

• TeamView – another small component serving as a representation of a team, which shows team’s flag and name.

⏱️ Timeouts

The timeouts – or more precisely the time intervals – in the application are implemented with the help of several React hooks. All of them are located in the hooks folder. I borrowed them from a very knowledgable and kinda famous guy named Josh W Comeau. I'll post the links in the end of the article.

So basically we use three hooks, one per type of time interval or timeout we need.

1. useInterval – this is based on the built-in JavaScript setInterval function and it's used for initial countdown, before the games start

2. useRandomInterval – this is an enhanced version of the previous one, and it’s used for randomly updating the score of the games, as well as randomly starting and stopping them

3. useTimeout – this is based on the built-in JavasScript setTimeout function and it’s used for deciding when to stop the playing time of the games and start finalizing them

🧾 How to Build the Project

By now you should have a decent understanding of what our application is and how its various parts are put together.

Let me now guide you, step-by-step, from the very beginning, and show you how I built it. I will add images where necessary, so that it’s easier for all of you to follow along.

📦 Dependencies

The dependencies we have are very few. Except Vite and Vitest, I have installed additionally only SASS, and the React Testing Library. Here is how my package.json file looks:

{
  "name": "scoreboard",
  "private": true,
  "version": "1.0.0",
  "type": "module",
  "author": "Mihail Gaberov",
  "scripts": {
    "dev": "vite",
    "test": "vitest",
    "build": "vite build",
    "preview": "vite preview"
  },
  "dependencies": {
    "react": "^18.2.0",
    "react-dom": "^18.2.0"
  },
  "devDependencies": {
    "@testing-library/jest-dom": "^5.16.5",
    "@testing-library/react": "^14.0.0",
    "@types/react": "^18.0.28",
    "@types/react-dom": "^18.0.11",
    "@vitejs/plugin-react": "^3.1.0",
    "jsdom": "^21.1.1",
    "sass": "^1.59.3",
    "vite": "^4.2.0",
    "vitest": "^0.29.7"
  }
}

🧑🏻‍💻 Installation

In this step I assume you are starting from scratch. We are going to use Vite for scaffolding the project. In order to do that you need to have Node.js installed on your system – at least version 14..18. I suggest that you update it to the latest stable version. And as a package manager you may go with either npm or yarn. In my case I use yarn.

In your terminal app run the following:

yarn create vite

And then follow the prompt.

Some of you may ask “Why Vite?” Here is a little praise of Vite that should answer that question.

After doing the installation we have the bare skeleton of a React app that we can start building on. Here is how it looks:

Default Vite Project

💡 When starting such projects, I usually wipe off what’s there by default. Meaning that I delete the files I don’t plan to use, clean up App.jsx, and update the index.html file.

Another thing you may have noticed already is that the only pure CSS file I kept is index.css. This is one of the files that comes by default from Vite’s installation. I kept it as it is because it contains some basic styling that I didn’t want to move anywhere else.

After the initial cleaning and adding the files for styling and testing App.jsx, the project looks like this:

First steps of the project in App.jsx

In the screenshot above, you can see what the App.jsx file looks like after my changes. I placed comments as placeholders for where the components I need to create will be.

We are now ready to start building the components in question. Usually there are several different approaches you can take when deciding what to begin with. In this case, we'll start from top to bottom, create the header component, then jump to the scoreboard component, and in the end we'll build the footer component.

You could also decide to first build the essential part of the app, that is the scoreboard and in the end to add the “hat” and the “shoes”.

But in any case, what I recommend is to create empty components for each of the placeholders we have placed, based on the idea we have in mind about what our application will be.

Usually I use something called “Live Templates” in my IDE (in case you are using different IDE, I am sure there is an alternative for it) that can generate different types of a boilerplate code.

In our case I use it for generating empty functional React components. This comes in very handy at this stage of the development process, because we can quickly create our project's components, leaving them empty. Then later we can start filling them up with content.

Live Templates in Webstorm

Generating boilerplate code for the components we will create

And this is what the result of the above looks like:

Generated boilerplate code for a functional component in React

🧩 How to Build the Header

In order to make the application to look more like a real-life one, I decided to add a small logo in the left part of the header, and a title next to it. Let’s see how it will look like in the browser and then how to implement it with code:

Application Header

First, I did a quick Google search and chose an appropriate image (the cup). I made sure to pick a SVG file for several reasons.

First and most important is the performance and the adjustability that come from it. And second, in the Vite default settings there is already an SVG logo added. So the only thing you need to do is to replace the existing one with yours. And then add some styling if necessary.

SVG logo

Let’s now look at the code of our brand new header component:

import './header.module.scss'
const Header = () => {
    return (
        <header>
            <img src='./logo.svg' alt='FIFA World Cup Scoreboard'/>
            <h2>FIFA World Cup Scoreboard</h2>
        </header>
    );
};

export default Header

If you keep the logo file in the public folder, you don’t need to worry about the path to the image. It’s taken care by Vite and you refer to it as it’s shown in the code above. The import statement in the beginning applies all styles to the header that make it looks like the picture.

header {
  display: flex;
  background-color: #fdbe11;
  justify-content: flex-start;
  align-items: center;

  img {
    width: 3rem;
    height: auto;
    margin: 1rem;
  }
}

After adding some tests, the content of the component folder looks like this:

Header component directory

I mentioned in the beginning of the article that we will use Vitest and React Testing Library to write the units/components tests for this application. Here is how the tests for the header look:

import { render, screen } from '@testing-library/react'
import { beforeEach, describe, expect, it } from 'vitest'
import Header from "./index"

describe('Header', () => {
    beforeEach(() => {
        render(<Header />)
    })
    it('renders correctly the app title', async () => {
        expect(screen.getByText(/FIFA World Cup Scoreboard/i)).toBeVisible()
    })

    it('renders correctly the app logo', async () => {
        const logo = screen.getByAltText('FIFA World Cup Scoreboard');
        expect(logo).toHaveAttribute('src', './logo.svg')
    })
})

As you probably can guess just by reading the tests, what we're doing here is checking for the app title and then the logo we saw on the left.

Congratulations 🎉 You just finished the implementation of the first building block of your application. Let’s continue now with the main area. This is where the essential functionality of the scoreboard will be.

🧩 How to Build the Scoreboard

The scoreboard supports two screens: one showing the scores of the games that are currently being played, and another one showing a summary of the end results.

Current Games screen

Summary screen

When I see this kind of layout design, I usually start thinking about a grid. Because, what’s a grid if not just rows and columns?

The modern CSS language has support for grid systems with just few lines of code, as you will see a bit later in this section. For example, to achieve this result I used the following styles:

.grid {
  list-style-type: none;
  margin: 1rem;
  display: grid;
  gap: 1rem;
  grid-template-columns: repeat(auto-fit, minmax(300px, 1fr));
}

Whenever I am about to implement a UI like this in a component based library such as React, I tend to mentally split it to separated blocks. These will turn into components.

Let me show you visually what I mean by this:

Thinking components - visual representation

I hope you can figure out what I am showing you on the picture above.

This is how I mentally split the design layout we have in place into representational components.

After defining the constituent parts of our application, it’s time to move forward and implement them in code.

First we need the ScoreboardsGrid component that will hold all the smaller ones and will contain the logic for managing different events based on time.

ScoreboardsGrid component directory

As you may have noticed, in addition to the usual files, here we have one more – ScoresReducer.js. This is where our reducer logic lives. It’s responsible for manipulating the application state, depending on what actions are being triggered. In other words, this is where we actually update the score when a team scores, and also where we start and finish games.

In the return statement of the component we make use of the rest of the components we defined earlier.

...
...
...
return (
        <>
            {timeElapsed === 0 ?
                <>
                    <MessageBoard message={getScoreBoardStateMessage()}/>
                    <div className={classes.grid}>
                        {gamesToRender?.map(pairScore => (
                            <Scoreboard
                                key={crypto.randomUUID()}
                                pairScore={pairScore}
                                status={getGameStatus(pairScore.startedGame)}/>))}
                    </div>
                </> :
                <MessageBoard message={`Games are about to start in ${timeElapsed} seconds.`}/>
            }
        </>
    );

The rest of the code consists of a few helper methods, dispatch methods, and the logic for starting and stopping the timers.

From here, things become even easier. We just are going to use our smaller components for displaying different things in our scoreboard app.

For example, the MessageBoard component is just a container that shows in a stylistic way a bit of a string, passed via its props. Here is the implementation:

import classes from "./message-board.module.scss";

const Index = ({ message }) => {
    return (
        <div className={classes.message}>
            {message}
        </div>
    );
};

export default Index;

Same goes for the [GameStatus](https://github.com/mihailgaberov/scoreboard/tree/main/src/components/GameStatus) and [Result](https://github.com/mihailgaberov/scoreboard/tree/main/src/components/Result) components. The difference between the later ones is that Result gets two arguments – the name of each team in a game – and displays them with a dash (’-’) in the middle. GameStatus is just showing whatever we pass through via its props, which happens to be a string signifying that a game is playing at the moment.

The only component that is a bit different is TeamView, because it contains both an image and text, representing the teams. The code itself is far from complicated. See for yourself:

import classes from "./team-view.module.scss";

const TeamView = ({teamData}) => {
    return (
        <div className={classes.team}>
            <img src={`https://flagcdn.com/${teamData.countryCode}.svg`} width="50" alt={`${teamData.name}`}/>
            <span>{teamData.name}</span>
        </div>
    );
};

export default TeamView;

Here I used a regular HTML img tag, setting the width using inline styling. The rest is pretty straightforward.

With that, our coding job is more or less done. As you have probably seen, all the component have tests. These, in most cases, are just simple checks to see whether the component is being rendered correctly.

Maybe the most interesting tests to talk about are the ones we added for the ScoreboardGrid component.

This is so because we are using React Testing Library asynchronicity support to test the state of the component in different moments of the time. In this way we are able to test the initial timer ticking, before the games start. And after it expires, we can use it to check that our Current Games screen is displayed correctly. I'm pasting the code here as well, for easier reading.

import { render, screen } from '@testing-library/react'
import { describe, expect, it } from 'vitest'
import ScoreboardsGrid from "./index"

describe('ScoreboardsGrid', () => {
    it('renders correctly all available scoreboards', async () => {
        render(<ScoreboardsGrid />)

        expect(await screen.findByText(/Games are about to start in 3 seconds./i)).toBeVisible()
        expect(await screen.findByText(/Games are about to start in 2 seconds./i)).toBeVisible()
        expect(await screen.findByText(/Games are about to start in 1 seconds./i)).toBeVisible()
        expect(await screen.findByText(/Argentina/i)).toBeVisible()
        expect(await screen.findByText(/Australia/i)).toBeVisible()
        expect(await screen.findByText(/Spain/i)).toBeVisible()
        expect(await screen.findByText(/Brazil/i)).toBeVisible()
    })
})

After you've completed the implementation of the entire application and have a cup of ☕ or a glass of 🚰, it’s time to think about possible improvements.

For example, if we have more time to work on this project, what would we add or change, to make it an even better scoreboard app?

🧩 How to Build the Footer

To give the application a more complete look, I’ve decided to add a footer component as well. This is how it looks:

Footer Component

The implementation of it is pretty simple, too. We have two links to social platforms and a bit of copyright text. Here is how I coded it:

import classes from "./footer.module.scss";
import packageJson from '../../../package.json';

const Footer = () => {
  const currentYear = new Date().getFullYear();

  return (
      <footer className={classes.footer} data-cy="footer">
        <ul>
          <li className={classes.footerLinks}>
            <a
                href="<https://twitter.com/mihailgaberov>"
                target="_blank"
                rel="noopener noreferrer"
                data-cy="twitterLink"
            >
              twitter
            </a>{" "}
            &bull;{" "}
            <a
                href="<https://github.com/mihailgaberov>"
                target="_blank"
                rel="noopener noreferrer"
                data-cy="githubLink"
            >
              github
            </a>
          </li>
          <li className={classes.footerCopyrights}>
            © {packageJson.author} {currentYear}. All rights reserved.
          </li>
          <li>
            <div className={classes.version}>v.{packageJson.version}</div>
          </li>
        </ul>
      </footer>
  );
};
export default Footer;

Again, in the component folder you will find the other files that are necessary for applying the styles and the tests for that component.

The code looks a bit cluttered because I used an unordered list and added the links and the text as a separated list elements. Then I used the tests to verify that the elements I want are rendered correctly.

Here is the essential part of the code that is doing this:

it('renders correctly social links', async () => {
    expect(screen.getByText(/twitter/i)).toBeVisible()
    expect(screen.getByText(/github/i)).toBeVisible()
  });

  it('has social links working correctly', async () => {
    expect(screen.getByText('twitter').closest('a')).toHaveAttribute('href', '<https://twitter.com/mihailgaberov>');
    expect(screen.getByText('github').closest('a')).toHaveAttribute('href', '<https://github.com/mihailgaberov>');
  });

  it("should contain copyright info", () => {
    expect(screen.getByText(/© Mihail Gaberov 2023. All rights reserved./i)).toBeVisible()
  });

  it("should contain version number", () => {
    expect(screen.getByText(/v.1.0.0/i)).toBeVisible()
  });

🚀 Possible Improvements

• Add a clock under the game status, say counting down the seconds, to make it look more like a real-time app

• Add some animation when updating the scores to make it easier for the user to spot the change

• Add some interactivity in general:

  • Clicking on each game leads to a details pane with the match details

  • Option for selecting a favourite team

  • Add another page/tab where users can read a history summary of the past games

Conclusion

That was a fun challenge. Especially if you are a football fan, right? ⚽

We learned about several interesting topics.

First we learned what a scoreboard is, and the ‘why’ and the ‘how’ behind it.

Then we learned about Vite and Vitest, which I think are currently the best tools to use when making a React app – especially if you don’t want to start from scratch and deal with Webpack manually.

Then we saw how to leverage JavaScript timeouts with React hooks, and thus create some kind of time-based interactivity.

And last, but not least, we had fun, didn't we? 🕺🏻

Thanks for reading 🙏🏻

References:

• Resources from Josh W. Comeau: for use-interval and use-timeout and use-random-interval

• An article from Kent C. Dodds about common mistakes devs make with the React Testing Library

They used their own numeric system, which was a bit of a mouthful, especially when it came to writing. It looks like this: I, II, III, IV, V, VI and so on.

Maybe that’s one of the reasons that people adopted and started using the Arabic numeric system. It's the one we all know and use on a daily basis. Yes, yes, the same – 1,2,3…and so on.

What Are We Building?

In this tutorial, we will see how to build a small app that gives the user an input for entering Arabic numbers and displays their Roman numeral equivalent with a nice, sleek animation.

We will use SolidJS for building the UI and good old JavaScript for implementing the algorithm for the actual conversion. More on this later in the article.

We also will take advantage of CSS Modules and SASS to help make our application a bit more eye pleasing.

GitHub Repo and Demo Project

💡If you want to skip the reading, here 💁 is the GitHub repository, and here you can see the live demo 📺.

What is SolidJS?

SolidJS is a front-end library for creating reactive user interfaces. It is still relatively new. It looks a lot like React, but they say it’s simpler and faster.

It got my attention recently, so I’ve decided to take a deeper look and educate myself. And, of course, share my experience with you here.

The Project

Our application is really simple. It has just a few dependencies and contains only several components. Let me walk you briefly through them.

Dependencies

{
  "devDependencies": {
    "vite": "^4.1.1",
    "vite-plugin-solid": "^2.5.0"
  },
  "dependencies": {
    "@motionone/solid": "^10.15.5",
    "@solid-primitives/keyed": "^1.1.8",
    "sass": "^1.58.3",
    "solid-js": "^1.6.10"
  }
}

Except the obvious dependency – solid-js – I’ve only installed the sass, @motionone/solid and @solid-primitives/keyed libraries. We will use these for the styling and the animations. Vite-related packages come with the SolidJS app installation, which means that when you run this:

npx degit solidjs/templates/js my-app

It will install all you need to initially run your new SolidJS app.

Project Structure

Project Structure

Maybe folks with React experience will see immediately how much this looks like a regular React application. We have the same file/folders organization. And yes, we can use JSX with Solid as well.

After seeing the ‘new’ Solid application structure, let's dive into the basic components that come from the library and that we need in order to build the UI.

Components

Components in Solid are, surprise surprise 😲, regular JavaScript functions. A Solid app is composed of these functions. And, same way as in React, they support JSX. This means we can write functions that produce DOM elements.

For example, here is how our Logo component looks:

import styles from './Logo.module.scss';
import gameLogo from '../../../assets/logo.png';

export function Logo() {
  return (
      <div className={styles.logo}>
          <img src={gameLogo} alt="logo" />
      </div>
  );
}

Yes, you guessed right. This will produce HTML code like this:

Logo component (HTML)

Maybe some of you are already asking “C’mon Mihail, are you kidding? What’s the difference between Solid and React?” and I agree. So far everything looks pretty much the same. Let’s talk about Signals now.

SolidJS Signals

SolidJS Signal

Signals are the foundation of reactivity in Solid. They hold values that change over time and they update everything else that uses these values. Which means that if you change a signal’s value, this change will be propagated everywhere else in your app where it’s being used.

This is something that’s missing in the React world. At least in name.

When a signal is created, it gives you back two functions, a getter and setter. You use the first one to get the current value the signal contains. And the setter function is used to change that value. The syntax is the following:

const [count, setCount] = createSignal(0)

The value you pass as an argument to createSignal is the initial value that will be held by the signal, 0 in this case. This means that if you call count()without calling setCount with a different value before that, the result you will get is that zero.

Now that you've seen how to use it and what its purpose is, you might be thinking about its equivalent in React, useState. In my case, that was the initial association that popped into my mind. The so-called signals are means to manage the state in a Solid application. As it gives you an easy way for accessing and changing it.

The Algorithm

There are multiple implementations of this algorithm. And in many different programming languages. Only a Google search can say how many 🤓.

We'll implement it in JavaScript. I keep the file containing the algorithm separate, in a directory called lib. This approach keeps our hands untied when it comes to replacing the UI with, say, one done with a different UI library. Or maybe we use it in completely different context. That is, the frontend and the backend of our application are totally decoupled.

Let’s first walk through the algorithm itself and then we can discuss some improvements we can do.

Algorithm Steps

First things first, let me layout the code here so that it’s easier for you to follow:

export const convertArabicToRoman = function (num) {
    const rules = {
        "M": 1000,
        "CM": 900,
        "D": 500,
        "CD": 400,
        "C": 100,
        "XC": 90,
        "L": 50,
        "XL": 40,
        "XXX": 30,
        "XX": 20,
        "X": 10,
        "IX": 9,
        "V": 5,
        "IV": 4,
        "I": 1
    }

    let res = "";
    const romans = Object.keys(rules);

    for (let i = 0; i < romans.length; ++i) {
        const val = rules[romans[i]];

        while (num >= val) {
            num -= val;
            res += romans[i];
        }
    }
    return res;
};

Next, let’s take a look at the rules that define how the Roman numerals are created.

These rules allow you to write down any number:

• If a smaller numeral comes after a larger numeral, add the smaller number to the larger number.

• If a smaller numeral comes before a larger numeral, subtract the smaller number from the larger number.

• Do not use the same symbol more than three times in a row.

• Modern usage employs seven symbols, each with a fixed integer value:

Keeping in mind these rules, here are few examples:

• 399 in Roman Numerals is CCCXCIX

• 151 in Roman Numerals is CLI

• 185 in Roman Numerals is CLXXXV

• 3070 in Roman Numerals is MMMLXX

• 570 in Roman Numerals is DLXX

• 7 in Roman Numerals is VII

• 290 in Roman Numerals is CCXC

• 1880 in Roman Numerals is MDCCCLXXX

• 47 in Roman Numerals is XLVII

Let’s go through our solution now step by step: 🎢.

1. Create a data structure that will hold the representations of the known numbers from the rules. In our case it is a simple JavaScript object.

2. Add a few more known numbers that will help us in the later calculations, that is 4, 9, 20, 30, 40, 90, 400 and 900.

3. Create an empty string that will hold the result.

4. Then use the Object.keys() method to get all Roman numerals from our structure.

5. Iterate through them via a for-loop.

6. For each Roman numeral letter, get its Arabic counterpart and check if it’s less than or equal to the number we are converting.

7. If it is, first subtract it from the number we are converting and then store the current Roman representation in the res string by concatenating it with what’s already there.

8. After both loops finish, return the end result in our string variable.

After defining the algorithm steps, let’s run a specific example through them and it will get clearer.

Example

OK, let’s take a random number and pass it to our algorithm. Say number 1293. We will skip the preparation steps and go straight to where the real magic happens. Which means we start with getting the Romans numerals which are the keys of our key-value data structure:

    const romans = Object.keys(rules); // ["M", "CM", "D", "CD", "C", "XC", "L", "XL", "XXX", "XX", "X", "IX", "V", "IV", "I"]

This results in an array holding the Roman numeral representations we have there. That allows us to iterate over them via the **for-**loop and access each of them on every cycle.

Then, having access to each Roman numeral from this array, we then get its value:

const val = rules[romans[i]]; // First cycle this will give 1000, 900 in the second, and so on

So we have number 1293 as our input, which we named num. In the inner while- loop we compare the input with the currently selected value (from the rules data structure) and if it’s bigger or equal, we subtract it from our input value. Then we concatenate the Roman numeral letter to our string result.

In our example that would mean the following:

Is 1293 >= 1000 > yes => num = 1293 - 1000 = 293 and res = 'M'

Then we keep iterating with the result value from the previous iteration.

Is 293 >= 1000 => no => 293 >= 900 => no => 293 >= 500 => no
=> 293 >= 400 => no => 293 >= 100 => yes => 293 - 100 = 193
and res = 'MC'

Is 193 >= 100 => yes => 193 - 100 = 93 and res = 'MCC'

Is 93 >= 100 => no => 93 >= 90 => yes => 93 - 90 = 3 and res = 'MCCXC'

Is 3 >= 90 => no => 3 >= 50 => no => 3 >= 40 => no => 3 >= 30 => no => 3 >= 20
=> no => 3 >= 10 => no => 3 >= 9 => no => 3 >= 5 => no => 3 >= 4 => no => 3 >= 1
=> yes => 3 - 1 = 2 and res = 'MCCXCI'

Is 2 >= 1 => yes => 2 - 1 = 1 and res = 'MCCXCII'

and lastly

Is 1 >= 1 => yes => 1 - 1 = 0 and res = 'MCCXCIII' is the final result! 🎉🎉🎉

How to Improve the Process

One thing is important to mention here. If we use the algorithm directly as it is, it could consume whatever number we pass to it. But, keeping in mind the rules mentioned above, the result string could get really long. This could break the UI or at the very least it would make it ugly and unusable for writing.

This is why some implementations talk about adding more letters to the rules. As shown on the table below, we could have letters signifying bigger numbers. Adding this to the algorithm would significantly reduce the length of the result string when a bigger number is added.

For example, with our current implementation, if we enter 1,000,000, the result would be 1000 times the letter M. You can imagine it, it’s a long string of Ms, such as MMMMMMMM_…_ But, if we introduce additional letters for bigger numbers, this will become just the letter M with a line above, as shown in the table below.

Possible improvement using more letters. Source: by https://www.calculateme.com/roman-numerals/to-roman

Conclusion

Yet another learning-by-sharing session ends here 🎉.

We achieved two main goals in this tutorial. First we touched on a relatively new player on the front-end libraries market, SolidJS. We got familiar with its basic elements. We figured out how to use them in order to quickly build a decent user interface. And we’ve manage to use this UI to show the workings of our algorithm.

And second, we tackled the algorithm itself. We saw how can we implement it in JavaScript. We also know understand the limitations of this approach, and what would be possible improvements. For example, you can add more letters for signifying the bigger numbers. This could easily remove our top limit. And instead of 4999 we could go unlimited.

Last thing I would like to say here is, as always, thank you for reading 🙏🏻, I hope it was fun and interesting for you!

References:

• SolidJS docs

The Parking Lot is challenge where you are asked to write a class that manages an imaginary parking lot.

In this tutorial we will do that in JavaScript. And to make it a bit more interesting, we will create a small React app that will visualize the workings of our class.

Let's begin. 🎉

Challenge Requirements

For this challenge, you have to implement a class in JavaScript. That class should consist of variables and methods that simulate how a parking lot works. Here are the details:

• We should be able to create the parking lot with a given size (number of parking spots)

• We don’t differentiate between different vehicles – we consider them all the same

• Our class provides a method for parking new cars in the parking lot

• Our class provides a method for removing already parked cars, and

• Our class provides a method for getting the size of the parking lot (total count of slots)

Parking Lot Challenge Solution

First, let’s take a look at the class logic itself.

It’s pretty straightforward, so there probably won’t be any surprises for most of you – especially if you already have some programming experience in OOP and class-based languages.

class ParkingLot

I will give you the code first and then I'll follow up with a short explanation on the implementation.

class ParkingLot {
  slots = [];

  constructor(parkingSize) {
    this.slots = new Array(parkingSize).fill(null);
  }

  park(carId) {
    console.log(`Parking car: ${carId}`);
    if (this.slots.every((slot) => slot !== null)) {
      return false;
    }

    for (let i = 0; i <= this.slots.length; i++) {
      const slot = this.slots[i];

      if (slot === null) {
        this.slots[i] = carId;
        return true;
      }
    }
  }

  remove(carId) {
    console.log(`Leaving car: ${carId}`);
    if (this.slots.every((slot) => slot !== carId)) {
      return false;
    }

    for (let i = 0; i <= this.slots.length; i++) {
      const slot = this.slots[i];

      if (slot === carId) {
        this.slots[i] = null;
        return true;
      }
    }
  }

  getSlots() {
    console.log(`Parking slots: ${this.slots}`);
    return this.slots;
  }

  getSize() {
    console.log(`Parking size is: ${this.slots.length}`);
    return this.slots.length;
  }

  getAvailable() {
    const availableSlots = this.slots.filter((s) => s === null).length;
    console.log(`Available parking slots: ${availableSlots}`);
    return availableSlots;
  }

  isFull() {
    return this.getAvailable() === 0;
  }
}

export default ParkingLot;

Starting from the beginning – our class has one property, slots, which is going to be an array that stores info about the parking slots (whether they're free or occupied).

Then we have a constructor method that gets executed every time you create an instance of this class. Here is where we use an input number parameter, called parkingSize, to create an empty array with length equal to that number.

Technically speaking, this array is not empty, as we initialize it with null values. This means that after the code executes in the constructor, we will end up with an array filled with null values, depending on the number we passed in.

For example, if we execute this:

const parking = new ParkingLot(5);

It will result in this:

[null, null, null, null, null] // lenght = 5

instead of [] // empty array, length 0

After going through the constructor, let’s take a look at the rest of the methods in the class.

park() – This is where we do the actual parking of a car. This method iterates over the slots array, checks if there are free spots (that is, slots that are still equal to null), and adds in the car in those empty spots.

Cars are given by carId. This is just an identifier we use to signify that we have a car in a certain spot. Note that this method returns false if there are no free slots or true if parking was successful.

getSlots() – Helper method that just returns the array we use to store the parking slots.

remove() – This is how we remove cars from the parking lot. This method also iterates over the slots array.

💡As you may have noticed up until now, in almost every case when we need to manipulate data stored in a data structure like array, we have to iterate over this structure so that we can access its elements.

Different programming languages provide different data structures and methods to work with them, but the main idea is always the same: when you need to do something with this data, you need to iterate over it in some way.

To remove a car from the parking lot, we use the aforementioned identifier. We look for such items in the slots array, and if we get a match, we have a car to ‘un-park’. We perform the actual removal by just setting that specific slot to null again.

Now you can guess why we decided to initialize our slots array with nulls in the first place.

This method also returns a boolean result depending on whether there was a successful removal or not.

We should be able to use this feedback when building some kind of UI that is able to react to such changes. The same is valid when adding cars to the parking lot (look at the park method).

getSize() – Another helper method that we use to check the parking lot size.

getAvailable() – This one shows us how many available slots we currently have.

isFull() – Tells us if the parking lot is full, that is that there are no more available slots.

How to Build the React App

Parking Lot app - main screen

Here is where the fun starts. 🕺

We are going to create an interactive app, visualizing the tasks which we can perform with the help of our implementation above.

Our app will provide basic UI controls allowing an (imaginary) operator to work with the parking lot software_._ And in order to make their work a bit more pleasing to the eye, we will try to animate the basic functions our software provides.

Let’s see how! 📺

Demo

Here is the live demo for those of you who doesn’t care about the details and just want to ‘taste’ it: 🥪

Embedded content

Source Code

Here is the repo with the app's source code.

Let me give you a brief summary on the what and the why.

The app is built with vite. The reason for this is that I've been playing around recently with it and I am really happy with the speed and the performance it provides.

No matter that it’s still in the relatively early stages of development – if I am about to start a new project and am in a position to choose, I will go with vite.

This is not to say I have anything against its big brother CRA. On the contrary, I have built multiple apps with it and I am still using it in some of my projects. It’s just that vite is much faster and often gives me everything I currently need.

💡Just keep in mind that selecting a given technology always depends on your specific needs for a specific project. That is to say that there is no silver bullet. It’s always a matter of requirements and priorities.

Structure of the React App

App structure

The app's structure is straightforward. At the root level we have two folders – assets and src. The first contains the assets used in the app (in this case it’s just a car image). The later contains all the files with the source code.

Let’s take a closer look inside the source folder.

Here we have the following folders:

• components – contains all React components used in the app

• lib – contains the parking lot class, responsible for the main logic of the app

• pages – contains two sub-directories, for the two main screens in the app – Landing and Main, respectively

• utils – contains a helper method for generating fictitious car license plates that we use later when representing a parking slot as busy

• And several files, most of them are related to the entry point of the app, except the favicon ones – their role should be clear to you. If not, take a look at the tab of your browser 😉

Browser tab with favicon

App Pages

As mentioned earlier, the main pages (also called screens) in the app are called Landing and Main. These are React components themselves. They serve as skeletons for everything you see in the welcome page – where you land initially and where you can select how many parking slots you want to have in your parking lot.

Welcome page

And the page you go to after clicking the big, pink submit button - the main screen where your operator is able to manage the parking lot.

Main page

App Functionality

The app provides very basic functionality for managing an imaginary parking lot. When the user select how many slots they want (max 20), they'll be transitioned to the main screen. There, the user will be able to see all free parking slots.

When a car is parked, via the PARK! button, the relevant spot will be visualised as busy and will show the registration number of the car being parked there. The operator can un-park cars by clicking on a busy slot, that is on the car they want to “remove” from the parking lot.

💡The simple animation of the moving red car is just for visual effect and doesn’t have any real influence on the way the parking lot works.

I used CSS modules for styling the app. I also tried to make the app a bit mobile friendly, in case you decide to try it on your mobile device.

Be my guest and give a try 🧪

Conclusion

My initial idea behind this post was to describe the parking lot class itself. You know, just for educational purposes. To show you how can you write such a class in JavaScript.

But then I thought it’s kind of boring 🥱. I wanted to create something funnier 💃🏻, something more gamified 🕹️ so to speak.

And this is how I ended up with this mini game-like app 🎮.

While building it, my 5 year old daughter 🧒🏻 saw it and wanted to play with it. And she had a lot of fun actually!

Yes, yes, of course! I am not saying that if it was something funny for a 5 year old, it will be for you too 😀.

My only goal was to catch your attention through the game, so that the knowledge 📖 behind it stays longer with you.

Thanks for reading! 🙏

We will use React with Typescript for creating the UI, Redux for managing the application state, and styled-components for applying the styling. And last, but not least, we'll use WebSockets for fetching the data feeds.

GitHub Repo

💡 If you want to skip the reading, here 💁 is the GitHub repository with a detailed README 🙌, and here you can see the live demo.

What is an Order Book?

An Order Book is an application that usually displays some kind of information related to buying and selling stuff.

💡 The most common use case is showing data for various assets, such as stocks, bonds, currencies, and even cryptocurrencies.

Why Would I Need an Order Book?

In practice, Order Books are used by traders to watch the fluctuations of the bidding price and the asking price of certain products – currencies, stocks, and so on.

This is happening real time, so the changes can be very rapid. Here is where WebSockets will come in handy, as you will see later.

In the past, people did something similar on paper, but the ‘real-time' part was impossible, of course.

A regular Order Book usually has two sides: buying (or bidding), shown in green on the left side and selling (or asking), red, on the right.

Classic Order book

The Plan for our Order Book App

Our Order Book app will consist of five parts:

• order book main view

• grouping select box

• Toggle Feed button

• Kill Feed button

• Status Message.

The app design will look as shown below. Note that the Status Message component, that you will see in the my implementation, is missing on these screenshots:

Desktop layout

Mobile layout

Application Features

Order book

The order book has two sides: the buy side and the sell side.

Both sides contain information about the number of orders opened at each price level.

Each level displays:

• Price: this is what defines the level. As orders must be placed at a price that is a multiple of the selected market's tick size (0.5), each level will be an increment of 0.5 (as long as there is an order open at that level).

• Size: the total quantity of contracts derived from open orders that have been placed at this level.

• Total: the summed amount of contracts derived from open orders that reside in the book at this level and above. To calculate the total of a given level we take the size of the current level and sum the sizes leading to this price level in the order book. The total is also used to calculate the depth visualizer (colored bars behind the levels). The depth of each level is calculated by taking that level's total as a percentage of the highest total in the book.

Grouping Select Box

By default the orders are grouped by the selected market's ticket size (0.5).

Possible toggling of the grouping is between 0.5, 1, 2.5 for XBTUSD market and 0.05, 0.1 and 0.25 for ETHUSD market.

To group levels, we combine the levels rounded down to the nearest group size – for example, if we change our grouping from 0.5 to 1 then we would combine the data from prices 1000 and 1000.5 and display it under a single level in the order book with the price 1000.

Toggle Feed Button

This button toggles the selected market between PI_XBTUSD and PI_ETHUSD. These are the two markets we will support -> Bitcoin/USD and Ethereum/USD.

It supports dynamic grouping logic and handles groupings for XBT (0.5, 1, 2.5) and groupings for ETH (0.05, 0.1, 0.25).

Kill Feed Button

Clicking this button stops the feed.

Then clicking this button a second time renews the feed.

Status Message

This message will show the currently selected market. It will also show a message saying the feed is killed.

Tech Stack for our App

Here is a list of the main technologies we will be using:

• React with TypeScript (yarn create react-app my-app --template typescript) — a UI library we will use for building our application’s user interfaces.

• Redux — a state management library we will use for managing our application’s state.

• WebSockets — The WebSocket object provides the API for creating and managing a WebSocket connection to a server, as well as for sending and receiving data on the connection. We will use it to implement the logic for consuming the live feeds as well as to be able to stop and renew.

• styled-components — a CSS-in-JS library that lets you define the CSS styles of your components using ES6 template literals. We will use it to add styles to our app and make the look and feel beautiful. It utilizes tagged template literals to style your components and removes the mapping between components and styles. This means that when you’re defining your styles, you’re actually creating a normal React component that has your styles attached to it.

• react-testing-library — The React Testing Library is a very light-weight solution for testing React components. We will use it for testing the UI components of our app.

• Jest - a JavaScript Testing Framework that has become the de facto standard when we talk about testing React applications. We will use it to write some unit tests that will cover the reducer functions we have in our app.

How to Build the App

From this point onward I will try to guide you through the process I followed when building this.

💡 I must say that what I am showing you here is just a way of creating such an app – but it's not the way in any regard. Probably folks with more experience in crypto would do it better.

Project Structure

The project structure is pretty straightforward. We are using React and styled-components, which makes this way of structuring very convenient.

Let's see first what it looks like and then I will explain the what and the why.

Project structure

As you can see on the image above, I have organized most of the components in folders. Each folder contains an index.tsx file, a styles.tsx and a .test.tsx files.

index.tsx – contains the code responsible for the component logic.

styles.tsx – contains the code responsible for styling the component. Here is where styled-components shines.

.text.tsx – these contain the component unit tests.

Let me give you a short summary of the idea behind each of the components in the components folder. Starting top to bottom:

Button renders a button with a given background color and title. It's used for the two buttons in the footer, Toggle Feed and Kill Feed / Renew Feed.

DepthVisualizer is the component responsible for drawing the red and the green backgrounds you are seeing behind the numbers. It does this by rendering a row (an HTML div element) with given width, position being left (Bids) or right (Asks).

Footer – well, there's not much to say here, it contains the two buttons used in the app.

GroupingSelectBox renders the select box we use to change the grouping value, using setGrouping reducer to amend the application state when grouping is being changed.

Header renders the title of the application as well as the GroupingSelectBox component.

Loader renders loading animation implemented by leveraging SVG.

Order Book contains the core logic of the app. Separated components are located in sub-folders, and the Redux state management logic is here also.

Spread renders the spread value, displayed in the middle of the header (in desktop view). The component itself contains short methods for calculating the amount itself and the percentage value.

StatusMessage is a small component used to display status messages. It basically shows which market is currently being displayed and whether the feed is killed.

Rendering Performance

Here is a good moment to talk about rendering performance and inline styling a bit.

Rendering is the process of React asking your components to describe what they want their section of the UI to look like based on the current combination of props and state.

This process is triggered by a change of the state in your component. This change could be caused by some of the props being changed or by some internal logic of the component.

The point here is that when re-rendering happens unnecessarily, it reduces the performance of our app. This is exactly what happened to me when I introduced the initial implementation of the DepthVisualizer component. It was using styled-components, that is JavaScript, for the drawing part.

In order to solve this, I have changed the component to use inline styles, that is pure CSS, instead of a CSS in JS approach. In other words, my bottleneck was using JavaScript animations, which is a famous reason for reduced performance.

Here is how it looks like now:

const DepthVisualizer: FunctionComponent<DepthVisualizerProps> = ({windowWidth, depth, orderType }) => {
  return <div style={{
    backgroundColor: `${orderType === OrderType.BIDS ? DepthVisualizerColors.BIDS : DepthVisualizerColors.ASKS}`,
    height: "1.250em",
    width: `${depth}%`,
    position: "relative",
    top: 21,
    left: `${orderType === OrderType.BIDS && windowWidth > MOBILE_WIDTH ? `${100 - depth}%` : 0}`,
    marginTop: -24,
    zIndex: 1,
  }} />;
};

export default DepthVisualizer;

Inline styling is when you write your CSS along with your markup, as values for the style attribute. This is something that is NOT considered a good practice, but as you can see here, there are cases when it's necessary to use it.

💡 Usually you would extract your CSS code into a separate file.

Footer a simple dummy component used to render the two buttons in the footer of the app.

Dummy components, also known as stateless or representational ones, are components that don't hold state and are usually used just to visualize data in some way. This data is being passed via the props. For example the isFeedKilled flag in the component above.

If such a component needs to execute some kind of interaction, it usually does this by accepting (again via the props, for example toggleFeedCallback) callback functions that can be executed when that interaction happens. For example clicking a button.

On the opposite side we could have smart or state-full components. They are the ones that are connected to the app state and can manipulate it directly. Usually they are the ones that read the data from the state and pass it to the stateless components via their props.

GroupingSelectBox contains the Select element you can use to switch between the groupings.

Header is the header part of the app. It takes care of setting properly the layout consisting of the title 'Order Book' on the left and the select box on the right.

Loader is used as an indicator for when the data has not yet been loaded. It leverages a SVG animation I have found online.

Order Book is where the real thing is happening. This one consists of a few smaller components:

• TableContainer – used for styling the views for both the Odds and Bets sides.

• TitleRow – this is the component responsible for displaying the titles of the columns: prize, size, and total, respectively.

How to Build the UI with React and styled-components

When we talk about component-based structure, such as the one React provides us, the styled-components library is likely one of the first choices you might make when styling is needed.

Like Josh Comeau says in his detailed article:

💡 It's a wonderful tool. In many ways, it's changed how I think about CSS architecture, and has helped me keep my codebase clean and modular, just like React!

As the name of the lib hints, we could easily style our components by using the CSS-in-JS pattern. Here is an example of how I used it to write the styles for my Button component:

import styled from "styled-components";

interface ContainerProps {
  backgroundColor: string;
}

export const Container = styled.button<ContainerProps>`
  padding: .3em .7em;
  margin: 1em;
  border-radius: 4px;
  border: none;
  color: white;
  background: ${props => props.backgroundColor};
  font-family: "Calibri", sans-serif;
  font-size: 1.2em;

  &:hover {
    cursor: pointer;
    opacity: .8;
  }
`

Notice how I am using an interface in my styles file, and also the background property being passed as an argument via props. This is part of the CSS-in-JS story.

The possibility to use CSS code in JavaScript or (as someone might say) vice versa comes very handy. For example, when we need a component to look differently depending on something, we can pass through its props a parameter to define this.

As every style is actually a component, this way of writing styles feels a lot like writing React components. I mean, in the end, everything is components, right?

Responsiveness and Page Visibility Detection

While working on this app, I read in several places that, for applications which support rapid updates, is a good practice to implement some kind of mechanism for pausing the whole thing when it is not being used by the user. For example when the user minimizes the browser window or just opens another tab.

Since our Order book is consuming a lot of new chunks of data every second via WSS, I decided to implement such a mechanism as well.

What this does is:

• it shows a loader when the data is not there yet

• it changes the meta title to signify that the app is in paused mode

• it unpauses the work once the app window is on focus

Active mode

Paused mode

You may see the whole implementation here.

The essential part is in the useEffect hook, which is triggered only once when the application renders for first time.

In there we take advantage of the Page Visibility API by attaching the necessary listeners. And then, in the handlers, we simply execute the logic we want.

Window Size Detection

In almost every app that has some level of responsiveness, you need some logic for detecting the changes in the window size and taking some actions accordingly.

In other words, you need to know when your app is being viewed in certain screen size, so you can arrange your components and adjust your styles so that everything looks nice and in place.

This is especially valid for mobile friendly applications, where responsiveness is essential.

Our implementation of the window size change detection is based on the innerWidtgh property of the browser window object and onresize event that is being triggered when it gets resized.

I am attaching a listener for this event in a useEffect hook in App.tsx file. And then, every time the window size changes, I am setting the new width to a state variable via setWindowWidth hook.

const [windowWidth, setWindowWidth] = useState(0);
...
...

// Window width detection
useEffect(() => {
  window.onresize = () => {
    setWindowWidth(window.innerWidth);
  }
  setWindowWidth(() => window.innerWidth);
}, []);

Then propagate this variable down through all interested components and use it accordingly. For example here is how I use it in Order Book/index.tsx in order to know when and where to render the TitleRow component.

{windowWidth > MOBILE_WIDTH && <TitleRow windowWidth={windowWidth} reversedFieldsOrder={false} />}

TitleRow component - desktop view

TitleRow component - mobile view

Note that it appears on different position depending on that whether you are seeing the app on desktop or mobile.

You may take a look at the component itself and see similar approach of using the window width there.

State Management with Redux

As you probably guessed already, I used Redux for managing the state of the app.

The main logic behind that is concentrated in the orderbookSlice reducer. In the following few lines I will walk you through it and see how and why I built it that way.

First we define the interface and the initial state of our order book data. The initial state contains the default values we need to have in place when starting the app.

export interface OrderbookState {
  market: string;
  rawBids: number[][];
  bids: number[][];
  maxTotalBids: number;
  rawAsks: number[][];
  asks: number[][];
  maxTotalAsks: number;
  groupingSize: number;
}

const initialState: OrderbookState = {
  market: 'PI_XBTUSD', // PI_ETHUSD
  rawBids: [],
  bids: [],
  maxTotalBids: 0,
  rawAsks: [],
  asks: [],
  maxTotalAsks: 0,
  groupingSize: 0.5
};

Then there are a few short, self-explanatory methods helping to manipulate the levels data:

const removePriceLevel = (price: number, levels: number[][]): number[][] => levels.filter(level => level[0] !== price);

const updatePriceLevel = (updatedLevel: number[], levels: number[][]): number[][] => {
  return levels.map(level => {
    if (level[0] === updatedLevel[0]) {
      level = updatedLevel;
    }
    return level;
  });
};

const levelExists = (deltaLevelPrice: number, currentLevels: number[][]): boolean => currentLevels.some(level => level[0] === deltaLevelPrice);

const addPriceLevel = (deltaLevel: number[], levels: number[][]): number[][] => {
  return [ ...levels, deltaLevel ];
};

Then the real magic is happening. If the size returned by a delta is 0 then that price level should be removed from the order book. Otherwise you can safely overwrite the state of that price level with new data returned by that delta.

/** The orders returned by the feed are in the format
 of [price, size][].
 * @param currentLevels Existing price levels - `bids` or `asks`
 * @param orders Update of a price level
 */
const applyDeltas = (currentLevels: number[][], orders: number[][]): number[][] => {
  let updatedLevels: number[][] = currentLevels;

  orders.forEach((deltaLevel) => {
    const deltaLevelPrice = deltaLevel[0];
    const deltaLevelSize = deltaLevel[1];

    // If new size is zero - delete the price level
    if (deltaLevelSize === 0 && updatedLevels.length > ORDERBOOK_LEVELS) {
      updatedLevels = removePriceLevel(deltaLevelPrice, updatedLevels);
    } else {
      // If the price level exists and the size is not zero, update it
      if (levelExists(deltaLevelPrice, currentLevels)) {
        updatedLevels = updatePriceLevel(deltaLevel, updatedLevels);
      } else {
        // If the price level doesn't exist in the orderbook and there are less than 25 levels, add it
        if (updatedLevels.length < ORDERBOOK_LEVELS) {
          updatedLevels = addPriceLevel(deltaLevel, updatedLevels);
        }
      }
    }
  });

  return updatedLevels;
}

What follows after these are few helper methods. Let me say a few words about each of them now:

• addTotalSums – with the help of this method, we iterate through the orders data, bids or asks, and calculate for each of them the total sum. The total sum value is then used for making the background visualizations.

• addDepths – we use this method to calculate the so-called depth for each order. These values will be used later by the depth meter component to display the red and green rows in the background.

• getMaxTotalSum – this one returns the max value of all total sums.

Everything below is what we use for creating the application state. As per the Redux Toolkit documentation, it’s using createSliceAPI to create the slice.

Redux state

Creating a slice requires a string name to identify the slice, an initial state value, and one or more reducer functions to define how the state can be updated.

Once a slice is created, we can export the generated Redux action creators and the reducer function for the whole slice.

The last few lines consist of the exports in question – action creators, state slices selectors and the main reducer.

export const { addBids, addAsks, addExistingState, setGrouping, clearOrdersState } = orderbookSlice.actions;

export const selectBids = (state: RootState): number[][] => state.orderbook.bids;
export const selectAsks = (state: RootState): number[][] => state.orderbook.asks;
export const selectGrouping = (state: RootState): number => state.orderbook.groupingSize;
export const selectMarket = (state: RootState): string => state.orderbook.market;

export default orderbookSlice.reducer;

With all that, our state manipulation logic is complete. 🎉

Now it’s time to take a look at the protocol we used in our app to take advantage of all these rapid changes in the data we consume.

Websocket Protocol (WSS)

As you may have noticed, we're using the Web Socket communication protocol for fetching data into our application. We also use its features, as you will see in a moment, to accomplish other things (such as toggling the feeds and subscribe/unsubscribe from the data channel).

Here is how I used it.

Instead of trying to rely on manual implementation, I used the react-use-websocket package. It gives you all you need when you want to leverage WSS in a React app. If you want to go into details about this, you may take a look at their documentation.

A Few Words About My Implementation

What we need fist is the endpoint URL where the data feeds are coming from. I am sure there are multiple options out there when we talk about cryptocurrencies. In our app I used the one provided by www.cryptofacilities.com/.

const WSS_FEED_URL: string = 'wss://www.cryptofacilities.com/ws/v1';

Then the only thing we need to do to start consuming the data is to put the useWebSocket hook to work. As you may have guessed already, this hook is provided by the package mentioned above.

import useWebSocket from ["react-use-websocket"](<https://github.com/robtaussig/react-use-websocket>);

...
...
...

const { sendJsonMessage, getWebSocket } = useWebSocket(WSS_FEED_URL, {
    onOpen: () => console.log('WebSocket connection opened.'),
    onClose: () => console.log('WebSocket connection closed.'),
    shouldReconnect: (closeEvent) => true,
    onMessage: (event: WebSocketEventMap['message']) =>  processMessages(event)
  });

We pass the endpoint as the first argument and a few callback functions after that. These help us perform certain actions when one of the following happens:

• onOpen – what to do when WebSocket connection is established.

• onClose – what to do when WebSocket connection is terminated.

• shouldReconnect – this is just a flag, saying if we want automatic reconnect when the connection drops for some reason.

• onMessage – this is the main event that brings us the chunks with the data (I call processMessage method every time when that happens. This means that every time when a new chunk of data is received, we process it and display it respectively).

Down below is the method in question. It simply does two things:

• Either calls a method called process (No pun intended 😄) – this method is called every time new data for bids or asks is received and it processes it accordingly.

• Dispatches an event that is using one of the reducer functions we have seen earlier. This function practically creates the initial state of our application.

In order to decide whether we are adding data to the current state or we should initialize it, we check for a property called numLevels. This is something that comes from the API, the very first time we establish the WebSocket connection.

Initial payload

The rest of the code you see in this file is mostly for preparing and rendering the results on the screen.

The most interesting part would be the method buildPriceLevels that is used for both halves – bids and asks. It sorts the data, makes the necessary calculations, and passes it to the relevant components for visualizing it. Those are DepthVisualizer and PriceLevelRow I mentioned earlier in this article.

Grouping

The grouping is an important part of how the order book works, as it defines by what ticket size the orders are grouped.

In our application, I have implemented a toggling functionality per each market, that allows grouping it as follows:

• Between 0.5, 1, 2.5 for XBTUSD market.

XBTUSD market grouping

• Between 0.05, 0.1 and 0.25 for ETHUSD market.

ETHUSD market grouping

There is a short gist I created when trying to figure out how to implement the grouping logic. You may find it here.

Also, aside from that gist, while developing this I have performed more than a few experiments out of the project itself. And just because these are just local files on my computer, I will publish them here for those of you who are even more curious.

It’s a small side npm project that has only one dependency. Here is the package.json file:

{
  "name": "grouping",
  "version": "1.0.0",
  "main": "index.js",
  "license": "MIT",
  "dependencies": {
    "lodash.groupby": "^4.6.0"
  }
}

And here is the code itself:

const bids = [
    [
        50163,
        110
    ],
    [
        50162,
        13140
    ],
    [
        50158,
        3763
    ],
    [
        50156,
        1570
    ],
    [
        50155,
        21997
    ],
    [
        50152.5,
        450
    ],
    [
        50151,
        4669
    ],
    [
        50150.5,
        10329
    ],
    [
        50150,
        2500
    ],
    [
        50149.5,
        450
    ],
    [
        50149,
        4022
    ],
    [
        50148,
        20000
    ],
    [
        50147,
        5166
    ],
    [
        50146.5,
        5274
    ],
    [
        50145,
        174609
    ],
    [
        50143,
        20000
    ],
    [
        50141,
        28000
    ],
    [
        50140.5,
        5000
    ],
    [
        50138,
        6000
    ],
    [
        50132.5,
        4529
    ],
    [
        50132,
        4755
    ],
    [
        50131,
        12483
    ],
    [
        50128.5,
        61115
    ],
    [
        50128,
        23064
    ],
    [
        50125.5,
        181363
    ]
]

/* function roundDownNearest(num, acc) {
    if (acc < 0) {
        return Math.floor(num * acc) / acc;
    } else {
        return Math.floor(num / acc) * acc;
    }
} */

/* function groupByTicketSize(ticketSize, levels) {
    const result = levels.map((element, idx) => {
        const nextLevel = levels[idx + 1];

        if (nextLevel) {
            const currentPrice = element[0];
            const currentSize = element[1];
            const nextPrice = nextLevel[0];
            const nextSize = nextLevel[1];
            console.log("current level: ", element)
            console.log("next level: ", nextLevel)

            element[0] = roundDownNearest(currentPrice, ticketSize);

            if (currentPrice - nextPrice < ticketSize) {
                element[1] = currentSize + nextSize;
            }
            console.log("==================================> Result: ", element)

            return element;
        }

    }).filter(Boolean); 


    console.log("============================================================");
    console.log(result)
} */

const test = [
    [1004.5, 1],
    [1001.5, 1],
    [1001,   1],
    [1000.5, 1],
    [1000,   1],
    [999.5,  1],
    [999,    1],
    [990,    1],
    [988,    1]
]

function groupByTicketSize(ticketSize, levels) {
    const result = [];

    for (let i = 0; i < levels.length; i++) {
        console.log(levels[i])
        const prevLevel = levels[i-1]
        const level1 = levels[i]
        const level2 = levels[i+1]

        if (prevLevel && level1 && level1[0] - ticketSize === prevLevel) return

        if (level2 && level1[0] - level2[0] < ticketSize) {
            const newLevel = [level2[0], level1[1] + level2[1]];
            console.log("newLevel", newLevel)
            result.push(newLevel);
        } else {
            result.push(level1)
        }
    }

    console.log("============================================================");
    console.log(result)
}

// groupByTicketSize(1, bids);
groupByTicketSize(1, test);

How to Perform Unit Tests on the App

For performing unit testing I used the react-testing-library.

The main idea behind it that the developer should write tests only for what the user will see and interact with. There is no much point of testing implementation details.

💡 Imagine, just to give you an example, that you have implemented a list component that is just displaying lines of textual data. Say something like a todo list.

Then imagine that this data is coming from an API call in the shape of array. A data structure that you could easily iterate through via various methods – some sort of a loop cycle, such as for() or while(). Or you could use another more functional approach, say .map() method.

Now ask yourself – for the end user, the one that will just see the listed text data, does your implementation matter? As long as everything works as expected and in a good, performant way, the answer is ‘no, it does not’.

This is what your tests should reflect.

In the context of our Order Book application, each test file is located in the same directory as the implementation file. Most of the tests are short and self-explanatory, due to the fact that these are testing mostly rendering logic and only the happy path.

For example let’s take a look at the button component tests below:

import React from 'react';
import { render, screen } from '@testing-library/react';
import Button from './index';

test('renders button with title', () => {
  render(<Button backgroundColor={'red'} callback={jest.fn} title={'Toggle'} />);
  const btnElement = screen.getByText(/Toggle/i);
  expect(btnElement).toBeInTheDocument();
});

It just verifies that the component is rendered properly and it displays what we expect the user to see. Which is the title Toggle in this case.

For testing the reducers I have used Jest, as this is the only not visual part that we'll cover. These tests are also pretty simple and self-explanatory. I use them for testing whether the initial application state is in place and to see that adding price levels to that state works correctly.

How to Deploy the App to Vercel

Finally – deployment time. 🎉

After finishing the development and testing our application, let’s put it live.

I used the Vercel platform for this purpose. They offer a pretty rich and easy to use interface as well as integrations for all famous source control platforms out there – including, of course, GitHub (where our application repo lives).

Assuming you have a GitHub account, what you need to do if you want to deploy it on your own is to login with it here.

Vercel login screen

Click on the +New Project button in the top right corner. Then import your Git repository using the provided options in the screen that opens. Here is how mine looks:

Vercel Import Git Repository screen

After importing the project, you will be able to do the actual deploy. When finished, Vercel will generate URLs for you to access your newly deployed app.

Vercel production deployment screen

And I think you will receive an email letting you know if your deployment was successful. That email also contains these URLs.

Vercel successful deployment email

Congratulations! 👏🏻

You now have your own Order Book application up and running online.

How to Add a Build Badge on GitHub

This is not order book related, but I decided to share it with you here anyway. It’s about those small details that make the big picture somehow more complete and attractive.

Maybe some of you have wondered how can you get one of these so called badges?

Here is the answer: https://shields.io/.

You go to the Other section and find the GitHub Deployments option.

Then click on it and follow the instructions.

There is one more thing you need to do in order to have this fully functioning. You go to your GitHub repository → Actions tab and create new workflow file. You may just go ahead and copy the content of mine from here. Name it main.yml.

What this will do is run the jobs defined in that file. In our case this is just the build job which is basically spinning a new build and running the tests.

After completing this, you just need add the following lines to your README file:

<!-- prettier-ignore-start -->
[![Tests](<https://github.com/mihailgaberov/orderbook/actions/workflows/main.yml/badge.svg>)](<https://github.com/mihailgaberov/orderbook/actions/workflows/main.yml>)
[![Build Status][build-badge]][build]

[build-badge]: <https://img.shields.io/github/deployments/mihailgaberov/orderbook/production?label=vercel&logoColor=vercel>
[build]: <https://github.com/mihailgaberov/orderbook/deployments>
<!-- prettier-ignore-end -->

💡 Don’t forget to put your own details in the URLs, that is your GitHub username and the name of your repository.

After pushing these changes you should see the badges displayed on your README: 🥳.

GitHub badges

Wrapping Up

If you are reading this from the beginning, I will name you a champion. 🍾

It has been a long trip, but hopefully interesting and fun to walk along with me!

Now it’s time to summarize what we have done here and try to extract some useful insights which will help us in our future development challenges.

I will layout below my opinion of what was the most challenging in building this application. And I will be even more eager to find out what is yours.

Rendering Performance

This really bit me in the beginning, when I was building the UI and was trying to implement the drawing of the price level rows.

I mentioned earlier how I have managed to solve it and I think this is going to be something I will remember for sure.

Grouping Functionality

Implementing this was also kind of challenging because there were several factors I had to take into account. Because of the market we are in and the range I had to do the calculations in.

It took me a while to polish it (remember the side mini project and the gist I shared in the previous sections) and I still think it could be improved even more. Try switching between the markets and the grouping values multiple times and observe the results.

Space for Improvement

One thing already mentioned is for sure the grouping. Which should also improve the visualizing of the red and green parts – they (almost) always should form a not ideal triangle.

If we try to look at the bigger picture, this order book application can be a part of a dashboard screen filled with other widgets as well, and they all can interact between them.

For example, changing the grouping of the order book to reflect on changing the views in the other widgets as well – say showing a market chart like this one below:

I am not even mentioning adding new markets as an improvement, as it’s kinda clear. But this should be taken into account when building the functionality for the current markets, as to do it in a way that will be easily extendable. So that adding a new market to the order book be a trivial and quick task to do.

I think that's all from me.

Thanks for reading! 🙏

References

Here are few links you might find useful to read:

The styled-components Happy Path

Blogged Answers: A (Mostly) Complete Guide to React Rendering Behavior

I collected the receipts? along the way. And I planned to calculate, at the end of the trip, how much the whole journey cost me.

In the end I had a full bag of papers. Which meant that I had a lot of numbers to sum up.

I put them in a spreadsheet on my PC, ready to start calculating them by hand. And then, my programmer's mind started talking to me - why should I do all this manual work ?️ when I could write a short program to do it for me?

Don't get me wrong, I am aware there are a lot of other ways to do such calculations. But since I would like to call myself a programmer who loves to automate stuff, I wanted to do it myself. In the old school way.

I decided to use Node.js to solve this problem, mostly because I am quite comfortable with JavaScript. And this was supposed to be a very quick solution that I came up with during a cup of coffee ☕ in the morning.

So, here is what I did:

First, I filled in all the numbers I had in a txt file, each on a new line.

Data source in a txt file

Then I wrote a small program that read the data source file, parsed the numbers on a new line as a separated value to be added, and did the summing up.

var fs = require('fs');

calculate = () => {
    fs.readFile('data.txt', 'utf8', (err, data) => {
        if (err) {
            throw new Error(err)
        }

        const arr = data.split('\r\n');
        const result = arr
            .filter(e => e)
            .map(parseFloat)
            .reduce((curr, next) => curr + next);
        console.log('RESULT: ', result);
    });
}

How I built this tool

I will say a few words about the implementation first. Then we'll go through a brief discussion about what other options I could have chosen.

This is a very short function that leverages a Node.js package, fs. It allows us to interact with the operating system (for example to read or write files to it). This is exactly what we need in order to be able to read our data source file.

The code itself follows the standard Node.js callback mechanism. And inside the callback function I used a bit of a functional approach: Piping multiple methods that get the data from the previous processing, do something on it, and then pass it to the next.

Piping methods

The first method, split, parses the data that is being read from the text file by using the \r\n separator. These symbols are used in the programming world to specify when a new line (in a file) is coming.

At this stage in our program, we have our numbers that have been read and parsed from the txt file. Now we use the filter method. This step strips the data out of any empty values.

Then we go for the map method - this is a JavaScript Array method that accepts a callback function. This callback will be executed on each of the arguments of a given array.

In our case the data is being passed implicitly – what's coming from the filter method output will go as input for the map method. And each of the members of this input will be processed by the parseFloat method.

This is another JavaScript method that parses an argument, converting it to string first if needed, and returns a floating point number. We need to perform this step to guarantee that we get a correct calculation.

The last step from our pipeline is the reduce method, a third JavaScript Array method we're going to use.

This method has multiple applications, but in our case we are using it just to sum up the numbers in the array while iterating it.

The reducer callback function that this method accepts does the real work. I have extracted mine in a separated named method to improve the readability of the code.

What we need to do vs what we can do

In the last section I promised a brief discussion on what else we could use to achieve the same goal.

Now it's time to stop for a moment and think about what we need to do versus what and how we can do it.

In this specific case my goal was very simple. I had some numbers that I needed to sum up automatically.

This made me think – what data structure did I need to put the data in, in order to have multiple choices for easy processing? That's how I came up with an array. After all, it's one of the simplest and most-used data structures in JavaScript.

And from here you have several options:

1. You could do as I did in my example – use JavaScript Array methods such as map, filter, and reduce in a more functional manner. Or,

2. You could go the old fashioned way and use regular loops to iterate over the array and do the calculation. Such loops could be for-, while-, forEach or even do-while JavaScript loops. In such small programs the performance is negligible, so it's up to you what to use.

Both choices would work fine. What is more important here is that you should always make your decisions based on what your end goal is.

In this article I discussed a very short and quick to implement automation tool. It did the job I needed it to do. Given the fact I didn't have much time to invest, the first working solution was good enough.

But there will be cases where you should perform a much more sophisticated analysis in advance so that you end up with good quality software in the end.

Keep your end goal as your guide when deciding what to do and how to do it, and you will always be on track.

Give it a shot

If you want to try it yourself, please make sure you have installed Node.js on your system. Then go ahead and check out this repository.

In order to run the program, use the following command when you're in the directory where the calc.js file is:

node calc.js

Check your console window to see the result. Mine looks like this:

Console output

That's all what I wanted to share with you. I hope part of this experience will stay with you for your future automation tasks.

? Thanks for reading! ?

Now and then you have used some back-end technologies, but you've always stayed in your comfort zone, perhaps in the JavaScript world. Or maybe you have built a small API with Python.

But you have never touched the modern .NET family tech stack.

This tutorial will guide you, step-by-step, in building a modern single page application (SPA) that will take advantage of Vue.js for the front-end and .NET Core (C#) for the back-end.

We will also see how to write some tests, both unit and integration, to cover the front and back end functionality (at least partially).

If you want to skip the reading, here ? is the GitHub repository with a detailed README ?.

What Will We Build

?‍? We will build a web app where users can signup/login and just tell us how much they love pizzas, by pressing an "I love it" button.

There are no restrictions on the number of times each user can show us their appreciation. The only requirement is that only logged in users can vote.

On the home page, along with the signup/login buttons, we will put a little bar-chart, displaying the top X users with the highest appreciation (on the X-axis) and the number of votes on the Y-axis.

Installation

Let's start with the front end. It makes more sense to build the visible parts of our app first. We will build our front end with one of the most famous front-end libraries on the market: Vue.js.

How to Set Up the Front End

In order to install and configure our initial front end setup with Vue.js, we will use the Vue CLI. This is a standard command-line tool for developing Vue.js applications.

To install it, use the following command. Note that all commands in this tutorial use NPM, which you need to have installed on your machine in order to follow along.

npm install -g @vue/cli

After successfully installing the Vue CLI, we should be able to start using it to install and configure Vue.js itself. Let's do with the following process.

Step 1: Create a new empty project directory and open it with the following commands:

mkdir pizza-app
cd pizza-app

Step 2: While in the project root, run the following:

vue create frontend

Then from the provided options, select the following:

• Manual select features

Vue.js installation - Manually select features

• Babel

• Router

• CSS-Preprocessors (SASS)

Vue.js installation - select features

Then select version 2.x from the next screen:

Select version 2.x

Next, select 'Use history mode for router?' and 'Sass/SCSS (with node-sass)', like so:

• Linter / Formatter

• Unit Testing with Jest

• E2E Testing with Cypress

After this last step, finish the installation process with the default options.

Now we are ready to run the app by using the following commands from the root project folder:

cd frontend
npm run serve

After the app is running, you can see it in your browser on http://localhost:8080:

Vue.js default installation screen

Before going on with building the actual components that our front-end app will have, let's install our back-end app via the .NET Core CLI.

How to Set Up the Back End

As mentioned above, we will use another command line tool, the .NET Core CLI, that gives us the ability to create and configure .NET applications.

If you don't have it already, you may use this link to download it and then install it.

Once you have the .NET Core CLI tool installed, go to your project's root directory and run the following command to create our back-end app. Thus we will create a folder called backend and install a .NET web app inside it:

dotnet new web -o backend

gitignore.io

Before continuing with installing the next packages we will need, let's sort out our .gitignore file.

This is a configuration file that tells Git what to ignore when committing changes to Git based repositories (the ones in GitHub).

Since we want to have one .gitignore file, it will include rules for two types of applications:

• a Node.js based one, which is our Vue.js front end, and

• a .NET (C#) one which is our back end.

For this, we will use a tool called gitignore.io. This tool will generate such files for us. The advantage of using this tool is that it allows us to type in what our programming languages/platforms are, and it generates the .gitignore file for us.

Use gitignore.io to generate a .gitignore file

Also, at the top of the generated file, it saves links for creation or subsequent editing, as shown below.

# Created by https://www.toptal.com/developers/gitignore/api/webstorm,vue,vuejs,visualstudio
# Edit at https://www.toptal.com/developers/gitignore?templates=webstorm,vue,vuejs,visualstudio

Now we are good to go with the rest of the packages we need to install.

First we will install a package called SpaServices, which will allow us to have our app running via only one URL, and pointing to the .NET app. From its side it will proxy requests to our front-end app.

To install it, open your terminal, go to the backend folder of your project, and run the following:

dotnet add package Microsoft.AspNetCore.SpaServices.Extensions --version 3.1.8

After this, we need to configure our back-end app with the SpaServices package in order to have the desired result.

Every request will go to our .NET back-end app, and if the request is meant for the front end, it will proxy it.

To do this, open the Startup.cs file and update its content to be like this:

using System;
using System.Collections.Generic;
using System.Linq;
using System.Threading.Tasks;
using Microsoft.AspNetCore.Builder;
using Microsoft.AspNetCore.Hosting;
using Microsoft.AspNetCore.Http;
using Microsoft.Extensions.DependencyInjection;
using Microsoft.Extensions.Hosting;
using Microsoft.AspNetCore.Authentication.JwtBearer;
using Microsoft.EntityFrameworkCore;
using Microsoft.Extensions.Configuration;

namespace backend
{
    public class Startup
    {
        public IConfiguration Configuration { get; }

        public Startup(IConfiguration configuration)
        {
            Configuration = configuration;
        }

        // This method gets called by the runtime. Use this method to add services to the container.
        // For more information on how to configure your application, visit https://go.microsoft.com/fwlink/?LinkID=398940
        public void ConfigureServices(IServiceCollection services)
        {
            string connectionString = Configuration.GetConnectionString("DefaultConnection");
            services.AddDbContext<ApplicationDbContext>(options => options.UseSqlite(connectionString));
            services.AddSpaStaticFiles(configuration: options => { options.RootPath = "wwwroot"; });
            services.AddControllers();
            services.AddCors(options =>
            {
                options.AddPolicy("VueCorsPolicy", builder =>
                {
                    builder
                    .AllowAnyHeader()
                    .AllowAnyMethod()
                    .AllowCredentials()
                    .WithOrigins("https://localhost:5001");
                });
            });
            services.AddAuthentication(JwtBearerDefaults.AuthenticationScheme)
  .AddJwtBearer(options =>
                {
                    options.Authority = Configuration["Okta:Authority"];
                    options.Audience = "api://default";
                });
            services.AddMvc(option => option.EnableEndpointRouting = false);
        }

        // This method gets called by the runtime. Use this method to configure the HTTP request pipeline.
        public void Configure(IApplicationBuilder app, IWebHostEnvironment env, ApplicationDbContext dbContext)
        {
            if (env.IsDevelopment())
            {
                app.UseDeveloperExceptionPage();
            }

            app.UseCors("VueCorsPolicy");

            dbContext.Database.EnsureCreated();
            app.UseAuthentication();
            app.UseMvc();
            app.UseRouting();
            app.UseEndpoints(endpoints => { endpoints.MapControllers(); });
            app.UseSpaStaticFiles();
            app.UseSpa(configuration: builder =>
            {
                if (env.IsDevelopment())
                {
                    builder.UseProxyToSpaDevelopmentServer("http://localhost:8080");
                }
            });
        }
    }
}

? This is the final version of the Startup.cs file and that's why you probably noticed some more stuff in it. We will get back to this a bit later in this tutorial.

At this point, you should be able to run your back-end app. If you wish to do so, run the following commands from the root folder of your project:

cd backend
dotnet run

How to Set Up Authentication

As you may remember from the description at the beginning, our app should have a Sign up/Login option.

In order to fulfill this requirement, we will use a 3rd party service called Okta. We will install the necessary packages for using the Okta SDK on both the front end and back end of our app.

But before that, you need to create an account on their website and get access to their admin panel. From there you may create a new application. Here is how it looks on mine:

Now let's start with the package we need for our front end. From the root folder, run the following commands:

cd frontend
npm i @okta/okta-vue

After this step, we are ready to amend our Vue.js app in order to take advantage of Okta SDK.

We will also install another package, called BootstrapVue, that provides a set of good looking and ready to use Vue.js components. This will help us save development time and will also get us a good looking front end.

To install it, run the following from your frontend folder:

npm i vue bootstrap-vue bootstrap

How to Set Up the Router

It's time to do some coding. We need to edit our router in order to apply what's coming from Okta authentication services.

You can see the full file in my GitHub repo, but here is the essential part that you need to configure with your own details (that you got when you registered on the Okta developer website):

Vue.use(Auth, {
  issuer: 'https://dev-914982.okta.com/oauth2/default',
  client_id: '0oatq53f87ByM08MQ4x6',
  redirect_uri: 'https://localhost:5001/implicit/callback',
  scope: 'openid profile email'
})

....

router.beforeEach(Vue.prototype.$auth.authRedirectGuard())

Home screen

After we get our router sorted, we can finally do some changes to our app's home screen, which will actually be visible to our users.

Open the App.vue file in your IDE and change its content as follows:

<template>
  <div id="app">
    <header>
      <b-navbar toggleable="md" type="light" variant="light">
        <b-navbar-toggle target="nav-collapse"></b-navbar-toggle>
        <b-navbar-brand to="/">Love Pizza</b-navbar-brand>
        <b-collapse is-nav id="nav-collapse">
          <b-navbar-nav>
            <b-nav-item href="#" @click.prevent="login" v-if="!user">Login</b-nav-item>
            <b-nav-item href="#" @click.prevent="logout" v-else>Logout</b-nav-item>
          </b-navbar-nav>
        </b-collapse>
      </b-navbar>
    </header>
    <main>
      <div>
        Love pizza button and clicks counter here
      </div>
    </main>
  </div>
</template>

<script>
export default {
  name: 'app',
  data() {
    return {
      user: null
    }
  },
  async created() {
    await this.refreshUser()
  },
  watch: {
    '$route': 'onRouteChange'
  },
  methods: {
    login() {
      this.$auth.loginRedirect()
    },
    async onRouteChange() {
      await this.refreshUser()
    },
    async refreshUser() {
      this.user = await this.$auth.getUser()
    },
    async logout() {
      await this.$auth.logout()
      await this.refreshUser()
      this.$router.push('/')
    }
  }
}
</script>

<style lang="scss">
#app {
  font-family: Avenir, Helvetica, Arial, sans-serif;
  -webkit-font-smoothing: antialiased;
  -moz-osx-font-smoothing: grayscale;
  text-align: center;
  color: #2c3e50;
}

#nav {
  padding: 30px;

  a {
    font-weight: bold;
    color: #2c3e50;

    &.router-link-exact-active {
      color: #42b983;
    }
  }
}
</style>

By now your app might look something like this:

Vue.js front-end app - work in progress

Note: Don't be confused by the text 'Pizza button and clicks counter here'. When building UIs, it's a good practice to leave such placeholders for components that are to be developed in the future.

In our case, this is where we will add the components responsible for the 'I love it' button and the counter later. They will show the number of votes per user.

<main>
  <div>
      Love pizza button and clicks counter here
  </div>
</main>

Authentication on the back end

By now, we have setup our front end to leverage the authentication service provided by Okta. But in order to have the whole picture ready to use, we need to do the same in our back-end app.

This is where we will be doing HTTP calls from, in order to communicate with the database. And, as you will see later, some of these calls will need to be authenticated in order to succeed.

Let's start again with installing some packages that will make our job easier. In your terminal, go to your backend directory and run the following:

dotnet add package Microsoft.AspNetCore.Authentication.JwtBearer --version 3.1.8
dotnet add package Microsoft.Extensions.Configuration --version 3.1.7

Then we need another package that will help us set up our database. We will use the SQLite database which is super easy to use in .NET Core setup.

While still in the backend folder, run:

dotnet add package Microsoft.EntityFrameworkCore.Sqlite --version 2.1.1

Once we're finished with the installations, make sure you got the full content of Startup.cs file (and if you didn't, do so now).

PizzaVotesApiService

OK everyone, we have set up both our front and back ends to support authentication. We have added SQLite as a database to be used for storing the users votes. And we have an initial version of our home screen.

Now it's time to implement a service on the front end that will allow us to consume our back end's API.

Great job so far! ?

Before being able to make HTTP calls from our front-end app to our back-end app, we need to install one more package in our Vue.js app. It's called axios and it gives us the ability to make XMLHttpRequests from the browser, which is exactly what we need.

Open your terminal, go to the frontend of your project, and run:

npm i axious

Then, in your IDE, go to the src folder of your front-end app, create a new .js file, and add the following inside it:

import Vue from 'vue'
import axios from 'axios'

const client = axios.create({
    baseURL: 'http://localhost:5000/api/pizzavotes',
    json: true
})

export default {
    async execute(method, resource, data) {
        const accessToken = await Vue.prototype.$auth.getAccessToken()
        return client({
            method,
            url: resource,
            data,
            headers: {
                Authorization: `Bearer ${accessToken}`
            }
        }).then(req => {
            return req.data
        })
    },
    getAll() {
        return this.execute('get', '/')
    },
    getById(id) {
        return this.execute('get', `/${id}`)
    },
    create(data) {
        return this.execute('post', '/', data)
    },
    update(id, data) {
        return this.execute('put', `/${id}`, data)
    },
}

I have named mine PizzaVotesApiService.js. We will stop with integrating the API for a while and will create another component that will hold the controls the users will use to interact with this API.

Dashboard Component

Say hello to our Dashboard.vue component.

This is where we will put the 'I love it' button and a small votes counter.

'I love it' button and votes counter

We'll also add a nice pizza image.

Pizza image

As well as a nice bar chart, showing the top X voters.

Top voters bar chart

You may copy and paste the full content of the file from my repo so we can continue with integrating the whole thing.

API Integration

I am going to use a small diagram to depict the data flow. As they say, "a picture is worth a thousand words:"

Data flow diagram

As you can see (I hope ?) from the diagram, when the user enters their votes, the data goes from the dashboard component through the API service we created for communicating with the back-end API. It then reaches the back-end controller that is actually making the HTTP calls.

Once the data is fetched, the service passes it back to our UI where we show it via our Vue.js components. As you will see, there is some additional logic that checks if the user is authenticated in order to know which calls to execute.

Here is the implementation of the controller itself:

using System.Collections.Generic;
using System.Threading.Tasks;
using Microsoft.AspNetCore.Authorization;
using Microsoft.AspNetCore.Mvc;
using Microsoft.EntityFrameworkCore;

namespace backend.Controllers
{
    [Route("api/[controller]")]
    [ApiController]
    public class PizzaVotesController : ControllerBase
    {
        private readonly ApplicationDbContext _dbContext;

        public PizzaVotesController(ApplicationDbContext dbContext)
        {
            _dbContext = dbContext;
        }

        // GET api/pizzavotes
        [HttpGet]
        public async Task<ActionResult<List<PizzaVotes>>> Get()
        {
            return await _dbContext.PizzaVotes.ToListAsync();
        }

        // GET api/pizzavotes/{email}
        [Authorize]
        [HttpGet("{id}")]
        public async Task<ActionResult<PizzaVotes>> Get(string id)
        {
            return await _dbContext.PizzaVotes.FindAsync(id);
        }

        // POST api/pizzavotes
        [Authorize]
        [HttpPost]
        public async Task Post(PizzaVotes model)
        {
            await _dbContext.AddAsync(model);
            await _dbContext.SaveChangesAsync();
        }

        // PUT api/pizzavotes/{email}
        [Authorize]
        [HttpPut("{id}")]
        public async Task<ActionResult> Put(string id, PizzaVotes model)
        {
            var exists = await _dbContext.PizzaVotes.AnyAsync(f => f.Id == id);
            if (!exists)
            {
                return NotFound();
            }

            _dbContext.PizzaVotes.Update(model);

            await _dbContext.SaveChangesAsync();

            return Ok();
        }
    }
}

Here we have four methods for executing four basic operations:

• get all records from the database

• get the records for one user (by their email address)

• create a new user record

• update an existing user's records.

You have probably noticed the [Authorize] clause above in three of the four methods. Those methods are going to require the user to be authenticated in order to execute.

We will leave the method GET api/pizzavotes for getting all records unauthorized on purpose. Since we would like to show the bar chart on the home screen to all users, we will need to be able to make this call, no matter if the user is authenticated or not.

Allow registration

Something to note: if you would like to have a 'Sign Up' on your login screen, you need to allow it from the Okta admin panel.

Once logged in, select from the menu Users->Registration:

Allow registration for new users

Finish the back end

In order for your back-end app to become fully functioning, please take a look at my repo here and add the missing files.

If you have followed along up to this point you should have the following files (except the test folder, as we are going to add it a bit later):

Back-end app structure

Finish the front end

In order to finalize the work on our front-end app, we will create two more components.

The first one will render the bar chart mentioned above, and the second one will display the email address of the user that is currently logged in.

In your IDE, go to frontend/src/components and create two files, named Username.vue and VotesChart.vue, respectively.

Username.vue is a very short and simple component that takes the user's email address as a prop and renders it. Here is its implementation:

<template>
  <div class="username">{{ username }}</div>
</template>

<script>
export default {
  props: { username: String },
}
</script>

<style lang="scss">
.username {
  color: rebeccapurple;
  display: flex;
  align-items: center;
  justify-content: center;
}

.username::before {
  content: "•";
}

.username::after {
  content: "•";
}
</style>

The only thing to notice here is that we are using SASS/SCSS for the component styles. That is possible because we chose that option in the beginning (when we were installing our Vue.js app).

For drawing the chart we will use a package called vue-chartsjs. Install it by running the following command from your frontend folder:

npm i vue-chartjs chart.js

Our component VotesChart.vue is going to be kind of wrapper for the bar chart component that comes from the vue-chartjs package.

We use it for getting the data from the parent component, Dashboard.vue, and processing it.

We sort the data array in order to display our top voters, sorted from the largest to the smallest number of votes. Then we pass it to the Bar chart component to visualize it.

Here is the full implementation:

<script>
import { Bar } from 'vue-chartjs'

const TOP_N_VOTERS_TO_SHOW_ON_CHART = 10

// Used to sort by votes value - from bigger to smaller (desc)
function sortByStartDate(nextUser, currentUser) {
  const nextVoteValue = nextUser.value
  const currentVoteValue = currentUser.value
  return currentVoteValue - nextVoteValue
}

export default {
  extends: Bar,
  props: { data: Array },

  watch: {
    data: async function (newVal) {
      const sortedVotes = Array.from(newVal).sort(sortByStartDate).slice(0, TOP_N_VOTERS_TO_SHOW_ON_CHART)
      this.labels = sortedVotes.map(user => user.id)
      this.values = sortedVotes.map(user => user.value)

      this.renderChart({
        labels: this.labels,
        datasets: [
          {
            label: 'Pizza Lovers',
            backgroundColor: '#f87979',
            data: this.values,
          }
        ]
      }, {
        scales: {
          yAxes: [{
            ticks: {
              stepSize: 1,
              min: 0,
              max: this.values[0]
            }
          }]
        }
      })
    }
  }
}
</script>

Note that there is a constant at the top of the file which will define how many top voters we would like to show on this chart. Currently it is set to 10, but you can amend it as you like.

Once you are ready with all the front-end stuff and want to run the app, you can do so by:

Going to the frontend folder and running:

npm run serve

Going to the backend folder and running:

dotnet run

Opening your browser and going to https://localhost:5001.

How to test our applications

So far we have built a modern and fully functioning single page application with a .NET Core back end and a SQLite database. That's a lot of work. Congrats! ✨

We easily could stop here and go have some cold ?.

But...

We are reasonable enough to know that if we don't test our apps, we can't guarantee that they will work as expected.

We also know that if we want to make our code testable, we should write in a well structured manner, keeping in mind the main principles of software design.

I hope I've convinced you to continue working through this tutorial. After all, the only thing left for us to do is to write some tests for both of our applications. So let's do it!

We will cover the functioning of our back end API with integration tests, and for our front end we will write both unit and integration tests.

Unit and integration tests

? Before going to the code, I would like to say a few words about these types of tests and answer some of most frequently asked questions.

You might be wondering, what are unit tests? What are integrations tests? Why do we need them? When should we use each of them?

Starting from the first question, a unit test is a piece of code that tests the functionality of an encapsulated module (meaning another piece). It's written in as a function or some kind of independent block of code.

They are good to have, because they give you quick development time feedback and keep the code safe from regressions when new features are being added.

Integration tests are useful when we need to test how multiple modules/units are working together. For example a REST API and a database interaction.

Depending on the size of the application we are working on, we might need only integration tests. But sometimes we need both integration and unit tests to bullet proof our code.

Ideally, we should have them both, as they are essential parts of the testing pyramid and are the cheapest to implement.

But in some cases, like for our back-end app, only integration tests are necessary to cover the functionality that is worth being tested. We have only several API methods for working with the database.

How to Create Our Back End Tests

This time we will start with creating our test solution. To do so, you need to do a few things.

First, install the xUnit library by running the following from your project root directory:

dotnet add package xUnit

Then go to your backend folder and create and empty folder called tests . Then inside that folder run:

dotnet new xunit -o PizzaVotes.Tests

Once that's done, open backend.csproj and add the following two lines to the <PropertyGroup> block:

<GenerateAssemblyInfo>false</GenerateAssemblyInfo>
<GenerateTargetFrameworkAttribute>false</GenerateTargetFrameworkAttribute>

Then go to your tests folder and install the following packages:

Microsoft.AspNetCore.Mvc
Microsoft.AspNetCore.Mvc.Core
Microsoft.AspNetCore.Diagnostics
Microsoft.AspNetCore.TestHost
Microsoft.Extensions.Configuration.Json
Microsoft.AspNetCore.Mvc.Testing

You do that by executing each of the following commands in your terminal app:

dotnet add package Microsoft.AspNetCore.Mvc --version 2.2.0
dotnet add package Microsoft.AspNetCore.Mvc.Core --version 2.2.5
dotnet add package Microsoft.AspNetCore.Diagnostics --version 2.2.0
dotnet add package Microsoft.AspNetCore.TestHost --version 3.1.8
dotnet add package Microsoft.AspNetCore.Mvc.Testing --version 3.1.8

After we have everything installed, we are ready to proceed to actually writing some tests.

As you may see here, except the tests themselves, I have added two more files which we need or are good to have when running the tests.

One of them is just a helper file with one method for dealing with serialized objects and getting the string content. The other is the fixture file, where we have configurations and settings for our test server and client.

And, of course, there's a file with our tests.

I am not going to paste the content of these files here, as this tutorial has become long enough already.

You can just copy them from my repository.

If you take a closer look at the tests, you might notice that we are testing only the first, not authenticated, call for a success response. The rest we are checking only for 401 HTTP response, which is Unautorized.

That's because only the first method is public, that is, it doesn't need authentication.

If we were to have the same tests for all methods, we would have needed to implement a middleware just to authorize our test app in front of Okta's authentication services.

And since the purpose of this tutorial is to learn a variety of things, we might say it's not worth doing.

Now the fun part: how to run the tests. It turns out to be super simple. Just go to your tests directory (where the tests.sln file is) from your terminal and run:

dotnet test

You should see something like this in your terminal (ignore the yellow warnings):

Running back-end tests

How to Create Our Front-end Tests

It's time to add some tests to our front end. Here we will do both unit and integration tests.

Unit tests
As I mentioned above, unit tests are suitable when we have a module or a component that doesn't have dependencies from the outside world.

Such components turn out to be our Username.vue and VotesChart.vue components.

They are representational components that receive the data they need to function properly via props. This means we can write our tests in the same manner: pass them the data they need and check whether the results of their execution are as expected.

Here's an important thing to mention. It's not that what is provided by the @vue/test-utils package (that comes from installing Vue.js), was not enough to test both components.

Rather, for educational purposes, I have decided to install and use the Vue Testing Library as well. That's why one of the components below is tested with @vue/test-utils, but the other is tested with @testing-library/vue.

Don't forget to install it before running the test:

npm i --save-dev @testing-library/vue

Again, to save space, I am not going to paste the component test's code here, but you can easily see it here and here.

Then in order to run the unit tests of your front-end app, go to the frontend folder and execute:

npm run test:unit

Integration test
This is probably more interesting for some of you.

If you remember the beginning of this tutorial when we installed our Vue.js app, for our e2e (or integartion) tests solution we selected Cypress.js.

This is a super easy-to-use tool that allows developers to write real e2e tests for their applications by giving them immediate feedback.

From personal experience I would say that working with Cypress is more of a pleasure than with other similar frameworks. If you have previous experience with frameworks like Nightwatch.js or Selenium, what you see below might be familiar to you.

Before running our tests with Cypress, we need to do some minor changes in its configuration.

Find the index file under the plugins folder and add the following line to the return statement in the end of the file:

  baseUrl: "https://localhost:5001"

Now update the content of the test.js under the specs folder as it's shown here.

Once you have it all done, you should be able to run your e2e tests via Cypress. You can do so by executing the following command while you're in your frontend directory:

npm run test:e2e

⚡Don't forget to start your back-end app before executing the e2e tests so that they work properly.

If you have followed along, after running the command above you should see something like this in your terminal:

Running e2e tests

And a new browser window will be opened by Cyrpess.js itself, where you can use the provided UI to see and run your tests.

Cypress.js UI

And when all tests pass, you are supposed to see a screen like this:

e2e tests pass successfully

Conclusion

In this tutorial, we have seen how to use one of the hottest technologies on the market, for both the front end and back end.

We've also learned how to combine them properly in order to build a small but fully functioning single page application with database support.

Finally, we also have written unit and integration tests for both ends.

I believe this kind of exercise is beneficial for both experienced and beginner readers, as it covers a lot of different stuff in a step-by-step manner. And you end up with a working example app if you've finished the entire process.

This tutorial ended up being much longer than I initially thought it would be. But if you have done it all, I admire you ?! And I hope it was pleasure for you reading it, as it was for me writing it.

? Thanks for reading! ?

Resources

You may find below the links that were useful to me in some way while writing this.

https://consultwithgriff.com/spas-with-vuejs-aspnetcore/
https://github.com/okta/okta-auth-dotnet
https://docs.microsoft.com/en-us/dotnet/core/testing/unit-testing-with-dotnet-test
https://docs.microsoft.com/en-us/dotnet/api/system.net.http.httpresponsemessage?view=netcore-3.1
https://vue-test-utils.vuejs.org/guides/#testing-key-mouse-and-other-dom-events
https://docs.cypress.io/guides/references/configuration.html#Options
https://docs.cypress.io/guides/tooling/visual-testing.html#Functional-vs-visual-testing
https://www.codingame.com/playgrounds/35462/creating-web-api-in-asp-net-core-2-0/part-3---integration-tests
https://testing-library.com/docs/vue-testing-library/intro
https://www.valentinog.com/blog/canvas/

✨ If you want to skip the reading and jump straight to the code, you will find it here. Also, I have deployed a live demo here.✨

Research

Recently I have decided to refurbish something old that I did 4 years ago for a project of mine. Here is how it looked:

Bingo Blower

At that time I chose to use a library called Paperjs. Back then this library let me build the closest thing to what I wanted to achieve.

As it turns out, there are many more JavaScript libraries today that let you do animations with or without physics.

Before making my final choice, which you will see below, I played around with Anime.js, Velocity.js, Popmotion, Three.js, GreenSock JS, Mo.js and Matter.js. All of them have pluses and minuses, and as with everything else, your choice between them depends on the specific needs you might have. I chose Matter.js.

Meet Matter.js

Matter.js is a 2d rigid body JavaScript physics engine. Sounds complex, but it's not. What this actually means is that this library contains all the stuff we need to create realistic 2d physics animations with JavaScript.

For detailed information on what Matter.js has to offer, you might check their documentation. In our case, we will take advantage mainly of the Body module and the features it has. Let's see how in the next section.

Balls and Tube

The "tube" component is easy. It's just a background image I am using to create an illusion that the balls are flying around inside a sphere-like glass object.

The interesting part is the code to create the animations and detect the collisions between the balls and the walls. But let's go step by step.

As I said, the "tube" is a background image I've added via the simple CSS background property. Let's see the balls themselves. For them I had two choices - try to draw circles in canvas and make them look like balls or use simple images. I chose the latter option, as I wanted to have a more realistic view of the balls.

So, with the help of a graphic processing program, a friend of mine created 75 images for me, one for each ball.

Having all the assets we need, we are now ready to go deeper and implement some physics with Matter.js.

Implement, test, implement, test

Before going into the animation itself, we need to mention few Matter.js specific things. When creating animations with this library, we need to define, at a minimum:

• Matter.Engine - this is the controller that manages updates to the simulation of the world.

• Matter.World - contains methods for creating and manipulating the world composite.

• Matter.Render - this module is a simple HTML5 canvas-based renderer for visualizing instances of Matter.Engine.

In our example we are also going to use:

• Matter.Bodies for creating the different parts of the scene (the balls, the invisible boundary circle).

• Matter.Body for applying forces to the bodies and thus creating a nice physics-based simulation of a blower.

• Matter.Runner to run the whole thing.

• Matter.Events gives us ability to have listeners for different events that could happen during the animation. In this specific case we use it for listening for the 'tick' event, which occurs on every render tick.
  In the event handler function we do our checking for when the balls collide with the walls and we apply the relevant forces to create a bounce effect.
  We postpone the listening for this event with a 3 second timeout, so we can have a more lotto-like effect. Imagine a sphere where the balls are starting to move when, let's say, a button is pressed.

Try and Play

In the beginning of this article I posted the link to the GitHub repository with the code and the assets in it. If you want to play more, you can easily check it out and try different modifications. You might want to play with the forces being applied, or the size of the balls, and so on.

There is plenty of room for experimenting when we talk about Physics. And it's always fun, especially when we add animations to the picture.

Conclusion

As it turns out, Matter.js is a great library for doing 2d realistic animations backed up by the laws of Physics. Of course, there are other options you might choose from, but as I said, this is a matter of choice and project needs.

I personally would recommend at least giving it a try and see for yourself. For someone with Flash experience or similar, Matter.js is definitely easy to start with. And if you are stubborn enough to keep trying different settings, you might achieve incredible results.

Resources

https://brm.io/matter-js/ - The website of the library
https://burakkanber.com/blog/modeling-physics-in-javascript-introduction/ - interesting and well explained articles related to physics in JavaScript
https://spicyyoghurt.com/tutorials/html5-javascript-game-development/collision-detection-physics/ - collisions detection tutorial
https://codepen.io/AlexRA96/full/egaxVV - bouncing ball example
https://codepen.io/Shokeen/pen/WjKmMG?editors=1010 - codepen example with applying forces
https://code.tutsplus.com/tutorials/getting-started-with-matterjs-body-module--cms-28835 - beginner tutorial to get you started with Matter.js
https://codepen.io/jh3y/pen/gOPmMyO?editors=0110 - another cool example with falling bears
https://codepen.io/danielgivens/pen/geKrRx - even cooler example with a circle clock and particles inside
https://codepen.io/dotcli/pen/NEXrQe - another example of circle bounds and particles (socks!) inside

The application I built is simple enough. When someone loads the app, they are prompted to enter their username and begin chatting:

Welcome Screen

The application ultimately runs on Node with help from NW.js (previously known as node-webkit). NW.js is advantageous because it enables us to code cross-platform desktop applications using our favorite web technologies. For this application, I chose to use React and Redux.

The back-end logic - from sending and receiving messages in real-time to populating what I call the "participant list" - is powered by CometChat. You will learn more about CometChat as you read on.

This post is not intended to be a walkthrough. Although I will be explaining the technical components of this application, my main ambition is to help you think through a solution from beginning to end. Hopefully, when you finish this post you'll be a slightly better developer and consider CometChat for your growing tool belt.

Just want the example code?

You may see the source code here. There is also a detailed README, where you will find all the information you need to install, run and test the app.

Because the desktop app is built using web technologies, it is entirely possible to run it in your browser. Towards the end of this post, I will show you how to deploy the app on Netlify.

Planning

In this section we have to decide what components will we need to build. What functionality will they have? In other words, what are the questions we need to answer, to plan the building process?

Let’s step back for a while and think. Try asking yourself the questions who will take us to the structure we need for our app.

Below I am going to lay out my questions and the answers. This is the process of the actual building the structure of the app, but in your head first. Keep in mind that it happens very often such that when answering a question new questions appear. This was the case with me as well.

Questions:

• What am I doing? ?

• What kind of app am I going to be building?

• What are the most common components, such an app needs to have?

• How do the app’s components interact with each other?

• What level of completion am I aiming for — (demo apps are not supposed to be fully featured)?

Answers (following the order of the questions):

• This is the most neglected question that many people forget to think about. When one can step aside first and give a clear answer to this question, his path for future developments becomes settled. In my specific case the answer I got sounds something like this — “I am thinking about building a chat app. This app should serve as a tutorial demo app. It will have to provide basic functionality for ‘having a chat’ by using CometChat API. It should run on a desktop”. The styling and specific details about what goes where will come later in the process.

• A chat app that will run on desktop and serve as a demo for this tutorial.

• To give a proper answer to this question, a non-familiar person would have to do some research first. Take a look at real-world chat applications. Make notes of what features they have. How are they put them in place, how do they interact between them and with the users of the app. In my case, I had some previous experience and got, more or less, the idea of what I need.

• The interaction between the components would be pretty straight forward. The user should be able to use the main component that is a text input and a button to send messages. And a sidebar component to see the other chat participants.

• The demo app should provide basic chat functionality — send and receive real-time messages. And be able to run on a desktop (without a browser).

Features

I have decided to implement the following features to the demo app:

• Send with Enter key

• A sidebar with names and last active time

• Welcome screen with input and validation with error messages

• Chat area with auto-scroll to bottom

• Chat message and time of sending.

Front End — React

We are going to use React to build our user interface. Below, I am going to list the components I have created and a short explanation about each of them:

• ChatPane — this is the main container-like component that contains the Participants and Conversation components and passes the data they need to visualize.

• Conversation — this is the component responsible for typing and sending chat messages.

• Footer — displays a simple footer message, containing the app name and version, as defined in package.json file.

• Header — header component holding the application menu bar.

• MenuAppBar — application menu bar component, simulating how a real menu bar would look like. The hamburger menu on the left and the profile dropdown menu on the right are fake — clickable, but not functional.

• Messages — a container component, holding a message itself — it has the name of the sender, the message content and the time of sending.

• Participants — this component shows the name of a chat member and the time when he joined.

• Welcome — this component is responsible for displaying the login page — the starting point of our app, where we have logic related to checking for certain allowed usernames and storing them to the local storage for later use. I also implemented basic error handling logic, which shows an error when the selected username is not correct, as per CometChat API (in this specific case for our demo) registered usernames — superhero1, superhero2 and so on till 5.

Here a visual representation of the app components:

Visual Components

State Management — Redux

Every modern application these days has a state. Place in the memory where the application is storing certain data for later use. For our application state management, we use Redux. Of course, for a simple app like this, we could go without using Redux at all. But, from the learning point of view (after all we all do this for learning new stuff, right?), I think it would be nice to see the whole cycle of sending a request to an API, going through a middleware (redux-thunks) and getting the response recorded to the state. And we will manage this state by using Redux.

How it works

The main building blocks in a Redux app are called reducers — small functions used for managing the state. Simply said, what they do is accepting the old state object as input and, depending on certain actions (which are also passed in the same input), returning new state object. The new state could be changed in full or just partially.

In our app, we have three simple reducers, which are responsible for those parts of the state, responsible for the users’ list, the login process and sending/receiving messages. All of them can be seen in /src/reducers folder, along with a file containing the initial state of our app.

Redux, as state management library, can be used with any other UI framework, practically every app that needs to have a state can benefit from using Redux. If you want to go deeper, start from their website and follow along.

Side Effects Handling — Redux Thunks

One of the best known approaches for managing side effects in a redux app is called redux-think. This is what we use in our application as well. If you want to learn more details about redux thunks and how to use them, I recommend their website as a starting point and then build a small application, like this one for example :).

In our project, in /src/actions folder, is where I put the thunks used in the demo application. And in /store directory is where the configurations for the redux store live.

Make it desktop — NW.js

The part of our application that makes it possible for our app to run on desktop is taken care of by a library called NW.js. Remember that we are building a desktop application. Exactly the desktop part is going to be implemented via NW.js. Similar to Electron, another library for building desktop applications, NW.js provides a way to the developers to use their web skills to build applications that can run on a desktop. This means you can still use your JavaScript/React skills when building an app and then leverage the power of the desktop operating system via Nw.js APIs. In other words, Nw.js gives you the ability to make a skeleton app, which can be “filled” with your UI, no matter what library you have used to create it. And the best thing is that such an app has access to Node.js/NW.js APIs and the DOM in the same JavaScript context.

Since we mentioned the other big player in the field of building cross-platform desktop apps, let me give you a brief comparison between the two.

Nw.js vs Electron

Entry of Application

• In NW.js the main entry point of an application is a web page or a JS script. You specify an HTML or js file in the package.json and it is opened in a browser window as the application's main window (in case of an HTML entrypoint) or the script is executed.

• In Electron, the entry point is a JavaScript script.

Build System

• Nw.js uses Chromium

• Electron uses libchromiumcontent to access Chromium's Content API. libchromiumcontent is a single shared library that includes the Chromium Content module and all of its dependencies.

Node Integration

• In NW.js, the Node integration in web pages requires patching Chromium to work.

• In Electron uses a different way to integrate the libuv loop with each platform's message loop to avoid hacking Chromium.

Multi-context

• Because of how NW.js was implemented concepts of Node context and web context were invented.

• By using the multi-context feature of Node, Electron doesn't introduce a new JavaScript context in web pages.

Chat — CometChat

The usage of CometChat API is pretty straight-forward. It’s a RESTFull API, on which is built another layer of abstraction - CometChat SDK. It allows us to call directly exposed methods for different actions we might want to perform, such as send. Here an example of such a method:

return CometChat.sendMessage(textMessage).then(    
  message => {      
    console.log("Message sent successfully:", message);      
    return message;
  }, 
  error => {      
    console.log("Message sending failed with error:", error);    
  }
);

You may see all the Chat API logic in /src/chat-api folder. There you will also see the mocks I created, which allow us to test our app without real connection to the API.

Improvements

Every project deserves some thoughts after finishing the first phase. One part of this thought process would be dedicated to how it went, what was good and bad, and what might be done better. And one part would be dedicated to thinking about possible improvements. Here are a few ideas for our case. If someone goes to this direction and implement any of these for real, please do not forget to let me know :)

• Waiting animation for when loading the chat history and the user list

• Option for skipping the login screen, if already logged

• Option for sending invitations to new users

• Option for seeing the status of a message — sent, received, read

• Emojis support

• Inline links/images/video support, such that the user can see them interpreted — playing video, rendered image or web page to which a link is pointing. I have added these as issues in my GitHub, in case anyone wants to take a look.

Deploy on Netlify

To deploy your application to Netlify platform you need to create an account first. Go to their website and sign up for new account. After that go ahead and login. While still under Sites section, you should see a button for deploying new site from Git.

Click it and follow the steps to create a new site for deployment from your GitHub repositories. Your process should be similar to what is shown in the image below.

Now, the last step before having your app deployed is to make sure you have the correct build commands and environment variables in place. To do that, after you create your site for deployment, go to Build & deploy settings screen and enter the following (don’t forget to use your repo URL):

Under Environment section is where you need to enter the environment variables as defined in your .env file. Here is how it looks mine:

Note: I have erased the values as this is supposed to be private info and you should not share yours as well.

That should be enough for you to have your app deployed on Netlify. Keep in mind the Deploys default settings are set to ‘auto publishing’, which means that it will trigger a deploy on each commit you do to the master branch in your repo. This is the place where you can trigger a deploy manually as well. This is how my Deploys screen looks like:

Conclusion

In this tutorial, we saw how can we leverage our web development skills to create applications that can run on a desktop. What we built is a demo application, that lacks a lot of a fully-featured-production-ready app features, but when one wants to learn and share, this would do the job. If you would like to deepen your knowledge in this direction, I would recommend you to try to improve it, by implementing features that are more likely to be seen in a real desktop application.

There are plenty of opportunities to explore out there, I hope this tutorial entertained you enough to keep your flame of curiosity burning even more.

? Thanks for reading! ?

Notes:

• In order to use Nw.js DevTools you need to install the SDK build —  https://nwjs.io/downloads/ - version 0.38.2 or higher.

Resources:

• Q: What is a ‘thunk’? A: The sound your head makes when you first hear about redux-thunk. Ok sorry, that was awful. But…daveceddia.com

• [book] Cross-Platform Desktop Applications: Using Node, Electron, and NW.js

• [book] Cross-platform Desktop Application Development: Electron, Node, NW.js, and React

• Thunk middleware for Redux

• https://reactjs.org/docs/hooks-reference.html#useref

What you are going to see below was supposed to be part of my solution to an exercise given in a coding challenge. It was several months ago, and I had signed in for it. Due to unforeseen factors, I hadn't finished it. Now, after that time and the challenge is finished, I can share it here.

This is not going to be a step-by-step tutorial. Rather, it'll be a quick review of how can we use frameworks like React and Popmotion.io along with an algorithm. And then create a nice visualization of that very same algorithm. Somehow it feels nice! ?

The so called Pancakes Sorting Algorithm is a famous (or not?) sorting algorithm that you can read more about on the internet, if you're interested. Its nature is out of the scope of this article. Here we only see it in action with nice animations, thanks to Popmotion.io.

Here is the live demo you can play with. There are two text inputs and two buttons. In the first input you enter the time interval which will be used for each animation round, that is how fast each pancake will be sorted. It's in milliseconds, which means if you enter the value 1000, the animation will execute for roughly 1 second.

The second input is used to define how many pancakes you want to see sorting. The value there must be between 2 and 50. The buttons are self-explanatory enough. One is for starting the sorting animation, the other one is for resetting it.

And here is where you can find the source code for the demo app. Feel free to check it out and take a closer look. You might try to amend the animations I did. I would be more than interested to see your versions. :)

That was all. Nice and short, perfect for the summer! ☀️ ?

? Thanks for reading! ?

TL;DR

This tutorial explains what a service worker is and how to use it, in JavaScript. There is a code example at the end of it. If you want to skip the reading, here is the Git repo and here you may see a live demo.

The Theory

Let’s see first what a w_orker_ is this ? and what s_ervice_ can we use it for ?.

The service worker is a simple script. It's JavaScript code, that your browser runs in the background, separate from a web page.

It’s very convenient to use service workers for features that don’t need a web page or user interaction. One of the most common uses is intercepting and handling network requests. This includes managing a cache of responses.

The following is a simple example of how to include a service worker in your application.

Usually, in the entry point of your app, you add this code:

if ('serviceWorker' in navigator) {  
    window.addEventListener('load', function() {
        navigator.serviceWorker.register('/service-worker.js');  
    });
}

This way of using service workers is a little bit improved than the basic one. The basic method involves directly calling the register() method inside the if statement. In this case, we use the window load event to register the service worker after the page has finished loading. After doing this, you need to add your service worker code in the service-worker.js file. At this point, you might want to take a look at my service worker file.

All major browsers support Service Workers now, and you can start using them right away.

The Example

Enough theory, let’s build a real example app that will leverage the service workers feature.

Let’s imagine we are building an app that needs to load a big chunk of data. It could be, for example, a nice, big full-screen image we display on the front page. Or it could be a big video clip we have to wait to load. This is an ideal use case for a service worker to shine. Let’s see how. ?

In our specific case, we will use the clock time to show the benefit of using service workers. What I mean is, that we will build a simple app, showing the time. It will have a nice, big button for fetching a nice, big image. And it will provide the user with an option to choose to use or not a service worker.

Here is a screenshot of how it looks:

What this app demonstrates is, that when fetching the image (by clicking the button, wow!) with an active service worker — we don’t get blocked UI (user interface, i.e. fields, buttons, ?). If you choose not to use the service worker, you will get a frozen UI for a certain period of time. When the work completes and the main thread frees itself, it will unfreeze the UI.

If you don’t want to clone and run the code yourself, jump straight to the live demo.

Conclusion

This demo of service workers in action shows us the advantage we get from using them. Especially when you are trying to build responsive and robust JavaScript applications. No user wants to end up in a frozen page for an unknown time, as no developer should want that for his application’s users. Keeping in mind the above, service workers are a must now. And we should not neglect them.

? Thanks for reading! ?