DEV Community: Eduardo Motta de Moraes

User Authentication with JavaScript and Express: A Practical Guide

Eduardo Motta de Moraes — Tue, 18 Jul 2023 15:26:48 +0000

Authentication is a critical aspect of building secure web applications that require user identification and access control. It ensures that users can securely access their accounts and protect sensitive information.

There are many ways to achieve that.

In this post we’re going to go through a practical example using Javascript and the popular Express framework, using a simple username/password mechanism (aka Local Strategy).

We’ll delve into practical examples and cover essential concepts, including user verification, session management, and authentication strategies

The examples use EJS, which is a templating package, but the same logic can be used in an API.

What is authentication

Authentication is the process of verifying the identity of a user, usually involving a few common steps:

(1) the user provides their credentials;

(2) the credentials are verified by comparing them against stored information;

(3) if the credentials are valid, a session or token is created to allow access to protected resources; and

(4) once authenticated, the application can determine the user’s access privileges and permissions.

Using a username and a password is the most common mechanism of authentication. There are alternatives like Single Sign-on (SSO), Multi-factor Authentication (MFA), and OAuth, which we won’t go into in this post.

Spinning up an application

To better understand the concepts above, we’re going to be building a simple app using Express.

We’ll begin by spinning up the a project called “member-only” with express-generator using EJS to create templates:

$ npm install -g express-generator
$ express members-only --view ejs

Next we can install the packages we’re going to use. We’re also installing apps that are not related to authentication, but that are necessary in the app. I’ll explain what each one does as we use them.

$ npm i bcrypt compression connect-mongo cookie-parser dotenv express-asyn-handler express-session express-validator helmet mongoose nodemon passport passport-local

To run the app in dev mode and have it reload every time any changes are saved, add these scripts to package.json:

"scripts": {
    "start": "node ./bin/www",
    "watch": "nodemon ./bin/www",
    "dev": "DEBUG=inventory-app:* npm run watch"
},

We’ll be using environment variables, so create a .env file in the root folder where you can save them in the format of VARIABLE_NAME=value.

Database and models

We’ll use MongoDB to store app and sessions data. You can create one on the cloud for free on Atlas Database. Just follow the instructions they provide, as they’re pretty straight forward.

Once you create the database, you can create a collection called “members_only”. In the main Database page, click on “Connect” and you’ll be presented with a few options. Choose “Drivers” and select Node.js 5.5 or later.

Copy the Connection String and paste it to your .env file on a variable called MONGO_DB, adding the name of the collection after the domain:

MONGO_DB=mongodb+srv://<username>:<password>@top-test.yu3rgpr.mongodb.net/members_only?retryWrites=true&w=majority

In your project, create a file called database.js and add the following code:

// database.js

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

mongoose.set("strictQuery", false);
const mongoDB = process.env.MONGO_DB;

async function main() {
  await mongoose.connect(mongoDB);
}

module.exports = main;

require(“dotenv”).config() is required to use the environment variables using process.env.[VARIABLE_NAME]. The rest of the code is for connecting to the database. We export it so it can be called in app.js:

// app.js

const useDatabase = require("./database");
useDatabase().catch((err) => console.error(err));

We can then define our models like so:

// models/users.js

const mongoose = require("mongoose");
const Schema = mongoose.Schema;

const UserSchema = new Schema({
  first_name: { type: String, required: true },
  last_name: { type: String, required: true },
  email: { type: String, required: true },
  hashed_password: { type: String, required: true },
  roles: [{ type: String, enum: ["admin", "member"] }],
  created_at: { type: Date, required: true },
});

UserSchema.virtual("full_name").get(function () {
  return this.first_name + " " + this.last_name;
});

module.exports = mongoose.model("User", UserSchema);

Notice we’re not storing the user’s actual password, but a hashed password. We’ll talk more about this in the next part.

Routes and controllers

We'll define the routes in a separate file, and then call controller functions that will handle the logic for each of them:

// routes/index.js

const express = require("express");
const router = express.Router();

const controller = require("../controller");

router.get("/", controller.index_get);

// controller.js

const asyncHandler = require("express-async-handler");
const { body, validationResult } = require("express-validator");
const bcrypt = require("bcrypt");
const passport = require("./auth");

const logger = require("./logger");
const MessageSchema = require("./models/messages");

exports.index_get = asyncHandler(async function (req, res, next) {
  logger.info(`${req.method} ${req.originalUrl} ${res.statusCode}}`);

  const messages = await MessageSchema.find({ deleted: false })
    .sort({ created_at: -1 })
    .populate("user")
    .exec();

  res.render("index", {
    title: "Members Only",
    user: res.locals.currentUser,
    isUserLoggedIn: !!res.locals.currentUser,
    messages,
  });
});

In short, we're defining a function index_get that queries the database to get all the messages, then renders an EJS view with the data. We’re using asyncHandler because it simplifies error handling.

To see how the other endpoints are handled, see the Github repo.

Authentication

We’ll use Passport to handle authentication and sessions, and bcrypt to handle password encryption.

Creating a user

We’ll create users when they submit a form with the appropriate information. In order to do that, we need to add the following middleware function in app.js, as it will allow us to access the form data in req.body:

// app.js

app.use(express.urlencoded({ extended: false }));

After that we can define controller functions user_create_get and user_create_post that will be called by the appropriate routes.

user_create_get will render the form using EJS, if the user is not already logged in:

exports.user_create_get = asyncHandler(function (req, res, next) {
  logger.info(`${req.method} ${req.originalUrl} ${res.statusCode}}`);

  if (res.locals.currentUser) {
    res.redirect("/");
    return;
  }

  logger.info("Rendering signup form");

  res.render("signup", {
    title: "Sign Up",
    user: null,
    isUserLoggedIn: false,
    newUser: {
      first_name: "",
      last_name: "",
      email: "",
    },
    errors: [],
  });
});

user_create_post will handle the data sent by the form, use this data to create a user with a hashed password, then redirect the user to the login page. You can do something similar with minor adjustments if you’re building an API.

Let’s take a look at the the code and then break it down:

exports.user_create_post = [
  body("first_name", "First name must not be empty.")
    .trim()
    .isLength({ min: 1 })
    .escape(),
  body("last_name", "Last name must not be empty.")
    .trim()
    .isLength({ min: 1 })
    .escape(),
  body("email", "Email must not be empty.")
    .trim()
    .isLength({ min: 1 })
    .escape(),
  body("email").custom(async (value) => {
    value = value.toLowerCase();
    const emailExists = await UserSchema.exists({ email: value });
    if (emailExists) {
      throw new Error("Email already in use.");
    }
    return true;
  }),
  body("password", "Password must not be empty.")
    .trim()
    .isLength({ min: 1 })
    .escape(),
  body("confirmPassword", "Confirm password must not be empty.")
    .trim()
    .isLength({ min: 1 })
    .escape(),
  body("confirmPassword").custom((value, { req }) => {
    if (value !== req.body.password) {
      throw new Error("Password confirmation does not match password.");
    }
    return true;
  }),

  asyncHandler(async function (req, res, next) {
    logger.info(`${req.method} ${req.originalUrl} ${res.statusCode}}`);

    const errors = validationResult(req);

    const { first_name, last_name, email, password } = req.body;

    if (!errors.isEmpty()) {
      res.render("signup", {
        title: "Sign Up",
        user: null,
        isUserLoggedIn: false,
        newUser: {
          first_name,
          last_name,
          email,
        },
        errors: errors.array(),
      });
      return;
    }

    try {
      bcrypt.hash(password, 10, async (err, hashed_password) => {
        if (err) {
          return next(err);
        }

        const user = new UserSchema({
          first_name,
          last_name,
          email,
          hashed_password,
          roles: [],
          created_at: new Date(),
        });

        await user.save();
        res.redirect("/login?signup=success");
      });
    } catch (err) {
      next(err);
    }
  }),
];

We need to somehow validate the data we’re getting from the user. We can do that by using the express-validator package, which provides us the functions body and validationResult.

body is used for the fields validation with requirements such as minimum length and options like trimming and escaping the input. It is a callback function itself, so we pass it in an array to the router, along with the endpoint controller (inside the asyncHandler).

We can then get any errors inside the endpoint function using validationResult(req). If there are any errors, we’ll just render the sign up page again.

When the inputs are valid, we can actually create the user. We’re using bcrpyt for that, as it allows us to create a hashed password with the user inputted password. This ensures that we never need to store the actual password, increasing security.

We need to call bcrypt.hash with a callback function that will take as arguments the actual password, a cost factor, and a callback function.

