DEV Community: Mirco Bellagamba

Why is my React Component re-rendering?

Mirco Bellagamba — Fri, 10 May 2024 09:16:59 +0000

React’s beauty lies in its simplicity and lightning-fast rendering. But as our component-heavy applications grow, so can performance bottlenecks. Unnecessary re-renders are a prime culprit. This article tackles this challenge head-on, offering 4 techniques to optimize your React app’s performance.

Components Composition: Learn how to structure your components for optimal performance.
Uncontrolled Components: Discover a lighter-weight alternative to controlled components for focused updates.
memo, useMemo, useCallback: Master these hooks to optimize expensive calculations.
Splitting Large Context: Break down complex contexts to minimize re-renders.

We’ll explore these techniques through the lens of a practical example: refactoring a simple tasks management application. This CodeSandbox provides a starting point for our journey. As you progress through the article, feel free to explore the code step-by-step to gain a deeper understanding. This initial version offers basic to-do list functionality, including displaying tasks, adding new ones, and customizing the background color.

Version 0

While the current app delivers a smooth experience, it’s important to consider future scalability. Unnecessary re-renders can become a performance bottleneck as the application grows with more features and components. To illustrate this potential challenge, let’s introduce a SlowComponent simulating a computationally expensive component or a large component tree. The top right counter tracks re-renders, excluding double re-renders due to React’s Strict Mode.

Before showing a new version of the example, I’ll keep a note of what’s changed in that version. In the code example, a comment with the UPDATE keyword highlights changes.

What’s changed in version 1: The following code adds a SlowComponent after the ul.

Typing becomes noticeably sluggish, with each character appearing after a measurable delay. In some browsers, like Chrome, changing the background color dragging the mouse can feel significantly slower than expected. Can we improve performance without removing the SlowComponent? Absolutely! Before diving into solutions, let’s understand why components re-render in the first place.

Why does a React component re-render?

React operates on the core principle of View = f(State), meaning the view you see on the screen is a direct function of the application’s state. In simpler terms, React re-renders a view whenever the state changes. However, it doesn’t blindly re-render the entire view. Instead, it employs a clever optimization algorithm to determine precisely which parts of the view need updating based on the specific state change that occurred.

Several factors can prompt a React component to re-render, including:

State changes: A component will re-render whenever its internal state changes. This typically happens when a callback function calls the setState function, often within an effect.
Parent re-render: Children components are inherently bound to their parents. Whenever a parent component re-renders, its children will re-render as well, even if their own state or props haven’t changed.
Context changes: Components subscribing to a context will re-render whenever the context value is updated..
Hooks changes: Custom hooks often encapsulate state or context changes, which means their usage can indirectly trigger re-renders in the components that use them.

Common pitfall: Since a component is re-rendered when its props change, a common misconception is that it won’t do so if the props don’t change from the previous rendering. In reality, even with unchanged props, a component is re-rendered every time its parent re-renders.

1. Components Composition

Component composition is a fundamental concept in React that involves building complex UIs from smaller, reusable components. It also plays a crucial role in optimizing performance by managing state effectively. By keeping state close to where it’s used, we can minimize unnecessary re-renders throughout the application.

There are two main ways to leverage composition for performance benefits:

Moving state down
Encapsulating state

Moving state down

When a piece of state is only used by a single child component, it’s often inefficient to manage it in the parent. This can lead to the parent re-rendering even when the state change is only relevant to the child. We can improve this by “moving the state down” to the child component itself. This ensures that only the component directly responsible for the state triggers re-renders when it changes.

An example of this is the add task form. The value entered in the form’s input field (inputValue) is only relevant to the form itself. By moving the inputValue state to the form component, we prevent unnecessary updates in other parts of the application when the user types.

What’s changed in version 2: it creates an AddTaskForm component and pushes the inputValue state inside this new component. The result is that typing something in the input does not trigger a re-render for the whole app, but only for the AddTaskForm. An additional RenderCounter shows how many times the form re-renders while typing, instead the original counter does not update.

Encapsulating state

In some cases, state might seem relevant to child components, but upon closer inspection, we might realize it doesn’t actually affect their behavior. In such scenarios, we can encapsulate the state within a container component. This prevents child components from re-rendering unnecessarily due to parent state updates.

This is the case of background color in our example. While child components might be rendered within a container with a background color, they typically don’t interact with or rely on this value. By managing the background color state within the container component, we can avoid unnecessary re-renders in child components when the background color changes.

What’s changed in version 3: The following code creates a Container component that is responsible for changing the background color and rendering its children.

Composition: final refactor

As a demonstration of the power of composition, consider the following final refactor, which encapsulates all task management logic within a separate component (TasksView). By doing so, even actions such as adding tasks or marking them as done do not cause unnecessary re-renders of unrelated components, resulting in improved performance.

What’s changed in version 4: TasksView is responsible for the task management logic and encapsulates the state and the update function related to tasks.

2. Uncontrolled components

When implementing forms in React.js applications, the canonical approach involves using controlled components where React manages the form state. While this approach is straightforward and effective for many scenarios, it can lead to performance issues, especially with complex forms that trigger re-renders with each user input. To address this, developers can leverage uncontrolled components, allowing the DOM to handle form state management in certain situations.

Uncontrolled components provide an alternative to controlled components by relinquishing control of form state management to the DOM.

Uncontrolled form

In situations where the entire form state is not needed except for submission purposes, uncontrolled forms can be utilized. By relying on the DOM’s native form submit event, we can reduce unnecessary re-renders of the entire form, resulting in improved performance. However, it’s essential to ensure that all form inputs have proper names to capture their values during submission.

A common pitfall when using uncontrolled components is neglecting to provide names for all form inputs, which can prevent their values from being captured during form submission. Ensuring that all inputs have proper names is crucial for the correct functioning of the form.

What’s changed in version 5: The AddTaskForm is implemented using an uncontrolled approach, while the TaskView is identical to the one in the previous example. The form contains an additional SlowComponent that introduces a delay for operations on tasks but not when editing the form.

Uncontrolled components & state colocation

State colocation principles can be applied to uncontrolled components by managing state within individual input components or a subset of inputs. This approach improves rendering performance by minimizing the scope of state updates and re-renders. For example, validating input fields while typing or managing dependencies between fields can be achieved by maintaining state within the relevant input components.

What’s changed in version 6: a new TaskTextInput component is introduced to manage the input value and the validation while the form still relies on the submit event to get the input value.

It’s important to note that while uncontrolled components offer performance benefits, they may also present limitations. In the previous example, the form lost the reset functionality for form inputs. Developers should carefully consider these trade-offs and choose the approach that best suits their specific requirements and use cases.

3. memo, useMemo, useCallback

React provides three memoization techniques to improve the rendering performance. Memoization is a type of caching technique, specifically used to speed up algorithms by storing the results of expensive function calls to pure functions (eg. expensive calculations) and returning the cached result when the same inputs occur again. In React, memoization means caching values that persist beyond a single render, so that you can reuse them on the next render without recalculating the result.

The React documentation defines them as follows.

memo this High Order Component lets you skip re-rendering a component when its props are unchanged.
useMemo is a React Hook that lets you cache the result of a calculation between re-renders.
useCallback is a React Hook that lets you cache a function definition between re-renders.

While useMemo and useCallback serve similar purposes, they differ in the type of value they memoize. Both hooks cache values between re-renders to optimize performance; however, useMemo is used to memoize the result of a calculation (typically a variable), whereas useCallback is used to memoize the definition of a function. You could argue that functions are variables too and in fact memoizing them with useMemo is fully equivalent to doing it with useCallback but needs more code because of the required function wrapper. More on this can be found in Memoizing a function.

So how could we benefit from them?

memo

Optimizing with memo is only valuable when your component re-renders often with the same exact props, and its re-rendering logic is expensive. Remember the false myth “a component re-renders only when its props change”? Well, memo makes this statement true. When using memo React will apply a change detection algorithm to the component’s props to decide whether to reuse its memoized version or not. Otherwise the component will always be re-rendered when its parent does.

The SlowComponent in the example is a perfect fit for memo because it is rendered often without changing its props (it has no props).

What’s changed in version 7: For the sake of simplicity, the next version re-starts from version 5, the one without input validation. The app uses a memoized version of SlowComponent leveraging memo benefits on subsequent re-renders.

Why not always use memo?

Memoization techniques come with a cost. When rendering a memoized component, React keeps a cache for it that is ready to use for the next render. Caching values means to allocate memory space for it. Keeping in mind that memo is ineffective if props changes across renders, using it when not necessary increases the memory consumption of the application and creates many values that the garbage collector must clean potentially provoking a performance degradation.

So memo is valuable only when props changes are minimized. For this reason it’s important to know how React compares props. It performs a shallow equality, comparing each prop with the corresponding one. While primitive values behave “as expected” (the equality check succeeds if values are equals), when dealing with arrays, functions and objects, a shallow equality comparison takes in consideration variable references, not their values. If these variables are defined during rendering, their reference will be different at each render, making the comparison fail.

How to minimize props changes?

useMemo and useCallback

React provides hooks like useMemo and useCallback to help address this issue. We can leverage these memoization techniques to keep a stable reference to non-primitive variables. By using useMemo and useCallback strategically, you can prevent unnecessary re-calculations and reference changes within your React components, leading to improved performance when used in conjunction with memo.

In our code example, we could benefit from them by avoiding to re-render AddTasksForm and every task item when we add or we mark a task as complete.

What’s changed in version 8: the code is updated by adding a TaskItem component which is memoized and its props are kept stable by useCallback. The same technique is used for AddTaskForm. Additional RenderCounter are added to count how many times each task item renders.

The memo HOC (Higher-Order Component) is used to wrap AddTaskForm and TaskItem components. This creates memoized versions (MemoAddTaskForm and MemoTaskItem) that will only re-render if their props actually change. The useCallback hook keeps stable across rendering the reference for onAddTask and onToggleTask functions. The overall impact is noticeable because both adding and toggling a task does not require to re-render nor the form, nor the other task items. Instead, TasksView will re-render because its state, the list of tasks, changes.

4. Split large Context

React Context offers a built-in way to share state across components within the same tree, eliminating the need for tedious prop drilling. The official React documentation even suggests Scaling Up with Reducer and Context as a solution for managing shared state.

Context provides a way to share the state and update functions across components without passing props down the hierarchy. Reducer ensures a predictable and well-defined logic for updating the shared state.

However, Context has limitations:

Frequent re-renders: Updating the context triggers a complete re-render of all components that use it, including their children. This can become inefficient, especially with large context objects and many dependent components.
Potential for misuse: When dealing with complex state objects in Context, it’s easy to add unrelated properties over time. This can lead to a cluttered state and difficulty in managing updates.

For large-scale applications with frequently changing state, dedicated state management libraries like Redux, MobX, Zustand, etc. are generally better choices. These libraries offer efficient ways to handle state updates and minimize unnecessary re-renders.

Context remains a valuable tool when dealing with:

Small and focused scope: When the shared state affects a limited set of components, Context provides a clean and efficient solution.
Infrequent updates: If the state doesn’t change frequently, Context’s re-render behavior is less of a concern.

In essence, Context excels at sharing state within a well-defined scope and for occasional updates. But for complex state management in larger applications, consider dedicated state management libraries.

Let’s revisit the todo list example using Context.

What’s changed in version 9: Here’s a fresh implementation using Context as a shared state.

Our current context object mixes unrelated properties. Updating one triggers unnecessary re-renders in components reliant on others. Even components that don’t use the context directly can be impacted. With this approach every action provokes a full app re-render.

To fix this, we’ll split the context. Each new “slice” will group related properties that update together. We’ll also separate reading and update logic for better control.

What’s changed in version 10: It introduces 4 contexts ColorContext, InputContext, TasksContext, TasksDispatchContext.

Each context limits update scope, ensuring only relevant components re-render. While this refactoring adds more code compared to the previous version (it might seem like overkill for this simple example), it showcases how to prevent unnecessary re-renders with Context. Once split, it becomes clear that ColorContext and InputContext are only used by a single component. In such cases, replacing them with a local useState hook is a viable option.

This refactoring mirrors the concept of function composition, but applied to object composition.

What’s next: React Compiler and Automatic Optimizations

The future of React rendering looks even brighter with the introduction of the React Compiler (previously known as React Forget). This upcoming feature promises to automate many of the optimizations currently achieved with hooks like useMemo and useCallback. The compiler will analyze your component code and potentially inject optimizations to reduce unnecessary re-renders and improve performance. While the exact release date is still under development, this is a significant step towards a more streamlined and performant React development experience.

Keep in mind: While the React Compiler will likely simplify optimization tasks, understanding the fundamentals of reference values and memoization will remain valuable for React developers. This knowledge will help you write cleaner and more efficient code, and make informed decisions when to leverage the compiler’s capabilities.

Final advices

While waiting for React Compiler, let’s optimize components following principles that React team suggests that will be valuable also in future.

When a component visually wraps other components, let it accept JSX as children. This way, when the wrapper component updates its own state, React knows that its children don’t need to re-render.
Prefer local state and don’t lift state up any further than necessary. For example, don’t keep transient state like forms and whether an item is hovered at the top of your tree or in a global state library.
Keep your rendering logic pure. If re-rendering a component causes a problem or produces some noticeable visual artifact, it’s a bug in your component! Fix the bug instead of adding memoization.
Avoid unnecessary Effects that update state. Most performance problems in React apps are caused by chains of updates originating from Effects that cause your components to render over and over.
Try to remove unnecessary dependencies from your Effects. For example, instead of memoization, it’s often simpler to move some object or a function inside an Effect or outside the component.

How does React Router location.state works?

Mirco Bellagamba — Thu, 16 Feb 2023 11:00:00 +0000

The first time I saw the React Router location.state API, I thought it was a really useful feature, somewhat magical, as is often the case with things we don't understand.
This feature allows you to pass data from one route to another, for example to branch the UI depending on the previous route or to avoid fetching data already loaded on the previous page. The API designed by the React Router team is extremely simple and perfectly integrated with the methods defined by React, that is through the use of props and hooks.
You can set the location.state in 2 ways: via Link or via useNavigate.

<Link to="/users/123" state={{ fromLogin: true }} />;
// or
let navigate = useNavigate();
navigate("/users/123/edit", { data: partialUser });

Then, from the landing page you can retrieve the state via useLocation.

let location = useLocation();
location.state; // { fromLogin: true }

But where is the state stored?
Before delving into the documentation or directly into the library code, I wanted to have fun trying to deduce the nature of this feature only by observing its behavior.
I initially assumed that the Router uses a React State or a React Context to share the state between the Route components. This hypothesis was immediately denied by the fact that the state is maintained when the page is refreshed. This rules out the possibility that the state is only stored in the application's memory and implies the use of some persistence system.
This led me to speculate that WebStorage (sessionStorage or localStorage) or cookies were involved but, to my great regret, I found both were empty. I excluded IndexedDB because it's an advanced browser API and using it for this purpose would probably make little sense. Anyway, I checked to be sure and of course found it empty.
Seeing my analysis fail for a second time, I tried to investigate the browser features involved and I realized that I had left out one of the main objects responsible for client side navigation: the History, that allows to manipulate the browser session history. Let’s take a look at how it works.

let state = { fromLogin: true };
window.history.pushState(state, 'page2.html', url)

// in page2.html
window.history.state; // { fromLogin: true }

The first parameter of the function is the state used by React Router.
From the MDN documentation.

The state object is a JavaScript object which is associated with the new history entry created by pushState(). Whenever the user navigates to the new state, a popstate event is fired, and the state property of the event contains a copy of the history entry's state object. The state object can be anything that can be serialized.

Indeed, after using <Navigate state={...} /> the value of window.history.state is exactly the same as the prop of the same name.

The case is solved!🎉
Below you will find the main references to learn more about the topic and the link to the portion of React Router code that directly refers to the use of browser history, if you still feel skeptical.

Working with the History API
Main Concepts | React Router
index.ts - remix-run/history · GitHub

Implementing micro-frontends – A path to evolve legacy codebases