The cost factor indicates the computational cost of the hashing algorithm (the higher the number, the slower the process is, but the safer the encryption becomes). This process also involves salting, making the hashes unique even if two users have the same password.

The callback function takes a possible error and a hashed_password which we can then use to create the user in the database.

Authentication strategies

Passport uses modules called “strategies” that encapsulate logic and configuration required to authenticate users. Each strategy corresponds to a different authentication method, such as local username/password, OAuth, OIDC, or JWT.

For this example, we’ll be using the Local Strategy.

Setting it up is as simple as passing a callback function to passport. We’re doing this in a separate file auth.js:

// auth.js

const passport = require("passport");
const LocalStrategy = require("passport-local").Strategy;
const bcrypt = require("bcrypt");

const UserSchema = require("./models/users");

passport.use(
  new LocalStrategy(
    {
      usernameField: "email",
      passwordField: "password",
    },
    async (username, password, done) => {
      try {
        const user = await UserSchema.findOne({ email: username });

        if (!user) {
          return done(null, false, { message: "Invalid email or password." });
        }

        const isMatch = await bcrypt.compare(password, user.hashed_password);

        if (!isMatch) {
          return done(null, false, { message: "Invalid email or password." });
        }

        return done(null, user);
      } catch (err) {
        return done(err);
      }
    }
  )
);

We import passport and call the use method, passing as its first argument an optional object with custom names for the usernameField and passwordField. If we don’t pass this object, the field names will default to username as password.

The second argument is a callback function with the logic for the strategy itself. In it we’re passing the username and password, which are used to query the database, fetch a user and compare the stored password.

We use bcrypt for this last step, as we’re not actually storing the password itself, but a hash value. The idea is bcrypt will take the provided password, generate a hash using the same cost factor and salt as before, and compare this hash with the value we have stored in the database. If they’re the same, the authentication is successful.

The callback function also takes a done argument, which is a function we need to call once the authentication flow is complete, either with no error and the user object, or with an error.

In this same file we’re also setting up serialization and deserialization, so passport can manage sessions more efficiently by storing only the user id instead of the whole user object.

// auth.js

passport.serializeUser((user, done) => done(null, user.id));

passport.deserializeUser(async (id, done) => {
  try {
    const user = await UserSchema.findById(id);
    done(null, user);
  } catch (err) {
    done(err);
  }
});

Finally, we export passport so it can be used in app.js

// auth.js

module.exports = passport;

// app.js

app.use(passport.initialize());

Once the user is authenticated, you can access it in the request object. To make your life easier, you can create a custom middleware function to store the user information in the response object, so you can access it in any other subsequent middleware or endpoint functions.

// app.js

app.use(function (req, res, next) {
  res.locals.currentUser = req.user;
  next();
});

This must be called after initializing passport, but before using any routes.

Sessions

After the authentication process is completed, we need to persist this information so it isn't lost everytime the page is refreshed.

Storing it in the application itself isn't ideal. If eventually we need to distribute processing by running it in more than one server, there would be no way of sharing the session information. If the server crashes, the session data would be lost and the users would be unexpectedly logged out. Lastly, it would consume server memory and disk space.

Instead, we should either send the session data back to the client, or store it in a database.

We'll be using mongoSession to store our sessions in a database. Create a file mongoSession.js and add the necessary configuration:

// mongoSession.js

const MongoStore = require("connect-mongo");

const sessionStore = MongoStore.create({
  mongoUrl: process.env.MONGO_DB,
  collectionName: "sessions",
  autoRemove: "interval",
  autoRemoveInterval: 60, // In minutes
});

exports.config = {
  secret: process.env.SESSION_SECRET,
  resave: false,
  saveUninitialized: false,
  store: sessionStore,
};

mongoUrl is the same Connection String we already have in our .env file. You may set option like autoRemove if you don’t want to persist session data indefinitely.

The secret is a string used to sign session information. It can be any string you want, but it’s recommended that’s a long, randomly generated, unique string. Save it as an environment variable to avoid sharing it.

Import the configuration and add it to app.js:

// app.js

app.use(session(mongoSession.config));
// ...
app.use(passport.session());

Once that’s done, everytime a user is logged in the session information will be saved in your database, looking something like this:

{
  _id: "8GcyUWw67tb44h9vdWQKSxIcPgypIeUx",
  expires: "2023-07-21T10:53:21.594+00:00",
  session: {
    cookie: { originalMaxAge: null, expires: null, httpOnly: true, path: "/" },
    passport: { user: "64a4a013cefdc295346ca0c3" },
  },
}

Final words

Understanding authentication is vital for building secure applications with user identification and access control. In this post, we explored a practical example using JavaScript and Express, focusing on the Local Strategy for username/password authentication. Here’s a summary:

Authentication involves verifying user identity, checking credentials, and granting access privileges.
We built an Express app, used EJS templates, and implemented routes and controllers.
Passport and bcrypt were used for authentication and password hashing.
Sessions were managed using mongoSession and stored in a MongoDB database.
The app followed a stateless approach, ensuring scalability and security.

By grasping authentication concepts and implementing secure practices, you can create robust applications that protect user data and provide a seamless user experience.

[Cover photo by FLY:D]

Pandas Code Testing 101: A Beginner’s Guide for Python Developers

Eduardo Motta de Moraes — Wed, 08 Mar 2023 15:53:11 +0000

Testing is a crucial step in software development. Every programming language has a myriad of tools to make our lives easier when testing our code — and Python is no different.

However, when using the Pandas library I've noticed that testing isn’t as common.

This could be because it’s harder than testing regular Python code, or because Pandas is usually used by professionals who aren’t necessarily programmers.

Regardless of the circumstances, the fact remains that testing plays a crucial role and should not be overlooked.

In this post I will share some of my knowledge about the topic, including what tools to use, general strategies for testing, and how to test code that uses Pandas.

Using Pytest

There are other libraries out there, but I’ve found Pytest to be the most simple and yet robust of them.

Other testing tools usually require defining classes with methods for every test, which makes this a bit more cumbersome. Pytest, on the other hand, lets us define simple and compact functions instead.

To use it, we must first install it:

pip install pytest

As an example, say we have the following function that we want to test, inside a file called “operations.py”:

# operations.py
def sum_a_and_b(a, b):
  return a + b

To test it with Pytest, we create a file that either starts or ends with “test” (so “test_operations.py” or “operations_test.py”). Inside this file we define a function to test our sum_a_and_b function with an assertion:

# test_operations.py
from operations import sum_a_and_b

def test_sum():
  result = sum_a_and_b(1, 2)

  assert result == 3

We run the tests by typing pytest in the terminal:

(venv) pandas-testing % pytest
========================== test session starts ==========================
platform darwin -- Python 3.9.6, pytest-6.2.5, py-1.10.0, pluggy-1.0.0
rootdir: /Users/eduardo/development/tutorials/pandas-testing
collected 1 item                                                        

test_operations.py .                                              [100%]

=========================== 1 passed in 0.01s ===========================

Writing good tests

Beyond the happy path

Of course the simple test above doesn’t ensure our function works correctly 100% of the time. For instance, it doesn’t test the behavior of the function when we pass strings as arguments.

To write good tests, we should start by testing the “happy paths” (i.e. the normal expected behavior), but we should always remember to also test the edge cases.

Testing principles

For unit tests, it’s a good rule of thumb to remember that tests should always follow the common “arrange / act / assert” structure. That is to say, we should:

arrange everything that is needed for the test, like creating any necessary data or special settings, preparing an in-memory database, or mocking API calls;
act on the function or method to be tested by calling it;
assert the expected outcome.

If we testing something that relies on user interaction, we can also think of it in terms of “given / when / then”, i.e.:

given what is needed to run the test;
when some interaction happens;
then we should expect a certain outcome.

Take your time naming everything correctly

Just like when we’re writing any other code, naming things correctly when testing is highly recommended.

Our test functions should be descriptive of what is being tested. The same goes for for any variables used inside it.

For instance, our test_sum example above could have been written like this:

from operations import s

def test1():
  x = s(1, 2)

  assert x == 3

It’s the same test and it achieves the same result.

But even for this simple example, it’s harder to understand what is actually being tested. For more complex test cases, you can imagine it would quickly become unintelligible.

Testing Pandas

So how do we apply this to Pandas?

If we have functions or methods that output DataFrames, we will want to ensure that the results are as expected. For example, say we have a function double_dataframe that multiplies every value of a DataFrame by two:

# pandas_example.py
import pandas as pd

def double_dataframe(df):
    return df * 2

To test it, we may want to use an assertion like we did in our previous example. We define an expected result and compare it with the actual result using an equality operator (==):

import pandas as pd
from pandas_example import double_dataframe


def test_double_dataframe():
    # arrange
    input_df = pd.DataFrame({'a': [1, 2, 3], 'b': [4, 5, 6]})
    # act
    result_df = double_dataframe(input_df)
    # assert
    expected_df = pd.DataFrame({'a': [2, 4, 6], 'b': [8, 10, 12]})
    assert result_df == expected_df

But that does not make sense in Pandas, as a DataFrame is a collection of vectorized values. Pandas won’t understand what we mean by that and will return an error: ValueError: The truth value of a DataFrame is ambiguous. Use a.empty, a.bool(), a.item(), a.any() or a.all().

Using the Pandas test functions

Instead we can use the Pandas test methods: assert_frame_equal, assert_series_equal, and assert_index_equal. (In many cases the Pytest assertions will still be useful and necessary, so we should still use them when appropriate.)

assert_frame_equal

We can rewrite the example above to correctly compare the result and expected DataFrames with assert_frame_equal:

import pandas as pd
from pandas.testing import assert_frame_equal
from pandas_example import double_dataframe


def test_double_dataframe():
    input_df = pd.DataFrame({'a': [1, 2, 3], 'b': [4, 5, 6]})

    result_df = double_dataframe(input_df)

    expected_df = pd.DataFrame({'a': [2, 4, 6], 'b': [8, 10, 12]})
    assert_frame_equal(result_df, expected_df)

And this time the test will succeed. assert_frame_equal will compare two DataFrames and output any differences.

We can allow varying the strictness of the equality checks by using additional parameters like check_dtype, check_index_type, check_exact… and many more that you can find in the Pandas documentation. For instance, if we want to compare values but we don’t care if they’re float or int, we can set check_dtype = false:

import pandas as pd
from pandas.testing import assert_frame_equal
from pandas_example import double_dataframe


def test_double_dataframe():
    input_df = pd.DataFrame({'a': [1.0, 2.0, 3.0], 'b': [4, 5, 6]})

    result_df = double_dataframe(input_df)

    expected_df = pd.DataFrame({'a': [2, 4, 6], 'b': [8, 10, 12]})
    assert_frame_equal(result_df, expected_df, check_dtype = False)

assert_series_equal

assert_series_equal works in a similar way, but for Series.

Say we have the following function that doubles the values of a single column in a DataFrame, and returns it as a Series:

import pandas as pd

def double_column(df, col_name):
    return df.loc[:, col_name] * 2

We can test it with assert_series_equal:

def test_double_column():
    input_df = pd.DataFrame({'a': [1, 2, 3], 'b': [4, 5, 6]})

    result_series = double_column(input_df, 'a')

    expected_series = pd.Series([2, 4, 6], name='a')
    assert_series_equal(result_series, expected_series)

assert_index_equal

assert_index_equal can be used when we need to make sure the indexes of two DataFrames are the same.

For example, if we have a function get_top_n_countries that takes a DataFrame containing information on countries and returns the top n countries based on a specified column. The resulting DataFrame uses the country names as the index.

import pandas as pd

def get_top_n_countries(df, column_name, n):
    sorted_df = df.sort_values(column_name, ascending=False)
    top_n_countries = sorted_df.head(n)
    top_n_countries.set_index('country', inplace=True)
    return top_n_countries

We can test it with assert_index_equal:

import pandas as pd
from pandas.testing import assert_index_equal
from pandas_example import get_top_n_countries

def test_get_top_n_countries():
    data = {'country': ['USA', 'China', 'Japan', 'Germany', 'UK'],
            'population': [328, 1393, 126, 83, 66]}
    df = pd.DataFrame(data)

    top_3_countries = get_top_n_countries(df, 'population', 3)

    expected_index = pd.Index(['China', 'USA', 'Japan'], name='country')
    assert_index_equal(top_3_countries.index, expected_index)

Don’t forget about the edge cases

In the examples above we’re testing only the happy path, the expected behavior when everything goes according to plan. However, it’s essential to consider situations where something may not go as expected.

These are called edge cases, and we need to define the desired behavior for them. For instance, we may want to allow negative values or not, depending on the data type we’re working with.

To illustrate that, let’s expand on the last example, where we tested the get_top_n_countries function. We can think of a few situations where we might have results that deviate from the happy path.

The DataFrame is empty

If the DataFrame is empty we may want to ensure that the function runs and no errors are raised:

def test_get_top_n_countries_empty_dataframe():
    data = {'country': [],
            'population': []}
    df = pd.DataFrame(data)

    top_3_countries = get_top_n_countries(df, 'population', 3)

    expected_index = pd.Index([], name='country')
    assert_index_equal(top_3_countries.index, expected_index, exact=False)

The DataFrame contains missing values (NaN)

If the DataFrame contains missing values, we may want to ensure that they are being handled correctly and no rows are being dropped:

def test_get_top_n_countries_missing_values():
    data = {'country': ['USA', 'China', 'Japan'],
            'population': [328, 1393, float('nan')]}
    df = pd.DataFrame(data)

    top_3_countries = get_top_n_countries(df, 'population', 3)

    expected_index = pd.Index(['China', 'USA', 'Japan'], name='country')
    assert_index_equal(top_3_countries.index, expected_index)

The DataFrame contains non-numeric values

If the DataFrame contains values that are not numbers, we may want to raise an exception if they are in the column being sorted:

def test_get_top_n_countries_non_numeric_values():
    # arrange
    data = {'country': ['USA', 'China', 'Japan'],
            'population': [328, 1393, 'One hundred twenty six']}
    df = pd.DataFrame(data)
    # act and assert
    with pytest.raises(TypeError):
        get_top_n_countries(df, 'population', 3)

The DataFrame contains negative values

If the DataFrame contains negative values, we may want to raise an exception when we’re working with population data, as a negative population value wouldn’t make sense.

To do that, we would first need to change the function that is being tested:

def get_top_n_countries(df, column_name, n):
    if column_name == 'population' and (df[column_name] < 0).any():
        raise ValueError('population values must be greater than zero')

    sorted_df = df.sort_values(column_name, ascending=False)
    top_n_countries = sorted_df.head(n)
    top_n_countries.set_index('country', inplace=True)
    return top_n_countries

Then we can implement the test:

def test_get_top_n_countries_non_numeric_values():
    data = {'country': ['USA', 'China', 'Japan'],
            'population': [328, 1393, -100]}
    df = pd.DataFrame(data)

    with pytest.raises(ValueError):
        get_top_n_countries(df, 'population', 3)

By testing these edge cases, we can ensure that our function works correctly and handles unexpected situations appropriately.

Final words

Testing is a crucial step in software development, and Pandas is no exception. In conclusion:

Although it may be harder to test Pandas code, and it’s not as common as testing regular Python code, it is still an essential part of the development process that should not be overlooked.
When it comes to testing, Pytest is a simple and robust tool that lets us define compact functions for testing.
To write good tests, we should always remember to test both the “happy paths” and the edge cases, and follow the “arrange / act / assert” structure for unit tests.
Proper naming of everything when testing is highly recommended to avoid confusion.
When testing Pandas, we should use Pandas test methods such as assert_frame_equal, assert_series_equal, and assert_index_equal.

By following these tips and best practices, we can ensure that our Pandas code is reliable, robust, and performs as expected.

Maximize Your React Skills: Build a To-Do List App from Start to Finish (with TypeScript + Vite)

Eduardo Motta de Moraes — Wed, 25 Jan 2023 16:09:38 +0000

In this blog post we’re going to go through everything you need to understand and build a basic React application. Whether you’re a beginner just getting started with React or a seasoned developer looking to brush up on your skills, this guide is for you.

This guide will take you through the entire process of building a fully-functional to-do list app, including design, layout, state management, and more. We will be using functional components and hooks. We will learn how to use state and props to pass data between components, and how to handle user input and update the state of your app.

By the end of this guide, we will have a solid understanding of how to build a React app from scratch, and you will be able to take your newfound knowledge to build your own React projects.

So, let’s get started!

*You can find the code of the app we’re going to be building here, and the live version here.

A brief intro

We'll be using TypeScript for writing the code and Vite for developing and building the app.

TypeScript

TypeScript is a strongly typed programming language that builds on JavaScript. In practical terms, if you already know JavaScript, all you need to learn to use TypeScript is how to use types and interfaces.

Types and interfaces allow us to define the data types we're using in the code. With this, we can catch bugs early on and avoid problems down the line.

For instance, if a function takes a number but we pass it a string, TypeScript will complain immediately:

const someFunc = (parameter: number) => {...};

someFunc('1') // Argument of type 'string' is not assignable to parameter of type 'number'.

If we were using JavaScript we’d likely only catch the bug later on.