Mirco Bellagamba — Thu, 14 Apr 2022 11:05:04 +0000

Micro-frontends are the present and the future for scaling large client-side applications. Why should you implement this architectural style? Let’s dig into the reasons that led me and my team to adopt it.

Working at scale is one of the main goals of modern software engineering. Micro-frontends is an architectural style and a technique many organizations are adopting to address this problem. Generally speaking, the motivations for using this approach are basically the same that makes us choose micro-services in the “backend” world: breaking down a monolithic codebase into micro-apps, each of which developed by autonomous team, responsible for the entire lifecycle of this portion of the project.

This approach has the main benefits of improving the development process and the developer experience, because each team is focused on a smaller scope and it can independently deploy new features adapting to changes with a high velocity. In other words, micro-frontends inherit microservices well-known benefits such as development agility, technological freedom, and targeted deployments.

We pay for this high encapsulation of business rules and this high flexibility for each team with an increased effort for infrastructure since automation is one of the key requirements for a successful implementation. Modern cloud technologies greatly simplify this work and can be considered the enabling technologies for this architectural style. Despite this, a distributed system is intrinsically more complex than a monolithic one, because we must take in consideration aspects such as orchestration, distributed failures, observability, and automated deployments.

Objectives & Principles

For the purpose of the article, we can consider our initial architecture as a classic client-server application where the PHP server is responsible for generating HTML pages and JavaScript client side code is responsible for making these pages interactive. We need to evolve the user experience making the user interface more responsive and more app-like. We also need to improve the developer experience because maintaining this legacy codebase has become overwhelming and the team was not so fast to adapt to ever evolving requirements. The final objective of this architecture migration is to improve the user experience, modernize the user interface and speed up the development process, and we would achieve this purpose satisfying the following objectives:

Independent artifacts: team should be able to independently deploy their frontend applications with minimal impact to other services. Other teams should consider other micro-frontends more or less like a black box.
Easier maintenance: each micro-frontend module should be developed in isolation and the developer has lower cognitive load when developing a feature or debugging. Each micro-frontend has a separate and decoupled codebase from the others and each of them represents a business subdomain. For this reason it’s easier for a developer to become a (sub)domain expert.
Autonomous teams: each team should be responsible for making the right choices for its module.
Technology independence: the legacy framework and tooling should coexist with modern technologies allowing to evolve the codebase without struggling.
Scalable development: each micro-frontends should be independent from each other so each team could deploy at its own pace, increasing the development speed.

Challenges

As it often happens in software engineering, every choice comes at a cost or at least with some aspects to take into consideration. Choosing a micro-frontends architecture requires facing these challenges.

Parent/child integration: The micro-frontend architecture involves loading different modules to compose the UI of an application. This requires defining the communication modalities between the loaded micro-frontends that guarantee the performance, the consistency of the user experience that is expected from a monolithic application and, at the same time, the low coupling between the modules. Many of the implementation strategies involve creating an app shell that acts as an orchestrator of the micro-frontends.
Operational complexity: A micro-frontend application involves creating and managing separate infrastructure for all teams. Automation is a critical aspect of the implementation to ensure scalability of the system.
Consistent user experience: Child applications should use the same design system of the parent application. This could be particularly difficult when evolving a legacy application because sharing the same UI components and CSS libraries is not an option.

Implementation

First of all, let’s briefly describe the application domain which is useful to understand our choices.

Nuvola is a web application that offers a range of services that fully cover the needs of schools, from teaching to administration. Teachers use the software for teaching management, insert lesson topics, assignments, grades, absences, etc. Instead, the primary purpose for parents and pupils is to read the data entered by the teachers. Finally, the school secretariat uses it to fulfill administrative burdens, registration of documents, communications, personnel management, etc.

The core concept is to apply a Strangler Pattern in order to gradually eliminate the original application by replacing each sub-domain with a micro-frontend. Adopting the Pattern in combination with a micro-frontends architecture can enable the frontend team to independently deploy each application module and increase the parallelism of development.

We followed the Micro-frontends Decision Framework as a guide for top-level architectural choices. This is a super-short summary of our decisions.

Definition: vertical split. Every page displays a single micro-frontend and there’s an orchestration layer responsible for switching micro-frontends. We identified a subdomain with a type of user, so each micro-frontend is a micro-app serving a single type of user.
Composition: client side. A tiny layer of JavaScript code is responsible for loading micro-frontends on the page. In our architecture, switching between micro-frontends is a residual use case because it can happen only for users with different roles, like both teacher and parent in the same school.
Routing: client side. Since we compose micro-frontends client side, delegating the routing responsibility to the same JavaScript code is the go-to choice.
Communication: local storage. Previous choices aim to enforce encapsulation and minimize the need for communication between micro-frontends, so the only thing we need to share is authentication. In future developments, if the modules need to share something more, we will likely rely on a loose communication system, such as an event emitter.

We chose to attach parent and child using a run-time integration via javascript because it’s one of the most flexible ways to do that. Each micro-frontend exposes an entry point and a rendering function. The app shell knows the list of entry points of the available micro-frontends and is responsible for loading them on the page.

<html>
  <head>
    <title>Parent application</title>
  </head>
  <body>
    <script>
      const microFrontendEntries = {
        "/pupils-area": "https://pupils.frontend.madisoft.it/pupils.js",
        "/teachers-area": "https://teacher.frontend.madisoft.it/teacher.js",
        "/administrative-area":
          "https://administrative.frontend.madisoft.it/administrative.js",
      }
      const microFrontendScript = document.createElement("script")
      microFrontendScript.src = microFrontendEntries[window.location.pathname]
      document.body.appendChild(microFrontendScript)
    </script>
  </body>
</html>

This example is a basic implementation of the app shell. Once the micro-frontend is loaded on the page it renders the corresponding content. In our configuration, the app shell does not render anything: it’s only responsibility is to load and orchestrate micro-frontends.

Full disclosure: at the time of writing, each micro frontend is served by separate HTML pages, and the server is responsible for redirecting the user to the corresponding micro frontend HTML. Future release, will adopt the implementation described previously.

Deployment pipeline

AWS CodePipeline orchestrates the pipeline steps.

A new commit is pushed to the repository main branch, triggering the deployment.
AWS CodeBuild clones the latest version of the code from the repository and runs the build commands that install dependencies, transpile and minify code. The build step produces static assets: JS, SVG, CSS, HTML files.
Build output is transferred to an S3 bucket.
AWS CloudFront serves static assets to the parent application.

A side note on assets caching

A popular performance optimization technique for serving static assets is to set a long cache expiration time and generate dynamic file names by including the content hash. When connecting micro-frontends together, their entrypoint must be stable and can’t be dynamically generated with the content hash algorithm. So the solution we adopted is to generate a manifest file which maps the micro-frontend name with the dynamic name of the entry point. The manifest file must never be cached or, at most, it can be saved in a shared cache (CDN) that we can invalidate at each deployment.

Cache is configured on our S3 origin setting Cache-Control header appropriately.

Manifest file: Cache-Control: max-age=0, s-max-age=2592000 // 1 month on shared
All other assets: Cache-Control: max-age=31536000 // 1 year

Webpack Module Federation

On 10/10/2020, Webpack 5 was released. We are already distributing our first version of the micro-frontends solution based on the code previously presented. However This release is shipped with the Module Federation plugin which abstracts the parent child integration in a very effective way. Being a Wepack plugin, we just upgraded Webpack to version 5 and we were ready to use it.

Put it simply, Module Federation allows to assign to each module the role of host or remote.

Remote modules can be considered independent and expose one or more entry points.
Host modules are containers that know entry points of remote modules and can therefore use them.

There’s a lot more things going on but this is the core concept. For instance, Module Federation allows each module to be both remote and host at the same time or can handle shared libraries avoiding the user downloading shared libraries multiple times when it is a dependency of many micro-frontends on the page.

Here’s an example of configuration for a remote module.

const { ModuleFederationPlugin } = require("webpack").container
const deps = require("./package.json").dependencies