We don’t always need to specify the type, as TypeScript can infer them automatically more often than not.

You can learn the basics of TypeScript here. (Or just ignore the types.)

Vite

The most common way of spinning up a React application is probably using create-react-app. We’ll be using Vite (pronounced like “veet”) instead. But fret not, it’s just as simple — but more efficient.

With tools like webpack (used by create-react-app under the hood), your entire application needs to be bundled in a single file before it can be served to the browser. Vite, on the other hand, takes advantage of native ES modules in the browser to make bundling more efficient with Rollup, serving parts of the source code as needed.

Vite can also greatly speed up development time with Hot Module Replacement — meaning whenever changes are made to the source code, only the changes are updated, rather than the entire application.

Besides that, Vite offers native support for Typescript, JSX and TSX, CSS and more.

Similarly to create-react-app, Vite offers a tool called create-vite, that allows us to quickly start a new project using basic templates, including options for Vanilla JS, or using libraries like React.

To be clear, we don’t need a tool like Vite or create-react-app to build React applications, but they make our life easier by taking care of setting up the project, bundling the code, using transpilers and much more.

Diving into React

JSX / TSX

React allows us to add markup directly in the code which will later be compiled to plain JavaScript. This is called JSX. When we’re using JSX we can save our files as .jsx for JavaScript or .tsx for TypeScript.

It looks like this:

const element = <h1>Hello, world!</h1>;

It’s similar to HTML, but it’s embedded in the JavaScript file, and it allows us to manipulate the markup with programming logic. We can also add JavaScript code inside the JSX, as long as it’s inside curly brackets.

For instance, if we have an array of text we want to render as different paragraph elements, we could do this:

const paragraphs = ["First", "Second", "Third"];

paragraphs.map((paragraph) => <p>{paragraph}</p>);

And it would be compiled to something like this:

<p>First</p>
<p>Second</p>
<p>Third</p>

But if we try to do just that, it won’t work. That’s because React works with components, and JSX needs to be rendered inside these components.

React components

React components can be written using JavaScript classes or just plain functions. We’ll be focusing on function components, as they are the most up-to-date and the recommended way of writing React components today.

A component is defined by a function that will return the JSX which will be compiled and rendered by the browser. So to extend the example above, if we want to render the paragraph elements, it would look something like this:

// Define the component
const Component = () => {
  const paragraphs = ["First", "Second", "Third"];
  return (
    <>
      {paragraphs.map((paragraph) => (
        <p>{paragraph}</p>
      ))}
    </>
  );
};

// Use the component in the same way you use an HTML element in the JSX
const OtherComponent = () => {
  return <Component />;
};

Props

Now maybe we want to reuse this component with different information. We can do that by using props — which is just a JavaScript object holding some data.

In our example, instead of hardcoding the array, we could pass it to the component. The result will be the same, but now the component will be reusable.

If we’re using TypeScript, we need to specify the types of the data inside the props object (there’s no context for what they are, so TypeScript can’t infer them), which in this case is an array of strings (string[]).

const Component = (props: { paragraphs: string[] }) => {
  <>
    {props.paragraphs.map((paragraph) => (
      <p>{paragraph}</p>
    ))}
  </>;
};

const OtherComponent = () => {
  const paragraphs = ["First", "Second", "Third"];
  return <Component paragraphs={paragraphs} />;
};

State

If we want to make an interactive component, we’re going to need to store information in the component’s state, so it can “remember” it.

For instance, if we want to define a simple counter that shows the number of times a button is clicked, we need a way of storing and updating this value. React lets us do it with the useState hook (a hook is a function that lets you “hook” into the React state and lifecycle features).

We call the useState hook with the initial value, and it returns to us an array with the value itself and a function to update it.

import { useState } from "react";

const Counter = () => {
  const [count, setCount] = useState(0);
  return (
    <>
      <span>{count}</span>
      <button onClick={() => setCount(count + 1)}>Increment count</button>
    </>
  );
};

With this knowledge, we’re now ready to start building our React app.

Creating the project

Dependencies

To use Vite we’re going to need **node **and a package manager.

To install node just choose one of the options here depending on your system and configurations. If you’re using Linux or a Mac, you can also install it using Homebrew.

The package manager can be npm or yarn. In this post we’re going to using npm.

Creating the project

Next it’s time to create the project. In the terminal, we navigate to the directory where the project will be created, then run the create-vite command.

$ npm create vite@latest

We may be prompted to install additional packages (like create-vite). Type y and press enter to continue.

Need to install the following packages:
  create-vite@4.0.0
Ok to proceed? (y)

Next we’ll be prompted to enter the project information.

Enter the name of the project. I chose my-react-project.

? Project name: › my-react-project

Select React as the “framework”.

React is technically a library and not a framework, but don’t worry about it.

? Select a framework: › - Use arrow-keys. Return to submit.
    Vanilla
    Vue
❯   React
    Preact
    Lit
    Svelte
    Others

Select TypeScript + SWC as variant.

SWC (stands for Speedy Web Compiler ) is a super-fast TypeScript / JavaScript compiler written in Rust. They claim to be “20x faster than Babel on a single thread and 70x faster on four cores”.

? Select a variant: › - Use arrow-keys. Return to submit.
    JavaScript
    TypeScript
    JavaScript + SWC
❯   TypeScript + SWC

It’s done, the project is created. To start it in development mode, we need to change to the project directory, install the dependencies and run the dev script command.

cd my-react-project
npm install
npm run dev

After a few seconds, we will see something similar to this:

  VITE v4.0.4  ready in 486 ms

  ➜  Local:   http://localhost:5173/
  ➜  Network: use --host to expose
  ➜  press h to show help

If we open our browser and navigate to http://localhost:5173/ we’ll see the default Vite + React page:

This means that everything is as it should be and we can start working on our app.

Building the app

File structure and initial setup

If we open the project in our code editor or IDE of choice, we should see a file structure like this:

We can delete some of the boilerplate files, since we won’t be using them (all .svg and .css files).

The code in the App function can be deleted to leave us with this:

function App() {
  return (

  )
}

export default App

We’ll come back to this file later.

Styling

Styling isn’t the focus here, but we’ll be using Tailwind CSS, which is a library that lets us style HTML elements by adding classes to them. Follow these instructions to see the styles reflected in your own project.

Otherwise you can just ignore the classes in the code.

Thinking about the design: components layout

The design process is an integral part of the development of an app and shouldn’t be overlooked.

To build our to-do list app, we need to first think of the components layout.

We start by mocking a basic UI and outlining a hierarchy of the components involved.

If you’re not a designer, it doesn’t need to be perfect or the final UI in terms of colors and exact placement yet — it’s more important to think of the components structure.

Ideally, our components should be responsible for only one thing, following the single-responsibility principle.

In the image below, the names in purple are the components we’re going to be building — everything else are native HTML elements. If they’re inside each other, it means there’s likely going to be a parent-child relationship.

Props: building a static version

After we have a sketch, we can start building a static version of the app. That is to say, just the UI elements, but with no interactivity yet. This part is pretty straightforward and involves a lot of typing and little thinking once you get the hang of it.

You can find the code for the static version in this GitHub repository, in the branch “static-version”. The code for the fully working app is the main branch.

Container

As outlined above, we’re going to have a Container that is reused for every section of the app. This Container shows one of the ways of composing different elements: by passing them as children.

// src/components/Container.tsx
const Container = ({
  children,
  title,
}: {
  children: JSX.Element | JSX.Element[];
  title?: string;
}) => {
  return (
    <div className="bg-green-600 p-4 border shadow rounded-md">
      {title && <h2 className="text-xl pb-2 text-white">{title}</h2>}
      <div>{children}</div>
    </div>
  );
};

export default Container;

It takes a props object with a children parameter of type JSX.Element | JSX.Element[]. This means we can compose it with any other HTML element or any other components we create. It can be rendered wherever we want inside the container — in this case inside the second div.

In our app, it’s going to render each section (defined below) when we use them inside the App component.

The Container also takes an optional string prop named title, which will be rendered inside an h2 whenever it exists.

// src/App.tsx
import Container from "./components/Container";
import Input from "./components/Input";
import Summary from "./components/Summary/Summary";
import Tasks from "./components/Tasks/Tasks";

function App() {
  return (
    <div className="flex justify-center m-5">
      <div className="flex flex-col items-center">
        <div className="sm:w-[640px] border shadow p-10 flex flex-col gap-10">
          <Container title={"Summary"}>
            <Summary />
          </Container>
          <Container>
            <Input />
          </Container>
          <Container title={"Tasks"}>
            <Tasks />
          </Container>
        </div>
      </div>
    </div>
  );
}