module.exports = {
  plugins: [
    new ModuleFederationPlugin({
      name: "RemoteApp",
      filename: "remoteEntry.js",
      exposes: {
        "./renderMFE": "./src/index",
      },
      shared: {
        react: {
          requiredVersion: deps.react,
          singleton: true,
        },
        "react-dom": {
          singleton: true,
          requiredVersion: deps["react-dom"],
        },
      },
    }),
  ],
}

This configuration declares a remote entry for a module called RemoteApp that exposes a renderMFE function. Moreover, it declares two shared libraries react, and react-dom.

It could seem counterproductive to share something between micro-frontends, instead, avoiding a multi-framework approach keeps the project more cohesive and more maintainable. However, we know this is a very valuable possibility because we probably need it during further steps of migration to allow the coexistence of jQuery and React, for the small period of time we need to completely migrate our codebase.

What's next?

At the time of writing this article, we have completed the migration of the parents and pupils area and we have noticed an increase in the use of this section by our users. This for us means that the update has been well received and has fixed at least some of the usability issues that made it less user-friendly. Secondly, we have seen a relative reduction in the cost of our cloud architecture due to adopting the API model compared to generating HTML on our main servers. Infrastructure costs have grown in absolute terms due to two factors. Our user base is constantly growing, more and more schools are choosing to use Nuvola as a management software and as an electronic register. The advent of the COVID-19 pandemic has generated greater use of our software which has represented the official software solution for communicating with schools during the distance learning period.

Given the excellent results obtained, we are already working on the migration of the other parts of the software using the same principles already implemented. Surely Webpack Module Federation will play a key role in this process and will be used for an even simpler and more immediate orchestration.

Grazie per aver letto fino a questo momento, condividerò maggiori dettagli del nostro percorso in post futuri. Continuate a seguirci nel nostro blog.

By Mirco Bellagamba, Software engineer, front end specialist.

Testing Library Recipes - Choosing query

Mirco Bellagamba — Wed, 05 May 2021 10:47:48 +0000

As frontend developers, we build software that lives in the browser. The DOM is the abstraction we rely on for creating user interfaces. Thus, testing a web application means making assertions about the DOM and its behavior.

Testing Library provides several query methods for obtaining a DOM element, each of which behaves differently and adapts to a specific context. Choosing the right query is a key skill in building robust and durable tests. Testing Library queries can be classified according to three main characteristics:

Type (get…, query…, find…): get… and query… are synchronous methods and the difference between them is whether the query will throw an error if no items are found. find… will return a Promise and wait for the element to be on the screen.
Quantity (…By…, …AllBy…): defines whether the query matches a single or multiple elements.
Selector (…Role, …LabelText, …Text, etc.): defines how to search the element.

We can choose both the type and the selector following an if (…) … else if () … else if (…) … chain. I know, there are a lot of design patterns for building scalable software architectures and the if else if chain is not one of the best, but I don't know how to refactor an article by applying the Strategy pattern 😅.

Choosing the Type

if (the element is in the document)

Pick the getBy… method.

This is the most common case. The element appears on the screen as soon as the component is rendered. The getBy… method throws an error if the element isn't on the screen or if more than one match is found, causing the test to fail. While it is tempting to use getBy… methods as "implicit assertion", it is best to write an explicit expectation for it.

import { render, screen } from "@testing-library/react"

test("should show login form", () => {
  render(<Login />)
  const input = screen.getByLabelText("Username")
  expect(input).toBeInTheDocument()
})

Advice: avoid using toBeDefined or other not explicit Jest matchers to verify that the element is visible on the screen. The @testing-library/jest-dom package provides the matcher toBeInTheDocument, which is the most expressive for doing this.

else if (the element will be in the document)

Pick the findBy… method.

This is the right choice if asynchronous operations are involved and the component renders the element when an asynchronous task ends or a promise is resolved. For example, if the element will be on the screen after a network request (during tests network requests will be mocked).

import { render, screen } from "@testing-library/react"

test("should show the product detail", async () => {
  render(<ProductDetail />)
  const price = await screen.findByText("20€")
  expect(price).toBeInTheDocument()
})

Advice: prefer find* over waitFor+get* to query something that may not be immediately available - it's simpler and the error message you get will be better.

// ❌
const submitButton = await waitFor(() =>
  screen.getByRole("button", { name: /submit/i })
)
// ✅
const submitButton = await screen.findByRole("button", { name: /submit/i })

else // the element is not in the document

Pick the queryBy… method.

The queryBy… methods are most appropriate when checking for the absence of an element. A queryBy… method returns null if the element is not on the screen, unlike getBy… which throws an error.

import { render, screen } from "@testing-library/react"

test("should show the product detail without any alert", () => {
  render(<ProductDetail />)
  const alert = screen.queryByRole("alert")
  expect(alert).not.toBeInTheDocument()
})

Advice: only use the query* variants for asserting that an element cannot be found.

Choosing the Quantity

if (querying multiple elements)

Pick the corresponding …AllBy… version of the choosen type of query.

The …AllBy… version of the query does not throw an error if multiple elements match but it returns an array of elements.

import { render, screen } from "@testing-library/react"

test("should show a list of products", () => {
  const products = [
    { id: 1, name: "Product 1" },
    { id: 2, name: "Product 2" },
    { id: 3, name: "Product 3" },
  ]
  render(<ProductsList products={products} />)
  const productListItems = screen.getAllByRole("listitem")
  expect(productListItems).toHaveLength(products.length)
})

Choosing the Selector

In this section I'll refer to the following component to write some example of tests.

// login.js
export default function Login() {
  return (
    <div>
      <h1>Login</h1>
      <img src="/logo.svg" width="100" height="100" alt="logo" />
      <p>Welcome user!</p>
      <form>
        <label>
          Username
          <input type="text" name="username" placeholder="Type the username" />
        </label>
        <label>
          Password
          <input type="text" name="password" placeholder="Type the password" />
        </label>
        <button type="submit">Login</button>
      </form>
      <span title="copyright">Copyright © 2021 Mirco Bellagamba</span>
    </div>
  )
}

if (the element is accessible by its role and name)

Pick …ByRole.

You should prefer the …ByRole selector over the others because it matches the items exposed in the accessibility tree. The name option allows you to specify its accessible name as well. If you can't get the item by its role and name, ask yourself if you're creating an inaccessible UI. Writing semantic HTML is a good starting point for building an accessible user interface. Assistive technologies, such as screen readers, recognize these elements and allow you to navigate the page in a structured way. For example, it is better to use a <button> instead of binding a click listener with a generic div.

import { screen } from "@testing-library/react"

const submitButton = screen.getByRole("button", { name: /login/i })

Advice #1: make sure your UI are always accessible for everyone. Check out the list of Accessible Roles on MDN.

Advice #2: I personally find RegExp really useful for matching element name or text without worrying about the case of characters. RegExps are really powerful but it's best not to rely on them too much: using them we are able to match almost anything and large RegExps could lead to poor testing.

else if (the element is a form input with a label)

Pick …ByLabelText.

Getting an element by the label text is the best way to get form fields. This method is not very useful for other HTML elements but it should be your preference for inputs because it requires you to provide a label for it.

import { screen } from "@testing-library/react"

const username = screen.getByLabelText("Username")
const password = screen.getByLabelText("Password")

else if (the element is a form input without a label)

Pick …ByPlaceholder.

If you can't provide a label or can't use the label text to identify form fields, try getting them through placeholder text. Like the previous selector, it is only useful for input elements.

import { screen } from "@testing-library/react"

const username = screen.getByPlaceholderText(/username/i)
const password = screen.getByPlaceholderText(/password/i)

else if (the element is a non-interactive element)

Pick …ByText.

This is the best way to get non-interactive elements, like div and span. You shouldn't use it for form elements, buttons, or any element that could be obtained with a …ByRole query. You may be tempted to use it every time, because it is easier to match texts than to match accessible role and name, but in this way your tests will be more fragile and you lose any guarantee on the accessibility of your page.

import { screen } from "@testing-library/react"

const welcomeText = screen.getByText(/welcome/i)

else if (the element is an input with a display value)

Pick …ByDisplayValue.

This is an alternative method for getting inputs. The docs says:

The current value of a form element can be useful when navigating a page with filled-in values.

Until now I have never faced a situation that made this method my preferred choice because I prefer to get an input from the text of its label and make an assertion about its value rather than getting it from its display value. However it could be useful when external libraries are involved or when we are unable to modify the input to make it accessible via the label text (this is very sad 😢).

import { screen } from "@testing-library/react"

const username = screen.getByDisplayValue("mircoBellaG")

else if (the element supports an alt text)

Pick …ByAltText.

This method is useful to get elements supporting alt text (img, area and input).

import { screen } from "@testing-library/react"

const logoImg = screen.getByAltText("logo")

else if (the element has a title attribute)

Pick …ByTitle.

The title attribute is not consistently read by screenreaders, and is not visible by default for sighted users. For this reason, tests that use it give you less confidence than those that aren't. It could also be used to get SVG from its title.

import { screen } from "@testing-library/react"

const copyrightText = screen.getByTitle("copyright")

else

Pick …ByTestId.

If nothing else doesn't fit your element, you should give it a data-testid attribute and use it in your tests. This is the case for elements the user cannot see (or hear), so this is only recommended for cases where you can't match by role or text or it doesn't make sense (e.g. the text is dynamic). While it's easier to create tests using this method by default, try using it only if it's actually difficult or impossible to do otherwise. Using testids makes tests more prone to false positives because it doesn't assert anything about the structure of your UI. However, it is still a good option for many cases like localized apps, loading spinners, mocked elements.

import { screen } from "@testing-library/dom"

const element = screen.getByTestId("custom-element")

Advice: Before adding a data-testid you should always ask yourself: "Why do I need to get an element that the user is not aware of? Am I testing an implementation detail?".

Helpers and manual queries

There are Testing Library helper methods that work with queries. As elements appear and disappear in response to actions, Async APIs like waitFor or findBy queries can be used to await the changes in the DOM. To find only elements that are children of a specific element, you can use within. If necessary, there are also a few options you can configure, like the timeout for retries and the default testID attribute.

Advice: Use within helper to test your modal or your accordion items but it should not be used frequently because it ties your tests to the page structure. Do not use it as a shortcut to test implementation details (I know you miss the shallow rendering from Enzyme 😜).

As final note, remember that you are running test in the DOM and you can use the regular querySelector DOM API to query elements. However, it's better to use a testid if you have to, to make your intention to fall back to non-semantic queries clear and establish a stable API contract in the HTML.

Testing Playground

Still not sure which query to use? Testing Playground can help you choose the right query. It is a super useful tool that suggests Testing Library queries for the selected item. You can download it as Chrome Extension or as Firefox Extension and directly run for the app you are developing!

Code reference

Check out https://github.com/mbellagamba/testing-library-recipes if you want to understand how to use in practice Testing Library queries. The example in the folder 1-choosing-query contains a test exploring all the query methods.

Conclusion

As developers, we love algorithms and code. So, why not write an algorithm for choosing testing libraries query?

function getQuery() {
  return getQueryType() + getQueryQuantity() + getQuerySelector()
}

function getQueryType() {
  if (isInTheDocument()) {
    return "get"
  } else if (willBeInTheDocument()) {
    return "find"
  } else {
    // The element is not in the document
    return "query"
  }
}

function getQueryQuantity() {
  if (areThereMultipleElements()) {
    return "All"
  } else {
    return ""
  }
}

function getQuerySelector() {
  if (isAccessibleByItsRoleAndName()) {
    return "ByRole"
  } else if (isAccessibleByItsLabelText()) {
    return "ByLabelText"
  } else if (isAnInputWithAPlaceholder()) {
    return "ByPlaceholder"
  } else if (isNonInteractiveText()) {
    return "ByText"
  } else if (isAnInputWithAValue()) {
    return "ByDisplayValue"
  } else if (hasAnAltText()) {
    return "ByAltText"
  } else if (hasATitleAttribute()) {
    return "ByTitle"
  } else {
    return "ByTestId"
  }
}

It's just a funny joke, but it helps me figure out which query I should use.

The most important concept is to avoid testing the internal behavior of components and emulate users as much as possible. Testing Library is not designed to test implementation details because it makes your tests fragile. If you try to do this, the library will fight you by making it very complex. This is one of the things I love most about Testing Library.

Happy testing and always remember the Guiding principles!

Further references

Check out these super useful resources for a deeper understanding.

React Testing Library Recipes - Getting started

Mirco Bellagamba — Fri, 09 Apr 2021 15:18:36 +0000

Automated software testing has become a critical organization process within software development to ensure that expected business systems and product features behave correctly as expected. When developing a React.js front-end application, the React Testing Library is the officially recommended tool and it is the primary choice for many developers because it encourages good practices by enforcing not to test implementation details, but by focusing on tests that closely resemble how your web pages are interacted by the users.

This is the very first article of a series talking about best practices in testing front-end applications using the React Testing Library. Even if you are not a React.js developer, you can find useful information because the underlying concepts are the same of the Core Testing Library.

If you are not familiar with the theory of software testing, or you don't know the meaning of concepts like unit test, integration test, stub, mock, test doubles, you should take a look to some Software Testing reference, just to make sure to speak the same language.

The best place to start learning how to test a React web application is probably the official documentation:

Although the official documentation is great, I found myself too many times digging the web for the perfect setup, trying to understand in which way my tests will be robust and give me confidence about the code I wrote. My journey with Testing Library started two years ago and since that time I widely experimented its features and its limits. I want to share this experience and my personal test recipes.

At the end of the article, I share with you a repository that you can use as reference or as template to setup your project.

Let's start simple from the foundation concepts.

Basic concepts

An automated test is just a code checking the correctness of another piece of code. But how should you write this code? A common way to setup tests is the Arrange-Act-Assert pattern: a pattern for arranging and formatting code in UnitTest methods.

Arrange all necessary preconditions and inputs.
Act on the object or method under test.
Assert that the expected results have occurred.

For example, this code is a simple test.

function sum(numbers: number[]): number {
  return numbers.reduce((partial, current) => partial + current, 0);
}

function shouldSumAllNumbers() {
  // Arrange
  const input = [1, 2, 3];

  // Act
  const output = sum(input);

  // Assert
  if (output !== 6) {
    throw new Error(`Test failed. Expected: 6, Actual: ${output}.`);
  }
}

If you're asking... Yes, it's not very different from the "sum test" you have probably already seen on every other introductory resource on testing 😴. I promise to talk about more interesting stuff later on.
Even if not required, as I showed previously, writing and executing tests is way easier using frameworks or a set of testing utilities, especially for writing more complex tests, as those involving the DOM. So, let's set up our test environment.

Setup the environment

Depending on your project setup, you'll need some initial configuration to run tests on your React application.

Install required dependencies
Setting up the testing framework
Start testing!

Projects created with Create React App have out of the box support for React Testing Library, you can skip to fine tuning. Projects created with other tool chains like Next.js, Gatsby.js needs this steps. If you are a complete beginner, it's probably better to pick CRA and start testing without caring about configuration. If you are setting up a custom toolchain then these steps could be really useful.

This guide makes some assumptions:

Babel transpiles JS/TS files and it is configured with the TypeScript preset.
Webpack is used as bundler.
The files structure is like the following.

project-root/       // The root directory
 |-src/             // Contains the JS/TS source code
 |-test/            // Contains test config and utilities
   |-config/        // Contains test config files
   |-setupTests.js // The test env setup file

If you use a different setup, this guide could still work but you probably need to tweak some pieces, such as file paths. If you need a more advanced setup, you could check out Jest - Using with webpack.

1. Install dependencies

First of all, let's install required npm packages.

npm i -D jest babel-jest @testing-library/jest-dom @testing-library/react @testing-library/user-event

What have we just installed?

jest: the testing framework. It provides the test environment, a command line tool, a simulated DOM, functions for defining tests (describe, it, test, etc.), mocking and spying utilities, functions for assertions and expectations.
babel-jest: it transpiles JS files in tests. It requires @babel/core is installed. Babel is a popular JavaScript transpiler, but how to configure Babel for your project is out of the scope of this article.
@testing-library/react: it builds on top of DOM Testing Library by adding APIs for working with React components.
@testing-library/jest-dom: provides custom DOM element matchers for Jest. It extends the set of expectations we can use.
@testing-library/user-event: it is a companion library for Testing Library that provides more advanced simulation of browser interactions than the built-in fireEvent method. It is not required, but it is highly recommended.