export default App;

Summary

The first section is a summary (Summary component) showing three items (SummaryItem): the total number of tasks, the number of pending tasks and the number of completed tasks. This is another way of composing components: just use them in the return statement of another component.

(It’s important to never define a component inside another component, though, as that can lead to unnecessary rerenders and bugs.)

For now we can just use static data in the two components.

// src/components/Summary/SummaryItem.tsx
const SummaryItem = ({
  itemName,
  itemValue,
}: {
  itemName: string;
  itemValue: number;
}) => {
  return (
    <article className="bg-green-50 w-36 rounded-sm flex justify-between p-2">
      <h3 className="font-bold">{itemName}</h3>
      <span className="bg-green-900 text-white px-2 rounded-sm">
        {itemValue}
      </span>
    </article>
  );
};

export default SummaryItem;

// src/components/Summary/Summary.tsx
import SummaryItem from "./SummaryItem";

const Summary = () => {
  return (
    <>
      <div className="flex justify-between">
        <SummaryItem itemName={"Total"} itemValue={3} />
        <SummaryItem itemName={"To do"} itemValue={2} />
        <SummaryItem itemName={"Done"} itemValue={1} />
      </div>
    </>
  );
};

export default Summary;

You will notice SummaryItem takes two props: itemName, of type string, and itemValue, of type number. These props are passed when the SummaryItem component is used inside the Summary component, and then rendered in the SummaryIte JSX.

Tasks

Similarly, for the tasks section (the last one) we have a Tasks component that renders the TaskItem components.

Also with static data for now. We will later need to pass a task name and a status down as props to the TaskItem component to make it reusable and dynamic.

// src/components/Tasks/TaskItem.tsx
const TaskItem = () => {
  return (
    <div className="flex justify-between bg-white p-1 px-3 rounded-sm">
      <div className="flex gap-2 items-center">
        <input type="checkbox" />
        Task name
      </div>
      <button className="bg-green-200 hover:bg-green-300 rounded-lg p-1 px-3">
        Delete
      </button>
    </div>
  );
};

export default TaskItem;

// src/components/Tasks/Tasks.tsx
import TaskItem from "./TaskItem";

const Tasks = () => {
  return (
    <div className="flex flex-col gap-2">
      <TaskItem />
    </div>
  );
};

export default Tasks;

Input

Finally, the Input component is a form with a label, an input of type text, and a button to “Add task”. For now it doesn’t do anything, but we’ll soon change that.

// src/components/Input.tsx
const InputContainer = () => {
  return (
    <form action="" className="flex flex-col gap-4">
      <div className="flex flex-col">
        <label className="text-white">Enter your next task:</label>
        <input className="p-1 rounded-sm" />
      </div>
      <button
        type="button"
        className="bg-green-100 rounded-lg hover:bg-green-200 p-1"
      >
        Add task
      </button>
    </form>
  );
};

export default InputContainer;

State: adding interactivity

To add interactivity in React, we need to store information in the component’s state.

But before doing that, we need to think about how we want the data to change over time. We need to identify a minimal representation of this data, and identify which components we should use to store this state.

A minimal representation of state

State should contain every bit of information necessary to make our app interactive — but nothing more. If we can compute a value from a different value, we should keep just one of them in state. This makes our code not only less verbose, but also less prone to bugs involving contradictory state values.

In our example we might think we need to track values for total tasks, pending tasks, and done tasks.

But to track the tasks, it is enough to have a single array with objects representing each task and its status (pending or done).

const tasks = [
  {
    name: "task one",
    done: false,
  },
  {
    name: "task two",
    done: true,
  },
];

With this data we can always find all of the other information we need at render time using array methods. We also avoid the possibility of contradictions,— like having a total of 4 tasks, but only 1 pending and 1 done task, for example.

We also need state in our form (in the Input component) so we can make it interactive.

Where the state should live

Think of it this way: which components need to access the data we’re going to store in state? If it’s a single component, the state can live in this component itself. If it’s more than one component that need the data, then you should find the common parent to these components.

In our example, the state necessary to control the Input component only needs to be accessed there, so it can be local to this component.

// src/components/Input.tsx
import { useState } from "react";

const InputContainer = () => {
  const [newTask, setNewTask] = useState(""); // Initialize newTask and setNewTask
  return (
    <form action="" className="flex flex-col gap-4">
      <div className="flex flex-col">
        <label className="text-white">Enter your next task:</label>
        <input
          className="p-1 rounded-sm"
          type="text"
          value={newTask} // Set the input value to newTask
          onChange={(e) => setNewTask(e.target.value)} // Set newTask to the input value whenever the user types something
        />
      </div>
      <button
        type="submit"
        className="bg-green-100 rounded-lg hover:bg-green-200 p-1"
      >
        Add task
      </button>
    </form>
  );
};

export default InputContainer;

What this is doing is displaying our newTask value in the input, and calling the setNewTask function whenever the input changes (i.e., when the user types something).

We won’t see any immediate changes in the UI, but this is necessary so we can control the input and have access to its value to use it later.

The state to track the tasks, however, has to be handled differently, as it needs to be accessed in the SummaryItem components (we need to show the number of total, pending and done tasks) as well as in the TaskItem components (we need to display the tasks themselves). And it needs to be the same state because this information must always be in sync.

Let’s take a look at our component tree (you can use the React dev tools for this).

We can see that the first common parent component is App. So this is where our state for the tasks is going to live.

With the state in place, all that will be left will be to pass the data down as props to the components that need to use it.

(We’re not yet worried about how to make and persist any changes to the parent state, that’s the next part.)

// src/App.tsx
import { useState } from "react";
import { v4 as uuidv4 } from "uuid";
import Container from "./components/Container";
import Input from "./components/Input";
import Summary from "./components/Summary/Summary";
import Tasks from "./components/Tasks/Tasks";

export interface Task {
  name: string;
  done: boolean;
  id: string;
}

const initialTasks = [
  {
    name: "task one",
    done: false,
    id: uuidv4(),
  },
  {
    name: "task two",
    done: true,
    id: uuidv4(),
  },
];

function App() {
  const [tasks, setTasks] = useState<Task[]>(initialTasks);
  return (
    <div className="flex justify-center m-5">
      <div className="flex flex-col items-center">
        <div className="border shadow p-10 flex flex-col gap-10 sm:w-[640px]">
          <Container title={"Summary"}>
            <Summary tasks={tasks} />
          </Container>
          <Container>
            <Input />
          </Container>
          <Container title={"Tasks"}>
            <Tasks tasks={tasks} />
          </Container>
        </div>
      </div>
    </div>
  );
}

export default App;

Here we’re initializing the tasks value with dummy data (initialTasks), just so that we can visualize it before the app is finished. Later we can change it to an empty array, so a new user will not see any tasks when opening the app fresh.

Besides the name and done properties, we’re also adding an id to our task objects, as it will be necessary shortly.

We’re defining an interface with the types of the value in the task objects, and passing it to the useState function. This is necessary in this case, as TypeScript will not be able to infer it when we change the initial value of tasks to an empty array, or when we pass it as props.

Finally, notice we’re passing the tasks down as props to the Summary and Tasks components. These components will need to be changed to accommodate that.

// src/components/Summary/Summary.tsx
import { Task } from "../../App";
import SummaryItem from "./SummaryItem";

const Summary = ({ tasks }: { tasks: Task[] }) => {
  const total = tasks.length;
  const pending = tasks.filter((t) => t.done === false).length;
  const done = tasks.filter((t) => t.done === true).length;
  return (
    <>
      <div className="flex flex-col gap-1 sm:flex-row sm:justify-between">
        <SummaryItem itemName={"Total"} itemValue={total} />
        <SummaryItem itemName={"To do"} itemValue={pending} />
        <SummaryItem itemName={"Done"} itemValue={done} />
      </div>
    </>
  );
};

export default Summary;

We updated the Summary component so that it now accepts tasks as a prop. We also defined the value total, pending and done, which will be passed down as props to the SummaryItem components in place of the static itemValue’s we had before.

// src/components/Tasks/Tasks.tsx
import { Task } from "../../App";
import TaskItem from "./TaskItem";

const Tasks = ({ tasks }: { tasks: Task[] }) => {
  return (
    <div className="flex flex-col gap-2">
      {tasks.map((t) => (
        <TaskItem key={t.id} name={t.name} />
      ))}
    </div>
  );
};

export default Tasks;

// src/components/Tasks/TaskItem.tsx
import { useState } from "react";