2. Configure Jest

Jest aims to work out of the box, config free, on most JavaScript projects. But in spite of this, I prefer to customize the configuration to support these 3 features.

Add support for testing library and TS files.
Stub file imports
Stub CSS imports

Jest config file

Create a jest.config.js file in the project root directory.

module.exports = {
  verbose: true,
  roots: ["<rootDir>/src"],
  collectCoverageFrom: ["src/**/*.{js,jsx,ts,tsx}", "!src/**/*.d.ts"],
  setupFilesAfterEnv: ["<rootDir>/test/setupTests.js"],
  testMatch: [
    "<rootDir>/src/**/__tests__/**/*.{js,jsx,ts,tsx}",
    "<rootDir>/src/**/*.{spec,test}.{js,jsx,ts,tsx}",
  ],
  testEnvironment: "jsdom",
  transform: {
    "^.+\\.(js|jsx|mjs|cjs|ts|tsx)$": "<rootDir>/node_modules/babel-jest",
    "^.+\\.css$": "<rootDir>/test/config/cssTransform.js",
    "^(?!.*\\.(js|jsx|mjs|cjs|ts|tsx|css|json)$)":
      "<rootDir>/test/config/fileTransform.js",
  },
  transformIgnorePatterns: [
    "[/\\\\]node_modules[/\\\\].+\\.(js|jsx|mjs|cjs|ts|tsx)$",
    "^.+\\.module\\.(css|sass|scss)$",
  ],
  moduleFileExtensions: [
    "web.js",
    "js",
    "web.ts",
    "ts",
    "web.tsx",
    "tsx",
    "json",
    "web.jsx",
    "jsx",
    "node",
  ],
  resetMocks: true,
};

This configuration file instruct Jest about:

Log verbosity: verbose, I like to see what's happening 🕵️.
Source code roots: the src folder.
Code coverage sources: JS/TS file excluding TS declaration files.
Environment setup file: the setupTests.js file. We'll see it later.
Test sources: every file whose name ends with .test.js, .spec.js or corresponding TS, JSX, TSX variations. Also files within a __tests__ folder are included.
Test environment: Jest DOM
File transformers: JS/TS files are processed by Babel, CSS files and other files will require custom transformers we'll see later.
Transform ignore files: we avoid transforming source files from node_modules and CSS modules.
Module file extensions: the module file extensions we support.
Reset mocks: true, Jest automatically resets mocks after tests.

Jest setup file `setupTests.js`

Create a setupTests.js file in /test/.

import "@testing-library/jest-dom";

It instructs Jest with Testing Library custom matchers.

CSS transformer

Create the file /test/config/cssTransform.js.

"use strict";

module.exports = {
  process() {
    return "module.exports = {};";
  },
  getCacheKey() {
    // The output is always the same.
    return "cssTransform";
  },
};

This is a custom Jest transformer turning style imports into empty objects. In our tests, we does not need to import real CSS files.

File transform

Create the file /test/config/fileTransform.js.

"use strict";

const path = require("path");
const camelcase = require("camelcase");

module.exports = {
  process(src, filename) {
    const assetFilename = JSON.stringify(path.basename(filename));

    if (filename.match(/\.svg$/)) {
      const pascalCaseFilename = camelcase(path.parse(filename).name, {
        pascalCase: true,
      });
      const componentName = `Svg${pascalCaseFilename}`;
      return `const React = require('react');
      module.exports = {
        __esModule: true,
        default: ${assetFilename},
        ReactComponent: React.forwardRef(function ${componentName}(props, ref) {
          return {
            $$typeof: Symbol.for('react.element'),
            type: 'svg',
            ref: ref,
            key: null,
            props: Object.assign({}, props, {
              children: ${assetFilename}
            })
          };
        }),
      };`;
    }

    return `module.exports = ${assetFilename};`;
  },
};

Importing real file assets is something we do not care in testing. This custom Jest transformer is responsible for:

Turning SVG files into Component or string. In our app we could import SVG both with import svg from '../path/to/asset.svg' and import { ReactComponent as Asset } from '../path/to/asset.svg'.
Turning other assets (images, videos, etc.) as strings.

Start testing your components

Now that Jest is installed and configured we can set up the test script. In your package.json add or update the test script to run jest. There's no need of additional command line parameters since the configuration file take care of the customizations.

// package.json
{
  "scripts": {
    "test": "jest"
  }
}

Run tests in watch mode launching npm test -- --watch (or npx jest --watch) in the command line.

Now our test environment is ready 🙌. Let's write our first test.

Given this App component:

function App() {
  return (
    <div>
      <h1>Testing Library Recipes</h1>
      <a href="https://testing-library.com/">Getting Started</a>
    </div>
  );
}
export default App;

This test ensures that the page renders a link.

import { render, screen } from "@testing-library/react";
import App from "./App";

it("Should contain a link", () => {
  render(<App />);
  const linkElement = screen.getByRole("link", { name: /getting started/i });
  expect(linkElement).toBeInTheDocument();
});

The test does not rely on any implementation detail but it makes assumptions only on what final users actually see, as states the guiding principle of Testing Library.

The more your tests resemble the way your software is used, the more confidence they can give you.

Running npm test the console output should be like the following.

> jest

 PASS  src/App.test.tsx
  ✓ Should contain a link (71 ms)

Test Suites: 1 passed, 1 total
Tests:       1 passed, 1 total
Snapshots:   0 total
Time:        1.726 s
Ran all test suites.

Bonus: Run tests on commit

A test environment is really effective only if tests run frequently. The best way to do that is to set up a Continuous Integration server that automatically run tests at every push. Besides that, it could be useful to run tests even before each commit. This give you a faster feedback, and it prevents you from committing not working code.
Husky is a powerful tool that helps us to configure Git hooks to achieve this result.

Let's install and init Husky in our project! This command installs Husky as dev dependency and it adds a prepare script in our package.json.

npx husky-init && npm install

You should have a new prepare script in your package.json. If you don't see it, add it manually.

// package.json
{
  "scripts": {
    "prepare": "husky install"
  }
}

Install husky hooks running the prepare script (or you can directly run npx husky install).

npm run prepare

Then we need to create a Git pre-commit hook. This pre-commit hook runs npm test just before the commit.

npx husky add .husky/pre-commit "npm test"

If npm test command fails, your commit will be automatically aborted.

As your test suite grows, the execution time could slow down your development process. Running all tests in your local machine before every single commits could become a waste of time. In that case, running tests on a Continuous Integration server is probably the better choice. However, it shouldn't be an all or nothing approach: you can keep fast tests on your pre-commit hook (unit tests) and move slower ones on the CI process (end-to-end tests).

GitHub Actions

GitHub Actions provide an easy way to automate software workflows, including Continuous Integration, and it is free for public repositories.
Setting up a GitHub Action that run tests on push is really common workflow, and GitHub suggests a Node.js template for this if you switch to the Actions tab on your GitHub repository page. However, you can set up it manually and achieve the same result even before pushing your code to GitHub.
For this CI action, GitHub needs a workflow configuration file, which defines the environment and the commands to run.

To get started quickly, create a node.js.yml file in .github/workflows directory of your repository. The file content should be like this.

name: Node.js CI

on:
  push:
    branches: [$default-branch]
  pull_request:
    branches: [$default-branch]

jobs:
  build:
    runs-on: ubuntu-latest

    strategy:
      matrix:
        node-version: [12.x, 14.x, 15.x]

    steps:
      - uses: actions/checkout@v2
      - name: Use Node.js ${{ matrix.node-version }}
        uses: actions/setup-node@v1
        with:
          node-version: ${{ matrix.node-version }}
      - run: npm ci
      - run: npm run build --if-present
      - run: npm test

Remember to replace $default-branch with the name of your default branch (es. main / master).

This workflow will do a clean install of node dependencies, build the source code and run tests across different versions of node. For more information see Using Node.js with GitHub Actions.
This template will fit most use cases, but you can customize the CI process depending on your needs. You can read more on this directly on Github Actions Docs.

Wrapping up

Getting ready for testing requires these steps:

Install Jest, Testing Library and all the required dependencies
Configure Jest
Configure Git hooks
Set up a GitHub Action

I leave you with a project template that you can use as reference. This is a custom development toolchain which includes React Testing Library, Jest, Husky, TypeScript, Babel, Webpack, React.

https://github.com/mbellagamba/testing-library-recipes

Happy testing! 😃

Data fetching React Hook

Mirco Bellagamba — Mon, 22 Mar 2021 15:24:10 +0000

Making HTTP requests is a common task for most Single Page Applications. Due to the asynchronous nature of network requests, we need to manage the state of the request during its lifecycle: the start, the loading phase and finally the processing of the response or errors handling, if any occurred.

The problem

Today it is more and more frequent to start a new React.js web app without using any external state management library, such as Redux, but just relying on the React State and the React Context. Since React.js 16.8 was released, this trend increased even more because the introduction of the Hooks simplified the Context APIs, making them more appealing from a developer point of view.
In this kind of web app a React component making a network request could look like the following.

import * as React from "react"
import { topicsURL } from "./api"

function TopicsList() {
  const [topics, setTopics] = React.useState([])
  const [loading, setLoading] = React.useState(false)
  const [error, setError] = React.useState(null)
  React.useEffect(() => {
    setLoading(true)
    fetch(topicsURL)
      .then(response => {
        if (!response.ok) {
          throw new Error("Request failed")
        }
        return response.json()
      })
      .then(data => setTopics(data))
      .catch(e => setError(e))
      .finally(() => setLoading(false))
  }, [])

  if (error) {
    return <div>An error has occurred: {error.message}</div>
  }
  if (loading) {
    return <div>Loading...</div>
  }
  return (
    <ul>
      {topics.map(topic => (
        <li key={topic.id}>
          <a href={topic.url}>{topic.title}</a>;
        </li>
      ))}
    </ul>
  )
}

The TopicsList component is fairly good but most of its code deals with the management of the network request, hiding its real purpose: showing a list of topics. It smells like a separation of concerns issue.
Moreover, the same code will be duplicated in many other components, modifying only the request URL. Each component will declare three state variables, make the request inside an effect, manage the loading state, conditionally render the component only when the request is successful.
Finally, the request status depends on the value of three variables (topics, loading, error). It's easy to mess up things just checking these variables with the wrong order. To better understand the problem, check the article Stop using isLoading booleans.

The `useFetch` Hook

We could solve the issues previously described defining a custom hook that manages network requests. Our goals are:

Avoid rewriting the logic to manage requests.
Separate the request management code from the rendering.
Handle the request status in an atomic way.

import * as React from "react"

const reducer = (state, action) => {
  switch (action.type) {
    case "loading":
      return {
        status: "loading",
      }
    case "success":
      return {
        status: "success",
        data: action.data,
      }
    case "error":
      return {
        status: "error",
        error: action.error,
      }
    default:
      return state
  }
}

export function useFetch(url) {
  const [state, dispatch] = React.useReducer(reducer, { status: "idle" })
  React.useEffect(() => {
    let subscribed = true
    dispatch({ type: "loading" })
    fetch(url)
      .then(response => {
        if (!response.ok) {
          throw new Error("Request failed")
        }
        return response.json()
      })
      .then(data => {
        if (subscribed) {
          dispatch({ type: "success", data })
        }
      })
      .catch(error => {
        if (subscribed) {
          dispatch({ type: "error", error })
        }
      })
    return () => {
      subscribed = false
    }
  }, [url])
  return state
}

The useFetch hook is a useful abstraction and it can be easily shared among the components of the app. The request status depends on the single status variable, instead of three. The subscribed variable prevents a component update on an unmounted component, when the unmount event happens before the request completion.
No one is happy to see this warning in browser console.

Warning: Can’t call setState (or forceUpdate) on an unmounted component. This is a no-op, but it indicates a memory leak in your application. To fix, cancel all subscriptions and asynchronous tasks in the componentWillUnmount method.

Using the hook

With the useFetch hook the TopicsList component becomes like this.

import { useFetch, topicsURL } from "./api"

function TopicsList() {
  const res = useFetch(topicsURL)
  return (
    <>
      {res.status === "loading" && <div>Loading...</div>}
      {res.status === "error" && (
        <div>An error has occurred: {res.error.message}</div>
      )}
      {status === "success" && (
        <ul>
          {res.data.map(topic => (
            <li key={topic.id}>
              <a href={topic.url}>{topic.title}</a>
            </li>
          ))}
        </ul>
      )}
    </>
  )
}

The code is more readable because it sharply defines the component purpose. Now the rendering logic is separated from request management and there's no mixed level of abstractions.

Bonus #1: TypeScript version

For type safety lovers (here I am ✋), here's the TypeScript version.

import * as React from "react"

export type RequestState<T> =
  | { status: "idle" }
  | { status: "loading" }
  | { status: "success"; data: T }
  | { status: "error"; error: Error }

export type RequestAction<T> =
  | { type: "start" }
  | { type: "completed"; data: T }
  | { type: "failed"; error: Error }

export function useFetch<T>(route: string): RequestState<T> {
  const [state, dispatch] = React.useReducer<
    React.Reducer<RequestState<T>, RequestAction<T>>
  >(reducer, { status: "idle" })
  React.useEffect(() => {
    let subscribed = true
    if (route) {
      dispatch({ type: "start" })
      fetch(route)
        .then(response => {
          if (!response.ok) {
            throw new Error("Request failed")
          }
          return response.json()
        })
        .then(data => {
          if (subscribed) {
            dispatch({ type: "completed", data })
          }
        })
        .catch(error => {
          if (subscribed) {
            dispatch({ type: "failed", error })
          }
        })
    }
    return () => {
      subscribed = false
    }
  }, [route])
  return state
}

export function reducer<T>(
  state: RequestState<T>,
  action: RequestAction<T>
): RequestState<T> {
  switch (action.type) {
    case "start":
      return {
        status: "loading",
      }
    case "completed":
      return {
        status: "success",
        data: action.data,
      }
    case "failed":
      return {
        status: "error",
        error: action.error,
      }
    default:
      return state
  }
}

Then it could be useful to define an helper function with proper typing for each request, instead of using the hook directly in components. The topics request would be like this.

function useTopics(): RequestState<Topic[]> {
  return useFetch(topicsURL)
}

The Union type enforces us to check the status of the response before accessing any other properties. Writing res.data is allowed only if the language is sure that the status is "success" in the same scope. So, thanks to TypeScript, we can forget about mistakes like Uncaught TypeError: Cannot read property 'map' of undefined.

Bonus #2: Testing tips

The useFetch hook could help us to simplify unit tests. In fact, we can spy on the hook and return a proper test double. Testing the component becomes easier because the hook spy hides the asynchronous behavior of fetch requests, serving directly the response.
The stub let us reason about the component behavior and the test expectation without worrying about async execution.
Assuming to use Jest and Testing Library, a unit test for the topics list component could be like the following.

import * as React from "react"
import { render, screen } from "@testing-library/react"
import TopicsList from "../TopicsList"
import * as api from "../api"

const testData = Array.from(Array(5).keys(), index => ({
  id: index,
  title: `Topic ${index}`,
  url: `https://example.com/topics/${index}`,
}))

test("Show a list of topic items", () => {
  jest.spyOn(api, "useTopics").mockReturnValue({
    status: "success",
    data: testData,
  })
  render(<TopicsList />)
  expect(screen.getAllByRole("listitem")).toHaveLength(testData.length)
})

Even if there are alternatives to mocking fetch requests in tests Stop mocking fetch, this approach can be useful in complex situations when setting up an asynchronous unit test would be tricky.

Going further

The useFetch hook is a handy utility to retrieve data from the server and to manage network requests. It is simple enough yet quite powerful. Anyway, it is not perfect for every use case and I would leave you with some considerations.

The custom hook can be easily modified to work with any asynchronous task, i.e. with every function returning a Promise. For instance, its signature can be like the following.