const TaskItem = ({ name }: { name: string }) => {
  const [done, setDone] = useState(false);
  return (
    <div className="flex justify-between bg-white p-1 px-3 rounded-sm gap-4">
      <div className="flex gap-2 items-center">
        <input type="checkbox" checked={done} onChange={() => setDone(!done)} />
        {name}
      </div>
      <button className="bg-green-200 hover:bg-green-300 rounded-lg p-1 px-3">
        Delete
      </button>
    </div>
  );
};

export default TaskItem;

For the Tasks component, we also take tasks as a prop, and map its name property to TaskItem components. As a result, we get a TaskItem component for each object inside the tasks array. We also update the TaskItem component to accept name as a prop.

This is where the id comes in handy, as we need to pass a unique key every time we have a list of child components. If we don’t add the key, this could lead to bugs on rerender. (In a production app, the id would most likely come from the backend.)

The result for now is this:

We can already see the summary numbers and the task names reflecting our dummy data. But we still lack a way to add or delete tasks.

Adding inverse data flow

To finish our app, we need a way to change the App component state (where the tasks data is) from the Input and TaskItem child components.

To do that, we can use the functions generated by the useState hook to define event handlers, and pass them down as props. Once we do that, we simply call them during the appropriate user interaction from the child components.

Be sure to never mutate state whenever you’re updating it, as this will lead to bugs. Always replace the state object with a new one when updating it.

Below is our final App component with the handlers declared and passed down as props to the Input and Tasks components.

handleSubmit returns a new array with the old tasks plus the new one. toggleDoneTask returns a new array with the opposite done property, for the specified id. handleDeleteTask returns a new array without the task with the specified id.

// src/App.tsx
import { FormEvent, useState } from "react";
import { v4 as uuidv4 } from "uuid";
import Container from "./components/Container";
import Input from "./components/Input";
import Summary from "./components/Summary/Summary";
import Tasks from "./components/Tasks/Tasks";

export interface Task {
  name: string;
  done: boolean;
  id: string;
}

function App() {
  const [tasks, setTasks] = useState<Task[]>([]);

  const handleSubmit = (e: FormEvent<HTMLFormElement>, value: string) => {
    e.preventDefault();
    const newTask = {
      name: value,
      done: false,
      id: uuidv4(),
    };
    setTasks((tasks) => [...tasks, newTask]);
  };

  const toggleDoneTask = (id: string, done: boolean) => {
    setTasks((tasks) =>
      tasks.map((t) => {
        if (t.id === id) {
          t.done = done;
        }
        return t;
      })
    );
  };

  const handleDeleteTask = (id: string) => {
    setTasks((tasks) => tasks.filter((t) => t.id !== id));
  };

  return (
    <div className="flex justify-center m-5">
      <div className="flex flex-col items-center">
        <div className="border shadow p-10 flex flex-col gap-10 sm:w-[640px]">
          <Container title={"Summary"}>
            <Summary tasks={tasks} />
          </Container>
          <Container>
            <Input handleSubmit={handleSubmit} />
          </Container>
          <Container title={"Tasks"}>
            <Tasks
              tasks={tasks}
              toggleDone={toggleDoneTask}
              handleDelete={handleDeleteTask}
            />
          </Container>
        </div>
      </div>
    </div>
  );
}

export default App;

This is the final Input component using handleSubmit to update the App component state.

// src/components/Input.tsx
import { FormEvent, useState } from "react";

const InputContainer = ({
  handleSubmit,
}: {
  handleSubmit: (e: FormEvent<HTMLFormElement>, value: string) => void;
}) => {
  const [newTaskName, setNewTaskName] = useState("");
  return (
    <form
      action=""
      className="flex flex-col gap-4"
      onSubmit={(e) => {
        handleSubmit(e, newTaskName);
        setNewTaskName("");
      }}
    >
      <div className="flex flex-col">
        <label className="text-white">Enter your next task:</label>
        <input
          className="p-1 rounded-sm"
          type="text"
          value={newTaskName}
          onChange={(e) => setNewTaskName(e.target.value)}
        />
      </div>
      <button
        type="submit"
        className="bg-green-100 rounded-lg hover:bg-green-200 p-1"
      >
        Add task
      </button>
    </form>
  );
};

export default InputContainer;

This is the final Tasks component, which we updated to pass the props from App down to TaskItem. We also added a ternary operator to return “No tasks yet!” when there are no tasks.

// src/components/Tasks/Tasks.tsx
import { Task } from "../../App";
import TaskItem from "./TaskItem";

const Tasks = ({
  tasks,
  toggleDone,
  handleDelete,
}: {
  tasks: Task[];
  toggleDone: (id: string, done: boolean) => void;
  handleDelete: (id: string) => void;
}) => {
  return (
    <div className="flex flex-col gap-2">
      {tasks.length ? (
        tasks.map((t) => (
          <TaskItem
            key={t.id}
            name={t.name}
            done={t.done}
            id={t.id}
            toggleDone={toggleDone}
            handleDelete={handleDelete}
          />
        ))
      ) : (
        <span className="text-green-100">No tasks yet!</span>
      )}
    </div>
  );
};

export default Tasks;

And this is the final TaskItem component, using toggleDone and handleDelete to update the App component state.

// src/components/Tasks/TaskItem.tsx
const TaskItem = ({
  name,
  done,
  id,
  toggleDone,
  handleDelete,
}: {
  name: string;
  done: boolean;
  id: string;
  toggleDone: (id: string, done: boolean) => void;
  handleDelete: (id: string) => void;
}) => {
  return (
    <div className="flex justify-between bg-white p-1 px-3 rounded-sm gap-4">
      <div className="flex gap-2 items-center">
        <input
          type="checkbox"
          checked={done}
          onChange={() => toggleDone(id, !done)}
        />
        {name}
      </div>
      <button
        className="bg-green-200 hover:bg-green-300 rounded-lg p-1 px-3"
        type="button"
        onClick={() => handleDelete(id)}
      >
        Delete
      </button>
    </div>
  );
};

export default TaskItem;

And here’s our final app after we add a few tasks!

If you’re coding along, you can deploy your own app by following these instructions.

You can find the repo with all of the code we went through here, and the live version of the app here.

Final words

In conclusion, building a to-do list app can be a great way to learn and solidify our understanding of React and its principles. By breaking down the process into small steps and following best practices, we can create a functional app in a relatively short amount of time.

We’ve covered:

the key concepts of components, state, and inverse data flow.
the design and architecture of the app.
best practices such as the single-responsibility principle

By following the steps outlined in this guide, you should now have a solid understanding of how to build a simple React app and be able to apply it to your own projects.

Happy coding!

How to use Firestore with Redux in a React application

Eduardo Motta de Moraes — Mon, 09 Jan 2023 10:11:03 +0000

You’re using Firebase as your backend-as-a-service platform, with Firestore holding your data. You’re building the frontend with React and you want to use Redux to manage the app’s state.

If you’re still wondering how to efficiently fetch data from Firestore and seamlessly add it to your Redux state, you’ve come to the right place.

In this post I’m going to explain how to do it using some of the recommended approaches when using Redux today, in 2023.

TL;DR: use RTK Query, with queryFn functions that call the Firebase SDK.

Some background

Firebase and Redux

Firebase is a backend-as-a-service platform. One of their products is Firestore, which is a noSQL database. To use it in your app, the recommended approach is to use the Firebase SDK.

Redux is a state management library. It’s useful when your app’s state is too large, or the logic to update it too complex, among other scenarios.

You should be using Redux Toolkit

If you’re trying to build an app using Firestore and Redux, you may have come across resources explaining how to the fetch data, and in a separate process add it to Redux state. You may have read about writing your fetching logic using “thunks” explicitly. There’s even a package you may have found called react-redux-firebase that provides React bindings.

While these solutions certainly work, they’re not the most efficient or up-do-date in 2023. The main reason for this being — since most of the resources I found were written more than a few years ago — they do not make use of a library that will make your life using Redux 100% easier and more efficient: Redux Toolkit (or “RTK”).

As of today, the Redux documentation recommends always using RTK. In their own words, “RTK includes utilities that help simplify many common use cases, including store setup, creating reducers and writing immutable update logic, and even creating entire ‘slices’ of state at once.”

Using RTK Query to fetch data

If you’re using RTK, you should probably also be using RTK Query to fetch your data from the backend. It eliminates the need to write data fetching and caching logic yourself.

The createApi function is the core of RTK Query’s functionality. From their documentation: “It allows you to define a set of ‘endpoints’ that describe how to retrieve data from backend APIs and other async sources, including the configuration of how to fetch and transform that data. It generates an ‘API slice’; structure that contains Redux logic (and optionally React hooks) that encapsulate the data fetching and caching process for you”.

Normally, createApi is used by defining a baseUrl and then defining endpoints for specific queries and mutations:

// Define a service using a base URL and expected endpoints
export const pokemonApi = createApi({
  reducerPath: 'pokemonApi',
  baseQuery: fetchBaseQuery({ baseUrl: 'https://pokeapi.co/api/v2/' }),
  endpoints: (builder) => ({
    getPokemonByName: builder.query<Pokemon, string>({
      query: (name) => `pokemon/${name}`,
    }),
  }),
})

Firebase, though, works through its SDK, not through an API. If we still want to keep the benefits of fetching and mutating data using RTK Query (more on this below), we need a slightly different approach, as we’ll see.

Where to get the final code of the app shown here

The final version of the code shown in this post is part of a project that can be found in this repository. In my previous post I went through the design process and some insights I had while implementing it.

Implementing it

Before anything else, we need to install the necessary libraries (@reduxjs/toolkit and firebase), configure the Firebase project and set up the Redux store using RTK.

The first thing we’ll do after that is create a “slice” of the state, where we will write the code related to a specific part of the state. As mentioned, we’ll be using the createApi function for that.

We can do that by creating a single slice containing all of the logic pertaining to our API, or we can split it in more than one slice. In either case, it is recommended to define a single central slice. If we need more than one slice, we can inject the different endpoints in the central slice later.

For this post we’ll implement one slice that will fetch and update data related to a high-scores table from the Firestore database. In the repo and in this link you can see what would need to be changed if you need more than one slice when using RTK Query.

In this example, we’re creating a file called scoresSlice.ts:

// src/features/scores/scoresSlice.ts
import { createApi, fakeBaseQuery } from "@reduxjs/toolkit/query/react";
import {
  arrayUnion,
  collection,
  doc,
  updateDoc,
  getDocs,
} from "firebase/firestore";
import { firestore } from "../../firebase";
import { ScoresTable, ScoresTables } from "../../types";

export const firestoreApi = createApi({
  baseQuery: fakeBaseQuery(),
  tagTypes: ["Score"],
  endpoints: (builder) => ({
    fetchHighScoresTables: builder.query<ScoresTables, void>({
      async queryFn() {
        try {
          const ref = collection(firestore, "scoresTables");
          const querySnapshot = await getDocs(ref);
          let scoresTables: ScoresTables = [];
          querySnapshot?.forEach((doc) => {
            scoresTables.push({ id: doc.id, ...doc.data() } as ScoresTable);
          });
          return { data: scoresTables };
        } catch (error: any) {
          console.error(error.message);
          return { error: error.message };
        }
      },
      providesTags: ["Score"],
    }),
    setNewHighScore: builder.mutation({
      async queryFn({ scoresTableId, newHighScore }) {
        try {
          await updateDoc(doc(firestore, "scoresTables", scoresTableId), {
            scores: arrayUnion(newHighScore),
          });
          return { data: null };
        } catch (error: any) {
          console.error(error.message);
          return { error: error.message };
        }
      },
      invalidatesTags: ["Score"],
    }),
  }),
});

export const { useFetchHighScoresTablesQuery, useSetNewHighScoreMutation } =
  firestoreApi;

*A note: The way things are set up here, Firestore rules need to be open for read and write by everyone, which is not recommended for production. A better approach would be calling Firebase Functions to perform operations on Firestore, but since they don’t offer a free version for that, for the sake of this example project I chose to leave things as they are shown here.

The createApi function takes an object with baseQuery and endpoints. In this example we’re also adding optional tagTypes. RTK Query will automatically generate React hooks so that we can use the queries and mutations.

baseQuery

This is normally used to define the base URL of the API (see the Pokémon example above, under the “Using RTK Query to fetch data” section).

Nevertheless, since we’re using the Firebase SDK, we don’t have a base URL. We can instead use a fakeBaseQuery(), imported from the RTK Query library.

tagTypes

Tag types are used for caching and invalidation.

When specifying them, you will be able to provide tags when data is fetched from the database. Afterwards, you can invalidate the cache of specific tags, meaning the data will need to be fetched again. This can be useful when you need to ensure that you’re using the most up-to-date data.

In our example, we’re specifying the tag “Score”.

We provide this tag when fetching data from the fetchHighScoresTables endpoint (notice the providesTags: [‘Score’] after the endpoint object).

When setting a new high score with the setNewHighScore endpoint, we’re invalidating the same tag (invalidatesTags: [‘Score’] after the endpoint object). This means that the cached data fetched with fetchHighScoresTables (without the new high score) will be invalidated and the data will need to be fetched again (this time with the new high score).

endpoints

This is a function that takes a builder as argument and returns an object with the expected API endpoints.

Normally the endpoints would look like in the Pokémon example above (under the “Using RTK Query to fetch data” section).

To fetch data from Firestore, though, considering we’re not actually querying it from an API, we need to use the queryFn function. This allows us to define any arbitrary logic inside it, as long as we return the data in the shape expected by RTK Query (i.e. { data: ResultType }).

In the example above, we’re importing and using the Firebase SDK functions to query and update Firestore, just like we would if not using RTK Query. After querying the data, we return { data: scoresTables }; when updating the database, no data needs to be returned, but RTK Query still expects the same shape of return, so we simply return { data: null }.

React hooks

After defining firestoreApi with the createApi function, RTK Query will automatically generate React hooks to query/mutate the data.

As per the documentation: “A React hook that automatically triggers fetches of data from an endpoint, ‘subscribes’ the component to the cached data, and reads the request status and cached data from the Redux store. The component will re-render as the loading status changes and the data becomes available.”

In the example above, it generated the useFetchHighScoresTablesQuery and useSetNewHighScoreMutation hooks. We can use them just like any other React hook (inside function components, or inside other custom hooks).

The use…Query hook will return an object with the data and the query properties.

// src/features/scores/HighScores.tsx
import { useFetchHighScoresTablesQuery } from './scoresSlice';

const HighScores = () => {
  const {
    data,
    isLoading,
    isSuccess,
    isError,
    error,
  } = useFetchHighScoresTablesQuery();

  return (
    // ...
  )
}

The use…Mutation hook will return a tuple with a mutation trigger and the mutation result. The mutation trigger is called to fire off the mutation request. The mutation result is an object with the mutation properties.

// src/features/scores/components/EnterName.tsx
import { useSetNewHighScoreMutation } from '../scoresSlice';

const EnterName = () => {
  const [setNewHighScore, result] = useSetNewHighScoreMutation();

  // assume we set the variable 'id' with the table id
  // and the variable 'newHighScore' with a valid high score

  return (
    <button onClick={() => setNewHighScore(id, newHighScore)}></button>
  )
}

And this is it! You’re all set to use Firestore while keeping the benefits of Redux and RTK Query.

Final words

In summary:

To use Firestore with Redux in a React application, it is recommended to use Redux Toolkit (RTK) and RTK Query.
RTK Query’s createApi function can be used to define endpoints for specific queries and mutations.
However, since the Firebase SDK is not an API, a different approach is needed to use createApi with Firestore.
By using RTK Query with queryFn functions that call the Firebase SDK, you can add data from Firestore to your Redux state and take advantage of the benefits of Redux and RTK Query.

I hope this can be useful to you, or at least be a source of inspiration!

Building a React application: "Where's Wally?"

Eduardo Motta de Moraes — Mon, 02 Jan 2023 12:36:05 +0000

I've been working as a fullstack (mostly backend) developer for a little more than a year now.

I'm also following The Odin Project curriculum, which is focused on web development. My latest project was one suggested in their JavaScript course. You can see the Github repository here and the live app here.

In this post I'm going to discuss some of my thinking behind its design and implementation. Specifically, how I approached each step of the design phase, and a few interesting aspects of things I learned during the development process.

Although it's a simple app, I was able to learn quite a few things with it.

The basic project requirements