function useAsync<T>(task: Promise<T> | () => Promise<T>): AsyncState<T>`

It is easy to replace the native fetch with Axios. There's only need to remove the code that checks if the response is successful and parse the JSON response body because Axios does it internally.
If the API endpoint require some headers, like Authorization, you can define a custom client function that enhance fetch requests with required headers and replace fetch with this client.
In complex web apps, making a lot of network requests, requiring advanced features like caching, it will probably be better to use React Query, a powerful React data synchronization library.

Connect

Do you find it useful? Do you have any question about it? Feel free to comment or contact me. You can reach me out on Twitter @mircobellaG.

JavaScript image compression and resizing

Mirco Bellagamba — Sun, 14 Mar 2021 13:54:16 +0000

Uploading and downloading images is a very common feature in modern web applications but exchanging files between client and server can quickly become a high resource consuming task. We must also consider that most Internet traffic comes from mobile devices, so we can expect users to upload photos taken with their phones. Those files can be very heavy (> 10MB) because of the ever increasing camera resolution on new mobile devices.

Sharing images in your platform means that users upload their photos to your storage server and then other users download those photos to use them somehow. This task involves much more resources compared to storing a new record in the database. We can expect an higher cost in terms of:

Upload bandwidth.
Download bandwidth. In a typical use case, there are many downloads for each image uploaded.
Storage. Photos and files are typically stored in a disk or in some object storage service. It's important to note that once you save a photo in your storage you must keep it stored throughout the lifetime of the software unless you apply some deletion policy. For this reason storage costs always increase during time, in contrast to bandwidth costs that depend on current usage.

Due to the pandemic emergency for COVID 19, in the period between March and June 2020, Nuvola has become the main hub for teachers, pupils and parents. This situation results in a rapid increase in traffic, as we have already talked about in a previous article. Furthermore, the needs of schools have changed to address distance learning. For example, students should send homework to teachers and teachers should send corrections back. Until now, this functionality was not needed because this process was done physically in the classroom. This new feature clearly implies file sharing. Talking with our customers we discovered that users prefer to do their homework in their exercise book, take a picture and share it on the platform. This means that most of the shared files are images and, for this reason, the benefit of image compression will be really huge.

How can image sharing be optimized?

The obvious answer is image compression. However, if image quality is your software primary concern, this technique is probably not right for you. A common solution involves server-side compression, reducing download bandwidth and storage space required. However this approach leads to increased CPU cycles which means an additional cost, even though probably less expensive than download bandwidth.

Thanks to modern browser API we can also reduce unnecessary upload bandwidth compressing images client-side, before uploading them. Reducing bandwidth also means a faster upload because compression time is much smaller than a large file upload request over network.

HTML5 features such as Canvas, FileReader and Blob allow compressing images directly in the browser, resulting in a lower number of bytes the platform needs to upload, store and download.

A little bit of context from MDN

The Canvas API provides a means for drawing graphics via JavaScript and the HTML canvas element. Among other things, it can be used for animation, game graphics, data visualization, photo manipulation, and real-time video processing. The Canvas API largely focuses on 2D graphics. The WebGL API, which also uses the <canvas> element, draws hardware-accelerated 2D and 3D graphics.

The FileReader object lets web applications asynchronously read the contents of files (or raw data buffers) stored on the user's computer, using File or Blob objects to specify the file or data to read. File objects may be obtained from a FileList object returned as a result of a user selecting files using the input element, from a drag and drop operation's DataTransfer object, or from the mozGetAsFile() API on an HTMLCanvasElement.

The Blob object represents a blob, which is a file-like object of immutable, raw data; they can be read as text or binary data, or converted into a ReadableStream so its methods can be used for processing the data. Blobs can represent data that isn't necessarily in a JavaScript-native format. The File interface is based on Blob, inheriting blob functionality and expanding it to support files on the user's system.

Image compression steps

Read the file using an <input> element with type="file"

   const input = document.getElementById(‘input’);
   input.onChange = function(ev) {
   const file = ev.target.files\[0\];
   // Use the file
   };

Create a Blob with the file data and get its URL with createObjectURL

const blobURL = window.URL.createObjectURL(file)

Create an helper image object and use the blob URL as source

const img = new Image()
img.src = blobURL

Use the onload callback to process the image

img.onload = function (ev) {
  window.URL.revokeObjectURL(blobURL) // release memory
  // Use the img
}

Create a canvas element setting the width and height to match the new dimensions of the image.

const canvas = document.createElement(‘canvas’);
canvas.width = newWidth;
canvas.height = newHeight;

Create a 2D context object and draw the image on the canvas

const ctx = canvas.getContext(‘2d’);
ctx.drawImage(img, 0, 0, newWidth, newHeight);

Export the image with the desired output quality

canvas.toBlob(
  function (blob) {
    // Handle the compressed image
  },
  mimeType,
  quality
)

mimeType is the mime type of the result image, like image/jpeg, image/png . Value of quality ranges from 0 to 1 and represents the quality of the output image. If you don't specify the mime and quality in the toBlob() method then default quality will be set and the mime type will be image/png. HTMLCanvasElement.toBlob is not fully supported by all browsers, see the polyfill section below.

(Optional) Show the compressed image in the document

document.body.append(canvas)

Polyfill canvas.toBlob

A low performance polyfill based on toDataURL.

  if (!HTMLCanvasElement.prototype.toBlob) {
    Object.defineProperty(HTMLCanvasElement.prototype, "toBlob", {
      value: function (callback, type, quality) {
        var binStr = atob(this.toDataURL(type, quality).split(",")[1]),
          len = binStr.length,
          arr = new Uint8Array(len);
        for (var i = 0; i < len; i++) {
          arr[i] = binStr.charCodeAt(i);
        }
        callback(new Blob([arr], { type: type || "image/png" }));
      },
    });
  }
}

Source: MDN

Final code

Try the JS image resizing tool on Codepen.

<div id="root">
  <p>Upload an image and see the result</p>
  <input id="img-input" type="file" accept="image/*" style="display:block" />
</div>

const MAX_WIDTH = 320
const MAX_HEIGHT = 180
const MIME_TYPE = "image/jpeg"
const QUALITY = 0.7

const input = document.getElementById("img-input")
input.onchange = function (ev) {
  const file = ev.target.files[0] // get the file
  const blobURL = URL.createObjectURL(file)
  const img = new Image()
  img.src = blobURL
  img.onerror = function () {
    URL.revokeObjectURL(this.src)
    // Handle the failure properly
    console.log("Cannot load image")
  }
  img.onload = function () {
    URL.revokeObjectURL(this.src)
    const [newWidth, newHeight] = calculateSize(img, MAX_WIDTH, MAX_HEIGHT)
    const canvas = document.createElement("canvas")
    canvas.width = newWidth
    canvas.height = newHeight
    const ctx = canvas.getContext("2d")
    ctx.drawImage(img, 0, 0, newWidth, newHeight)
    canvas.toBlob(
      blob => {
        // Handle the compressed image. es. upload or save in local state
        displayInfo("Original file", file)
        displayInfo("Compressed file", blob)
      },
      MIME_TYPE,
      QUALITY
    )
    document.getElementById("root").append(canvas)
  }
}

function calculateSize(img, maxWidth, maxHeight) {
  let width = img.width
  let height = img.height

  // calculate the width and height, constraining the proportions
  if (width > height) {
    if (width > maxWidth) {
      height = Math.round((height * maxWidth) / width)
      width = maxWidth
    }
  } else {
    if (height > maxHeight) {
      width = Math.round((width * maxHeight) / height)
      height = maxHeight
    }
  }
  return [width, height]
}

// Utility functions for demo purpose

function displayInfo(label, file) {
  const p = document.createElement("p")
  p.innerText = `${label} - ${readableBytes(file.size)}`
  document.getElementById("root").append(p)
}

function readableBytes(bytes) {
  const i = Math.floor(Math.log(bytes) / Math.log(1024)),
    sizes = ["B", "KB", "MB", "GB", "TB", "PB", "EB", "ZB", "YB"]

  return (bytes / Math.pow(1024, i)).toFixed(2) + " " + sizes[i]
}