The main objective of the project was to develop a kind of photo tagging app (actually a "Where's Waldo" style of game— or "Where's Wally" depending on where you're from).

If you're unfamiliar with it, here’s a short description: given an image with a multitude of characters, you need to find a few specific ones; you win when you find them all.

In the context of the app, the user should click on the image, select one of the characters, and receive feedback on whether they found it or not. After finding all the characters, their name goes to a high scores table with the time it took them to accomplish it.

The frontend was to be built with React, and the backend using Firebase (a Google backend-as-a-service platform).

The full description of the requirements can be found here.

Adding some extra spice: Redux and Tailwind CSS

I figured developing a React application with Firebase as a backend would be straightforward enough (I’m new to Firebase, but had used React before).

I decided to increment things a bit by adding Redux for state management and Tailwind CSS for styling, two JavaScript libraries I was yet to learn how to use.

I also used Typescript. While I’ve coded with it before, this was the first time I actually did my research to type everything correctly.

These additions made things more challenging, but also much more interesting.

Designing the application

One thing I learned the hard way is that it’s always better to think (a lot) before starting to code. It can save hours of development. So I took the time to design a few things before getting my hands dirty:

The information flow as the user interacts with the app

While React is declarative (meaning we code by describing the final state of the UI, not step-by-step instructions), I found that by thinking about the flow of information I could more easily figure out exactly what resources I would need from the backend at each step, the interactions I had to expect from the user, and all the components I would have to build.

In the backend I realized I would need storage for the images, as well as a database — Storage and Firestore, respectively, both from Firebase.

In the frontend I could see three main sources of user input: when selecting a level, when finding a character, and when adding their names to the high scores table.

From there, thinking about the UI components was straightforward.

The UI components

By thinking about all the components beforehand, I could visualize the relationships between them more easily (which components will be children of which, etc.). Coding a static version of the app, as I'll explain later, becomes easier.

As seen in the images above, I outlined the Home and the Level components as well as all of its children components. Some things ended up being changed in development, but these served as a good starting point. I didn’t design the High-scores component beforehand as it was simple enough.

The state of the application

Mocking the state and its shape helped me to think about all the information I would need, and how I would store it in Redux.

It also came in handy when I had to write all the interfaces and types, since I’m using Typescript.

Some thoughts about the development

UI components and Tailwind CSS

Loosely following the steps described in this handy section of the React documentation, I started the implementation by developing a static version of the components, as outlined in my design. This means coding the UI with no state or interactivity, which is usually a lot of somewhat mindless typing — since we did all the thinking when designing it.

This is when I started to delve into Tailwind CSS documentation. Tailwind is a CSS framework that allows us to apply CSS to HTML elements (or, in the case of React, JSX/TSX elements) simply by adding utility classes to them. It’s not a UI kit — there are no inbuilt components or themes — , so we still need to know our CSS.

It simplifies the process of creating custom themes, add responsiveness (it imposes a mobile-first mentality, with options for bigger screens), transitions… all of this using classes and with minimal configuration.

It has a bit of a learning curve, as we have to know the logic behind the class names and how they relate to the CSS code, but once we get the hang of it, I feel like it can greatly speed up the process of building responsive and yet customizable components.

App state, Redux and Firebase

Redux

Although not necessary for an app as simple as this one, I decided to use Redux to learn it with a hands-on approach. Simply put, Redux is a state container for JavaScript apps.

In React, every component can have its own state. Usually, when state needs to be shared between components, it needs to be “lifted” to a parent component and then passed down to the children components as props. In large applications this can become messy pretty quickly.

Redux helps in ensuring we have a predictable state. It works by having a centralized store, with reducer functions that hold the logic to how the state will be updated when “actions” are dispatched to it.

Although we can use Redux directly, or through the React-Redux bindings, this requires us to set up everything manually: from the store, to the middlewares, to reducers that will take manually written actions as arguments, among many other complicated things.

Redux Toolkit

As of today, though, the Redux documentation recommends always using Redux Toolkit (or “RTK”). In their own words, “RTK includes utilities that help simplify many common use cases, including store setup, creating reducers and writing immutable update logic, and even creating entire ‘slices’ of state at once.”

So this is what I used in my app. Using RTK, I set up a store and divided the state in five “slices”: three using the createSlice function for information about the found characters, for the button component used to select a character in the image, and for the timer; and two using the createApi function for fetching information about the levels and characters from the backend and storing it in the state.

createSlice

The createSlice function receives an object of reducer functions and automatically generates action creators and action types, which can be used to dispatch actions to the store.

(Some code was removed from the code snippets below for brevity and readability. The full source code can be found in the Github repo.)

// src/features/levels/slices/found-characters-slice.ts
export const foundCharactersSlice = createSlice({
  name: 'foundCharacters',
  initialState: foundCharactersInitialState,
  // Here we add the reducer functions
  reducers: {
    resetScore() {
      return foundCharactersInitialState;
    },
    setFoundCharacter(state, action: PayloadAction<string>) {
      const id = action.payload;
      const character = state.find((char: FoundCharacter) => char.id === id);
      if (character) character.found = true;
    },
  },
});

// RTK generates the action creators for us
export const { resetScore, setFoundCharacter } = foundCharactersSlice.actions;



// src/features/levels/useGame.ts

//...
const dispatch = useAppDispatch();
// We call the action creator with the desired payload
dispatch(setFoundCharacter(charPosition.character_id));

Once the slice is registered in the Redux store, we can easily use the action creators to easily update the state from anywhere in the app. There are some caveats when updating the state of a component while a different component is rendering, which I will discuss in a future post.

createApi and Firebase

The createApi function is the core of RTK Query’s functionality. From their documentation: “It allows you to define a set of ‘endpoints’ that describe how to retrieve data from backend APIs and other async sources, including the configuration of how to fetch and transform that data. It generates an ‘API slice’; structure that contains Redux logic (and optionally React hooks) that encapsulate the data fetching and caching process for you”.

Normally, createApi is used by defining a baseUrl and then defining endpoints for specific queries and mutations:

// Define a service using a base URL and expected endpoints
export const pokemonApi = createApi({
  reducerPath: 'pokemonApi',
  baseQuery: fetchBaseQuery({ baseUrl: 'https://pokeapi.co/api/v2/' }),
  endpoints: (builder) => ({
    getPokemonByName: builder.query<Pokemon, string>({
      query: (name) => `pokemon/${name}`,
    }),
  }),
})

Firebase, though, works through its specific SDK, not through an API. If we still want to keep the benefits of fetching and mutating data using RTK Query (such as caching, useQuery/useMutation hooks, etc.), we need a slightly different approach.

We need to use fakeBaseQuery() as the base query, and define the “endpoints” (which aren’t really endpoints) with queryFn, which needs to return an object with the shape { data: ResultType }. Inside queryFn we can use the Firebase SDK to read or write any data we need from Firestore, then return it in the way expected by RTK Query.

In the example below, we’re fetching a single document from Firestore, using its id. When the query is called, RTK Query will take the data and store it in state appropriately.

// src/features/levels/slices/levels-slice.ts
export const levelsApi = createApi({
  reducerPath: 'levels',
  baseQuery: fakeBaseQuery(),
  tagTypes: ['Level', 'Character'],
  endpoints: (builder) => ({
    // We define the async information fetch using Firebase
    fetchSingleLevel: builder.query<Level, string>({
      async queryFn(id) {
        try {
          const ref = doc(firestore, 'levels', id);
          const documentSnapshot = await getDoc(ref);
          const data: Level = { ...documentSnapshot.data() } as Level;
          return { data };
        } catch (error: any) {
          console.error(error.message);
          return { error: error.message };
        }
      },
      providesTags: ['Level'],
    }),
  }),
});

// RTK Query generates a hook we can use to fetch the data
export const { useFetchSingleLevelQuery } = levelsApi;



// src/features/levels/Level.tsx
// We use the hook to get the data, status indicators and a possible error
const { data, isLoading, isSuccess, isError, error } =
    useFetchSingleLevelQuery(levelId);

By doing this, we ensure the data is being fetched from Firestore while still maintaining RTK Query state management advantages.

For instance, as a rule RTK Query will cache the retrieved data for 60 seconds (we can change this time if necessary). This ensures, for example, that a user navigating back to a previously loaded page will see it load instantly, using the cached data. At the same time, the cache is cleaned after a while to ensure that any changes in the backend will eventually be reflected in the frontend.

Arriving at this solution took some trial and error, as there aren’t many updated resources about how to integrate RTK Query and Firebase. I may write a more detailed post about it in the near future.

The finished app

The finished app was deployed with Firebase Hosting and can be accessed here: https://top-project-photo-tagging.web.app/.

Below are some screenshots of the Home, Level and High scores pages. As we can see, there were some changes compared to the initial design, but the overall idea remained the same.

Closing remarks

These are just some of the main thoughts that went into designing and developing the app. To recapitulate:

Designing the app before coding it is important. By thinking about and visualizing the information flow I was able to more easily design the components and the state of the app, arguably saving me hours of coding.
Tailwind CSS can be very handy to quickly spin up a responsive, yet customized app.
React is great for state management as it centralizes the information in a single store that can be accessed throughout the app. Using RTK, this is made even simpler once you take the time to go through the documentation. RTK Query is also a useful tool if you need to fetch data from external sources.

Overall I believe this was great learning experience. There are many other interesting but somewhat more complex things that I went through, that may become separate posts in the future. If you're still reading, I hope this can be useful to you or a source of inspiration for future projects!