Forem: Lucas Wolff

The Responsive Web Design Guide For Developers

Lucas Wolff — Tue, 18 Jul 2023 11:55:56 +0000

Responsive web design is getting more important than ever, and for good a reason. It ensures that your website looks and behaves beautifully across multiple devices, from small mobile screens to large desktop monitors.

Websites must effortlessly adjust to different devices and screen sizes in today's digital environment. This is where CSS media queries come into play.

Simply explained, CSS media queries let you employ various styles and layouts according on the features of the device being used to view your website.

CSS Breakpoints and Media Queries

CSS breakpoints act as triggers for your website to switch between different layouts at specific screen widths. These breakpoints allow you to control how your site looks and behaves on different devices.

The triggers are defined by the media queries. Media queries allow you to target different CSS properties or styles depending on the dimensions of the viewport.

They allow you to set specific rules for responsive websites and create layouts that automatically adjust to fit the device size. For example, at a given set of breakpoints, you might change the site's font size or hide certain elements as the viewport gets smaller.

You can also use them to give your site a mobile-specific design.

/* Styles for screens up to 600px width */
@media (max-width: 600px) {
  body {
    background-color: lightblue;
    font-size: 16px;
  }
}

/* Styles for screens between 601px and 1024px width */
@media (min-width: 601px) and (max-width: 1024px) {
  body {
    background-color: lightgreen;
    font-size: 18px;
  }
}

/* Styles for screens larger than 1024px width */
@media (min-width: 1025px) {
  body {
    background-color: lightgray;
    font-size: 20px;
  }
}

In this example, the styles for the <body> element change based on the screen size. When the screen width is up to 600 pixels, the background color is light blue, and the font size is 16 pixels. For screen sizes between 601 and 1024 pixels, the background color changes to light green, and the font size is 18 pixels. Lastly, for screens larger than 1024 pixels, the background color becomes light gray, and the font size increases to 20 pixels.

Mobile First Design

Mobile first design is an approach that prioritizes designing for mobile devices first, then expanding the design to fit larger screens. This ensures a smooth experience for mobile users and encourages a streamlined design process.

Prioritizing mobile allows designers to focus on the most important elements first, rather than trying to fit an existing design into a smaller viewport.

This means paying close attention to visual hierarchy and ensuring content is condensed only to the essentials. Mobile first design also encourages responsive web design to ensure that the optimal display is provided no matter the device or screen size. This also requires the use of mobile-specific functionality such as touch gestures for navigation, as well as responsive images and other media content.

Mobile first design principles ensures an experience tailored to mobile devices while still preserving essential features from larger displays. By beginning with mobile design, designers can create a holistic experience that works across all devices.

The Viewport Meta Tag

The viewport meta tag is essential for responsive web design. It enables the browser to scale your website to fit the width of the device's screen and prevents users from needing to zoom in or out to view your content properly.

Pay attention if you are including images, make sure the size is also adaptive, that is, they should not occupy more than the viewport can show. Keeping the size of your elements in check will ensure a better user experience across all devices.

Example 1: Basic configuration

<head>
  <meta name="viewport" content="width=device-width, initial-scale=1.0" />
</head>

In this example, the viewport meta tag is set with the width=device-width attribute, which ensures that the webpage's width matches the device's width. The initial-scale=1.0 attribute sets the initial zoom level to 100%, ensuring that the content appears at its intended size.

Example 2: Controlling zoom behavior

<head>
  <meta
    name="viewport"
    content="width=device-width, initial-scale=1.0, minimum-scale=1.0, maximum-scale=2.0"
  />
</head>

Here the viewport meta tag includes additional attributes to control the zoom behavior. minimum-scale=1.0 ensures that the minimum allowed zoom level is 100%, preventing the user from zooming out further. maximum-scale=2.0 sets the maximum allowed zoom level to 200%, limiting how much the user can zoom in.

Example 3: Fixed Width

<head>
  <meta name="viewport" content="width=1200" />
</head>

In this example, the viewport meta tag is set with a fixed width of 1200 pixels. This approach is useful when you want to design a fixed-width layout that doesn't respond to different screen sizes. The content will appear at the specified width regardless of the device's actual screen size.

Designing for Different Screen Sizes

Each web application has unique characteristics. Understanding the variety of screen sizes and resolutions that exist is crucial for crafting a responsive design.

By analyzing your target audience, you can design and create your website's layout and content to suit their needs.

A good example is a dashboard created for business purposes. Maybe doesn't make sense to create a responsive version to mobile devices because it'll only be used by employees on their computers.

Or a storage management web application that some pages will be used on tablets, and others only on larger computer screens. In this case the application can have different view ports to adapt to the users' needs.

Leveraging CSS Flex-box and Grid

Both CSS Grid and Flex-box are powerful tools for creating responsive designs.

It's possible to use different configurations based on breakpoints and also use more "fluid" settings to keep them adapted to different screen sizes.

Example 1: CSS Grid

<style>
  .container {
    display: grid;
    grid-template-columns: repeat(auto-fit, minmax(300px, 1fr));
    grid-gap: 20px;
  }

  .item {
    background-color: lightblue;
    padding: 20px;
  }
</style>

<div class="container">
  <div class="item">Item 1</div>
  <div class="item">Item 2</div>
  <div class="item">Item 3</div>
</div>

In this example, the .container element is set to display: grid, and grid-template-columns is set to repeat(auto-fit, minmax(300px, 1fr)). This ensures that the grid columns will automatically adjust based on the available space, with a minimum width of 300 pixels and a maximum width of 1 fraction unit (1fr). The grid-gap property adds a 20px gap between grid items.

Example 2: CSS Flexbox

<style>
  .container {
    display: flex;
    flex-wrap: wrap;
    justify-content: space-between;
  }

  .item {
    flex-basis: calc(33.33% - 20px);
    background-color: lightgreen;
    margin-bottom: 20px;
    padding: 20px;
  }
</style>

<div class="container">
  <div class="item">Item 1</div>
  <div class="item">Item 2</div>
  <div class="item">Item 3</div>
</div>

In this example the .container element is set to display: flex, and flex-wrap is set to wrap. This allows the items to wrap onto multiple lines when the container width is limited. The justify-content property is set to space-between, which evenly distributes the items with space between them.

The .item class has flex-basis set to calc(33.33% - 20px), which calculates the initial width of each item as one-third of the container width minus 20px for the margin. This allows the items to take up equal space and adjust their size based on the container width.

The Power of CSS Frameworks

CSS frameworks like TailwindCSS provide a solid foundation for building responsive websites. With pre defined styles and components, you can quickly create responsive layouts without reinventing the wheel.

It has a very simple mobile-first approach, which is great to start creating your application fast.

By using Tailwind, you don't need to write specific media-queries (or even raw css), just use the classes that are available and you're good to go.

CSS Viewport Units

Viewport units in CSS allow you to set element sizes relative to the viewport dimensions, enabling designs that adapt fluidly to different screen sizes. They are represented by vw (view port width) and vh (view port height).

This is extremely beneficial for designing responsive web pages, as all of the page elements can respond to the user's device and present a top-notch experience.

Viewport units are very useful for creating dynamic layouts. For instance, they make it easy to create full-height or full-width elements on the page, regardless of the size of the viewport.

They can even be used to create stacked elements that expand and collapse, allowing users to customize their own layout.

Conclusion

CSS media queries are an indispensable tool in the tool-box of any web designer or developer. They empower you to create websites that automatically adapt to different devices, providing a smooth and enjoyable user experience.

Remember to always have the target audience in mind when creating web applications, so you can focus on the specific break points or screen sizes that will be used.

By embracing responsive design, you can ensure your website shines across all devices and captivates your audience.

If you have any feedback or suggestions, send me an email

Great coding!

CSS Colors: Understanding RGB, HEX, HSL, and Alpha Values

Lucas Wolff — Wed, 12 Jul 2023 11:40:37 +0000

tl;dr

10 Key Takeaways:

Learn to use RGB, HEX, and HSL formats to represent colors in CSS effectively.
Use alpha values to control color transparency and create visually interesting effects.
Explore different color palettes and schemes to create harmonious designs.
Understand color theory to convey emotions and convey your brand effectively.
Consider color perception and the impact it has on your website's users.
Take into account the color space and gamut of your target devices.
Utilize online tools to generate color palettes and schemes based on various rules.
Experiment with different color combinations to create visually appealing designs.
Be aware of color accessibility guidelines to ensure inclusion for all users.
Regularly update your color knowledge to stay up to date with emerging trends and techniques.

Intro

As a web designer or developer, understanding CSS colors is essential for creating visually appealing and captivating websites. The world of digital colors can sometimes be confusing.

In this article, we will demystify the various color models and codes used in CSS, including RGB, HEX, HSL, and alpha values.

So, let's dive in and explore the exciting world of CSS colors!

RGB (Red, Green, Blue)

The RGB color model is widely used in web design and development. It represents colors as a combination of red, green, and blue color channels.

Each channel can have a value between 0 and 255, indicating the intensity of that particular color.

For example, rgb(255, 0, 0) represents pure red, while rgb(0, 255, 0) represents pure green, and so on.

HEX Codes

HEX codes are another popular way to represent colors in CSS.

A HEX code consists of a hash symbol (#) followed by six alphanumeric characters, which represent the intensity of the red, green, and blue color channels.

For instance, #FF0000 represents pure red, and #00FF00 represents pure green.

HSL (Hue, Saturation, Lightness)

HSL is a user friendly alternative to RGB. It represents colors based on their hue, saturation, and lightness.

The hue value determines the color itself, while saturation represents the intensity or purity of the color. Lightness, on the other hand, determines the brightness of the color.

HSL values are expressed as hsl(hue, saturation, lightness), where hue ranges from 0 to 360, and saturation and lightness range from 0% to 100%.

Understanding Alpha Values

Alpha values, also known as transparency or opacity, allow you to control the level of transparency in a color.

Alpha values range from 0 to 1, where 0 represents fully transparent, and 1 represents fully opaque. You can express alpha values in CSS using either RGBa, HSLa or HEXa syntax. Note that HEXa varies between 00 and FF instead of 0.0 and 1.0.

Color Palettes and Schemes

Creating harmonious and visually pleasing websites often starts with choosing the right color palette or scheme.

There are various tools available online that can help you generate color palettes based on different rules, such as complementary, analogous, or triadic colors. Experimenting with different color schemes can make your website stand out from the crowd and leave a lasting impression on your visitors.

Understanding Color Theory and Perception

Color theory involves understanding the visual effects of color combinations and the psychological impact they have on individuals.

By understanding fundamental concepts like color harmony and contrast, you can create designs that evoke specific emotions or convey important messages. This knowledge will not only make your website visually appealing but also ensure that it effectively communicates your brand or message.

Color Spaces and Gamut

Color space refers to the range of colors that can be displayed or reproduced on a device. Different devices may have different color spaces, which can affect the accuracy and consistency of color representation.

Understanding the color gamut of your target devices is crucial to ensure that your selected colors appear as intended across different platforms, be it a computer monitor, smartphone, or even a printer.

Conclusion

Mastering CSS colors is an essential skill for web designers and developers.

Understanding RGB, HEX, HSL, and alpha values allows you to wield a powerful tool set when it comes to creating stunning websites. By leveraging the principles of color theory and experimenting with different color combinations, you can take your web development skills to the next level and deliver impactful user experiences.

If you have any feedback or suggestions, send me an email

Great coding!

How to Debug CSS (using CSS)

Lucas Wolff — Tue, 04 Jul 2023 11:21:40 +0000

Sometimes when you're working with CSS you may face some issues that are not very easy to debug, like having horizontal scrolls, overlapping elements, and margins that are more or less than the value that you set.

Even after changing attribute's values and re-writing elements, you're still seeing that strange behavior that you're desperately trying to get rid of.

So you go to Dev Tools and inspect the element, and there's nothing wrong with it, or with its parent elements. Then you start to get crazy because there's no other way to debug the issue and you tried every possibility so far!

CSS doesn't have a debugger like programming languages, so we need to rely on our own abilities to do it manually.

I usually have two approaches to do it: border and background color.

The `border` approach

This is pretty simple and works for more basic scenarios. You just need to add a colored border * the elements on the screen and see what may be causing issues:

* {
  border: 1px solid green;
}

This approach is good to check isolated groups of elements like headers, footers, lists and so on. For whole layouts it's not ideal because the border property adds some spacing between elements so it may cause inconsistencies on the page layout.

The `background-color` approach

This approach is more useful to more complex scenarios where border is not a good option, like whole pages and complex components. It's also pretty simple to use it:

* {
  background-color: rgba(0 255 0 / 5%);
}

Now you can clearly see any overlapping elements and identify issues that aren't easy to identify reading the CSS or via Dev Tools!

Wrapping up

Since CSS runs on the browser, we need to be creative to debug it and identify problems.

If you're working with React, you can take advantage of tools like Storybook which enables you to progressively build isolated components.

But without React this may be a tricky task. In these situations you can use the solutions above.

Hope that helps!

If you have any feedback or suggestions, send me an email

Great coding!

Path Mapping in TypeScript with Vite

Lucas Wolff — Tue, 27 Jun 2023 10:26:59 +0000

Working with imports in JavaScript applications can be a mess if you have deeply nested folder structures.

This can be even worse if your editor or IDE doesn't have intellisense or if it's not configured properly.

So you end up with some imports like this:

// ❌
import { useForm } from "../../../../hooks/useForm";
import { TextInput } from "../../../form/TextInput";
import { Button } from "../../../ui/Button";
import { loginValidations } from "../../../../utils/validations";
import { routes } from "../../../../config/routes";

This will work but doesn't scale nor is readable to the developer.

TypeScript Path Mapping

When using TypeScript it's very common to use path mapping. This is useful because you can omit the relative paths from the import and then get the module using an absolute import.

// ✅
import { useForm } from "@hooks/useForm";
import { TextInput } from "@components/form/TextInput";
import { Button } from "@components/ui/Button";
import { loginValidations } from "@utils/validations";
import { routes } from "@config/routes";

This can be achieved adding the paths config to your tsconfig.json:

// tsconfig.json

{
  "compilerOptions": {
    "baseUrl": "./src", // This is to avoid adding the ./src prefix to each path below.
    "paths": {
      "@components/*": ["components/*"],
      "@hooks/*": ["hooks/*"],
      "@utils/*": ["utils/*"]
      "@config/*": ["config/*"]
    }
  }
}

This improves the readability a lot, and also if you move your components or modules to another folder, the chances that you need to update the imports are very low.

Vite + TypeScript Path Mapping

If you try to create paths using Vite you'll notice that it's not possible, since Vite doesn't know how to build the imports by default.

There are two solutions to this issue: adding the paths manually to the Vite build config or using a third-party package.

Adding paths manually

In order to add the paths manually to Vite build you'll need to configure all the aliases in vite.config.ts:

// vite.config.ts

// ...
import path from "path";

export default defineConfig({
  // ...
  resolve: {
    alias: [
      {
        find: "@components",
        replacement: path.resolve(__dirname, "src/components"),
      },
      {
        find: "@utils",
        replacement: path.resolve(__dirname, "src/utils"),
      },
      {
        find: "@hooks",
        replacement: path.resolve(__dirname, "src/hooks"),
      },
      {
        find: "@configs",
        replacement: path.resolve(__dirname, "src/configs"),
      },
    ],
  },
});

// OR EVEN BETTER:

const aliases = ['components', 'utils', 'hooks', 'configs'];

export default defineConfig({
  // ...
  resolve: {
    alias: aliases.map(alias => (
      {
        find: `@${alias}`,
        replacement: path.resolve(__dirname, `src/${alias}`),
      },
    ))
  },
});

The downside of this approach is that every time the paths on tsconfig.json change you'll need to update the vite.config.ts too. This is not an ideal workflow.

Using `vite-tsconfig-paths`

To solve that you can use a package called vite-tsconfig-paths which does all that boring and repetitive work.

It's very simple to use. All the configuration can be done in 2 steps:

Install it as a dev dependency:

# npm
npm i vite-tsconfig-paths --save-dev

# yarn
yarn add -D vite-tsconfig-paths

Then add it as a Vite plugin:

// vite.config.ts

import tsconfigPaths from "vite-tsconfig-paths";

export default defineConfig({
  plugins: [tsconfigPaths()],
});

And that's it! Every new path added will work without any changes needed.

If you have any feedback or suggestions, send me an email

Great coding!

Best Practices for Creating a Folder and File Structure for a React Application

Lucas Wolff — Wed, 21 Jun 2023 22:19:02 +0000

When you start a new application one of the first decisions that you need to make is how to organize the folder structure.

It's common to spend a lot of time trying to create the perfect structure for new projects, but let me tell you: there's no such thing as the best folder structure.

Since every project has its own domain, goals and specifics, you need to reflect these singularities into your code, file and folder structure.

That's why it's so important to know and understand what you are going to create before actually starting creating it, and also because this structure plays a crucial role in the project's scalability and maintainability.

If you're not using an opinionated framework like Next.js, you'll be probably using Vite or even Create React App, so the chances are that you will need to create your own folder and file structure.

There are several different approaches to this, and today I'll show you what I usually use to start my projects and also the methodology and concepts behind it so you can create your own boilerplate.

Disclaimer

The organization that I'll be showing in this article is ideal for small to medium size projects. For big applications, there are better approaches like the feature-based architecture, screaming architecture and others, where you don't clutter your folders with unrelated files.

With that said, let's jump to the explanation!

Top-Level Folder Structure

In general your top-level folder structure will look like this:

dist/
public/
src/
...

In this article I'll focus mainly on the src/ folder, which contains the files that you'll be working most of the time.

The src/ Folder

src/
|-- App.jsx
|-- index.css
|-- main.jsx

The main.jsx is the entry point of the application, and basically renders the App.jsx into the DOM. This file also imports the index.css which is the top-level CSS file of the application, containing shared styles. If you're using TailwindCSS for example, this is the place where the @tailwind imports will be located.

The App.jsx file is the application itself. This is the place where you'll be adding the Router, Context Providers, setting up services and so on. Everything there is intended to be application-wide.

I propose the below file structure to start projects. Keep in mind that this can be used for projects of any size, but probably for huge ones you'll need to tweak some things.

src/
|-- adapters/
|-- assets/
|-- components/
|-- contexts/
|-- hooks/
|-- pages/
|-- services/
|-- utils/

Now let's break down each folder to understand what they are supposed to do.

`src/adapters`

Here you'll have adapters to external sources e.g., APIs, browser features like Local Storage, and File System. This folder can be also called providers/ but this may be confusing due to the Context API providers. Or even lib/, but I do prefer to call it adapters/.

Example:

src/
|-- adapters/
|---- api.js
|---- localStorage.js
...

// src/adapters/api.js
export const api = {
  get: (url) => axios.get(url),
  // ...
};

// src/adapters/localStorage.js
export const localStorage = {
  get: (key) => {
    const value = localStorage.getItem(key);
    if (value) {
      return value;
    }

    throw new Error("KEY_NOT_FOUND");
  },
  // ...
};

`src/assets`

This folder is intended to serve static assets like images, SVGs, and videos. Feel free to create as many folders as you need, always focusing on the organization of the folder structure.

Example:

src/
|-- assets/
|---- image/
|------ logo-transparent.png
|------ clients/
|-------- foo-logo.png
|-------- bar-profile-picture.png
|---- svg/
|------ loading-spinner.svg
...

`src/components`

Here is the place where all your components will live—except the main pages.

There are several ways to divide this folder internally depending on the project needs. I like to create folders to group related components, and then component folders inside them.

src/
|-- components/
|---- core/
|---- forms/
|---- layouts/
|---- pages/
|---- shared/
...

Understanding the structure:

core/: isolated components that are the building-blocks of the application;
forms/: components used to build forms;
layouts/: the layouts of the application, used on each page;
pages/: components used inside specific pages;
shared/: components that can be shared between more than one page.

Example:

src/
|-- components/
|---- core/
|------ Card/
|-------- Card.jsx
|-------- Card.test.js
|-------- style.scss
|-------- index.js
|---- forms/
|------ TextInput/
|-------- TextInput.jsx
|-------- TextInput.test.js
|-------- style.scss
|-------- index.js
|---- layouts/
|------ PageLayout/
|-------- PageLayout.jsx
|-------- PageLayout.test.js
|-------- style.scss
|-------- index.js
|---- pages/
|------ HomePage/
|-------- HomeCarousel/
|---------- HomeCarousel.jsx
|---------- HomeCarousel.test.js
|---------- style.scss
|---------- index.js
|---- shared/
|------ ShoppingCart/
|-------- ShoppingCart.jsx
|-------- ShoppingCart.test.js
|-------- style.scss
|-------- index.js
...

`src/contexts`

This folder will contain all the state management's contexts that your application will use. This may vary if the application uses other solutions like Redux. In this case—if you follow the Redux Toolkit patterns—you'll need to create a features folder, or slices.

The general idea here is not the name of this folder, but its purpose.

Since this folder is heavily dependent on the state management solution that is being used, you'll need to adapt it to the needs of the chosen tool.

`src/hooks`

The place where all the application's hooks will be located. Hooks can also be understood as the features of your application, which you can hook into as many components as you need.

Based on that, you can also create inner folders related to each feature to make the structure more readable and encapsulated.

Example:

src/
|-- hooks/
|---- useForm.js
|---- useWindowSize.js
|---- authentication/
|------ useLogin.js
|------ useSignUp.js
...

Here the useForm and useWindowSize are both global level hooks. The ones under the authentication/ folder are strictly related to the authentication feature of the application.

`src/pages`

This folder contains all the pages of your application. The idea of each page is to use the components from the components folder to build the UI.

The pages can use components from all the folders, but will use mainly from these:

src/components/layouts/: to build the base layout of the page;
src/components/pages/PAGE_NAME: to get specific components for the related page;
src/components/core/: to use elements like Button and Typography to build the page;
src/components/shared/: to use elements that are shared between pages;

I didn't add the forms component because it's ideal that each form has its own component inside the shared/ or pages/ folder. But feel free to get the form components directly if needed.

`src/services`

All the calls for each API endpoint will be under this folder. Each service will probably use the API adapter to call the API, and will be called inside a hook, which is called inside the components. I wrote an article around this topic, explaining how to organize your API calls correctly.

You can also create top-level files for each group of services or one service per file, or even create folders for each type of service, it's up to you.

The mentioned approaches are exemplified below:

TOP-LEVEL FILE:
src/
|-- services/
|---- user.js (exports functions like getUser, createUser, etc.)

OR

ONE SERVICE PER FILE:
src/
|-- services/
|---- getUser.js
|---- createUser.js

OR

GROUP SERVICES BY TYPE:
src/
|-- services/
|---- user/
|------ getUser.js
|------ createUser.js
|------ index.js (exports all functions)

Again, the best approach is the one that fits your needs and the needs of your team.

`src/utils`

Utils are pure JavaScript functions that can be reused across the application. Pure functions are basically functions that, given an input, will always return the same value.

The same idea used above for the services can be used for the utils:

TOP-LEVEL FILE:
src/
|-- utils/
|---- user.js (exports functions like calculateUserGrades, isUserBirthday, etc.)

OR

ONE UTIL PER FILE:
src/
|-- utils/
|---- calculateUserGrades.js
|---- isUserBirthday.js

OR

GROUP UTILS BY TYPE:
src/
|-- utils/
|---- user/
|------ calculateUserGrades.js
|------ isUserBirthday.js
|------ index.js (exports all functions)

File Naming Conventions

In the examples all the file names are very simple, following the pattern of [filePurpose].[fileExtension], like [createUser].[js].

Although one very common patter is to put the type of the file in the name before the extension. This is a matter of choice, and for some people it can improve the readability of the project. For example:

services/createUser.js → services/createUser.service.js
utils/isUserBirthday.js → utils/isUserBirthday.util.js

Also, for the React components I always use Pascal Case (ComponentName), and I like to use camel-case (fileName) instead of kebab-case (file-name) for file names that are not React components, like services and utils.

But for folders, I prefer to use the kebab case if they have multiple words. One example is a service folder for a resource that deals with product categories. I'd create a group folder like:

src/
|-- services/
|---- product-categories/
|------ getProductCategories.js
|------ updateProductCategory.js

Conclusion

Project structure is a very important and also personal topic. Using frameworks like Next.js makes things easier in this sense because they are very opinionated.

One idea is to create a project using Next.js and then clone it using Vite, for example, so you can compare and create your own boilerplate.

My goal here was to give you some direction towards your own project structure. You can use this idea as a boilerplate but always remember to follow the structure that fits best your needs.

If you have any feedback or suggestions, send me an email

Great coding!

The Definitive Guide to Make API Calls in React

Lucas Wolff — Mon, 19 Jun 2023 23:13:34 +0000

Understanding how to deal with API calls in web applications is a crucial skill to have. There are lots of different libraries that help you through this process, but sometimes they are not very beginner-friendly.

When working with vanilla JavaScript, you'll probably be using a library like Fetch or Axios to make API requests. In React you can also use them, and the challenge is how to organize the code around these libraries to make it as readable, extensible and decoupled as possible.

This is not a very intuitive task. It's very common for new developers that are starting with React to make API requests like this:

// ❌ Don't do this

const UsersList = () => {
  const [users, setUsers] = useState([]);

  useEffect(() => {
    fetch("/users").then((data) => {
      setUsers(users);
    });
  }, []);

  return (
    <ul>
      {users.map(user => (
        <li>{user.name}<li>
      ))}
    </ul>
  );
};

The above approach works, and is very common even in business-level codebases. But there are some downsides of using it:

The data is stored in the local state
- Every API call in other components will require a new local useState
The request library (Fetch) is called directly in the component
- If you change the library to Axios, for example, then every component will need to be refactored
- The same applies to the endpoint, if it changes you'll need to refactor it in many places
A server-level request is being made in a presentational component
- Components are intended to present data, not handle fetch logic
- It's a good practice to have a single responsibility for each component, class and function
It's not clear what the request will return
- You rely on the endpoint name to know what will be returned by the API

There are a lot of different ways to solve these problems. Today I'll be showing you my ideas and approaches to create a folder and file structure that is reliable and scalable, and you can apply it—or the idea behind it—even on frameworks like Next.js.

The scenario for our example

To understand and glue all the concepts, let's progressively build a Grocery List app. The app will have the following features:

List existing items;
Add new item;
Remove item;
Mark item as done;

For the styles, I'll be using TailwindCSS. To simulate API requests Mirage JS will be used, which is a very easy to use and useful API mocking library. To call this API, we're going to use Fetch.

All of the examples are on my GitHub, so feel free to clone the repository and play with it. The details of how to run it are described in the README file.

The final result will look like this:

Creating the API endpoints

This application will need 4 API endpoints:

GET /api/grocery-list - Retrieve all items
POST /api/grocery-list - Create a new item
PUT /api/grocery-list/:id/done - Mark the item with id equals to :id as done
DELETE /api/grocery-list/:id - Removes the item with id equals to :id

The following examples are the most basic case of calling APIs. It's not the best one but we'll refactor the code as we go, so you'll understand better all the concepts. Also, we're not focusing on the presentation layer, that is, the actual JSX of the component. It surely can be improved, but it's not the focus of this article.

1. Retrieving all the items

A good place to add the first call is on the useEffect of the component, and add a refresh state as parameter, so every time this state changes, we'll refetch the items:

// src/App.jsx

const App = () => {
  const [items, setItems] = useState([]);
  const [refetch, setRefetch] = useState(false);

  useEffect(() => {
    fetch("/api/grocery-list")
      .then((data) => data.json())
      .then((data) => {
        setItems(data.items);
      });
  }, [refresh]);

  return (
    <ul>
      {items.map((item) => (
        <li key={item.id}>{item.title}</li>
      ))}
    </ul>
  );
};

2. Creating a new item

When the user inputs the item title and clicks on the "Add" button, the application should dispatch a call to the API to create a new item, then fetch all the items again to show the new item:

// src/App.jsx

const App = () => {
  // ...
  const [title, setTitle] = useEffect("");

  const handleAdd = (event) => {
    event.preventDefault();

    fetch("/api/grocery-list", {
      method: "POST",
      body: JSON.stringify({ title }),
    }).then(() => {
      setTitle(""); // Empty the title input
      setRefresh(!refresh); // Force refetch to update the list
    });
  };

  return (
    // ...

    <form onSubmit={handleAdd}>
      <input
        required
        type="text"
        onChange={(event) => setTitle(event.target.value)}
        value={title}
      />
      <button type="submit">Add</button>
    </form>

    // ...
  );
};

3. Marking an item as done

When the user clicks on the checkbox to mark the item as done, the application should dispatch a PUT request passing the item.id as a parameter on the endpoint. If the item is already marked as done, we don't need to make the request.

This is very similar to creating a new item, just the request method changes:

// src/App.jsx

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

  const handleMarkAsDone = (item) => {
    if (item.isDone) {
      return;
    }

    fetch(`/api/grocery-list/${item.id}/done`, {
      method: "PUT",
    }).then(() => {
      setRefresh(!refresh); // Force refetch to update the list
    });
  };

  return (
    // ...

    <ul>
      {items.map((item) => (
        <li key={item.id}>
          <label>
            {/* Checkbox to mark the item as done */}
            <input
              type="checkbox"
              checked={item.isDone}
              onChange={() => handleMarkAsDone(item)}
            />
            {item.title}
          </label>
        </li>
      ))}
    </ul>

    // ...
  );
};

4. Removing an item

This is pretty much the same as we did on marking an item as done, but with the DELETE method. When clicking on the "Delete" button, the application should call a function that dispatches the API call:

// src/App.jsx

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

  const handleDelete = (item) => {
    fetch(`/api/grocery-list/${item.id}`, {
      method: "DELETE",
    }).then(() => {
      setRefresh(!refresh); // Force refetch to update the list
    });
  };

  return (
    // ...

    <ul>
      {items.map((item) => (
        <li key={item.id}>
          <label>
            {/* Checkbox to mark the item as done */}
            <input type="checkbox" onChange={() => handleMarkAsDone(item)} />
            {item.title}
          </label>

          {/* Delete button */}
          <button onClick={() => handleDelete(item)}>Delete</button>
        </li>
      ))}
    </ul>

    // ...
  );
};

Final code for the first part of the example

The final code should look like this:

// src/App.jsx

const App = () => {
  const [items, setItems] = useState([]);
  const [title, setTitle] = useState("");
  const [refresh, setRefresh] = useState(false);

  // Retrieve all the items
  useEffect(() => {
    fetch("/api/grocery-list")
      .then((data) => data.json())
      .then(({ items }) => setItems(items));
  }, [refresh]);

  // Adds a new item
  const handleAdd = (event) => {
    event.preventDefault();

    fetch("/api/grocery-list", {
      method: "POST",
      body: JSON.stringify({ title }),
    }).then(() => {
      setRefresh(!refresh);
      setTitle("");
    });
  };

  // Mark an item as done
  const handleMarkAsDone = (item) => {
    if (item.isDone) {
      return;
    }

    fetch(`/api/grocery-list/${item.id}/done`, {
      method: "PUT",
    }).then(() => {
      setRefresh(!refresh);
    });
  };

  // Deletes an item
  const handleDelete = (item) => {
    fetch(`/api/grocery-list/${item.id}`, {
      method: "DELETE",
    }).then(() => {
      setRefresh(!refresh);
    });
  };

  return (
    <>
      <form onSubmit={handleAdd}>
        <input
          required
          type="text"
          onChange={(event) => setTitle(event.target.value)}
          value={title}
        />
        <button type="submit">Add</button>
      </form>
      <ul>
        {items.map((item) => (
          <li key={item.id}>
            <label>
              <input
                type="checkbox"
                checked={item.isDone}
                onChange={() => handleMarkAsDone(item)}
              />
              {item.title}
            </label>
            <button onClick={() => handleDelete(item)}>delete</button>
          </li>
        ))}
      </ul>
    </>
  );
};

First Refactor: Creating Services

Now that we already have everything in place and working, let's refactor the code.

The first thing that we can do to make the code better is to create a service for the API calls. Services are basically JavaScript functions that are responsible for calling APIs.

This is useful because if you need to call the API in other places, you just call the service instead of copy-paste the whole fetch call.

// src/services/grocery-list.js

const basePath = "/api/grocery-list";

export const getItems = () => fetch(basePath).then((data) => data.json());

export const createItem = (title) =>
  fetch(basePath, {
    method: "POST",
    body: JSON.stringify({ title }),
  });

export const markItemAsDone = (itemId) =>
  fetch(`${basePath}/${itemId}/done`, {
    method: "PUT",
  });

export const deleteItem = (itemId) =>
  fetch(`${basePath}/${itemId}`, {
    method: "DELETE",
  });

Note that the services are returning a Promise and all the state calls were removed. We also replaced the repetitive base path of the API endpoints with a constant.

Now let's replace the old fetch calls on the component with the new services:

// src/App.jsx

// Importing the services
import {
  createItem,
  deleteItem,
  getItems,
  markItemAsDone,
} from "./services/grocery-list";

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

  useEffect(() => {
    // Service call
    getItems().then(({ items }) => {
      setItems(items);
    });
  }, [refresh]);

  const handleAdd = (event) => {
    event.preventDefault();

    // Service call
    createItem(title).then(() => {
      setRefresh(!refresh);
      setTitle("");
    });
  };

  const handleMarkAsDone = (item) => {
    if (item.isDone) {
      return;
    }
    // Service call
    markItemAsDone(item.id).then(() => {
      setRefresh(!refresh);
    });
  };

  const handleDelete = (item) => {
    // Service call
    deleteItem(item.id).then(() => {
      setRefresh(!refresh);
    });
  };

  // ...
};

This is much more readable and testable. You can test each service individually instead of testing the component as a whole. Also, it's much easier to understand what the code is supposed to do, for example:

// Get the items, then set the items.
getItems().then(({ items }) => {
  setItems(items);
});

Second Refactor: Abstracting the HTTP call

The grocery-list service is heavily relying on the Fetch library. If we decide to change it to Axios, all the calls should change. Also, the service layer doesn't need to know how to call the API, but only which API should be called.

To avoid mixing these responsibilities, I like to create an API Adapter. The name actually doesn't matter—the goal here is to have a single place where the API's HTTP calls are configured.

// src/adapters/api.js

const basePath = "/api";

const api = {
  get: (endpoint) => fetch(`${basePath}/${endpoint}`),
  post: (endpoint, body) =>
    fetch(`${basePath}/${endpoint}`, {
      method: "POST",
      body: body && JSON.stringify(body),
    }),
  put: (endpoint, body) =>
    fetch(`${basePath}/${endpoint}`, {
      method: "PUT",
      body: body && JSON.stringify(body),
    }),
  delete: (endpoint) =>
    fetch(`${basePath}/${endpoint}`, {
      method: "DELETE",
    }),
};

export { api };

This is the only file in the entire application that deals with HTTP calls. The other files that need to call the API only need to call these methods.

Now if you decide to replace Fetch with Axios, you just change this single file and you're good to go.

On the test side, now it's possible to test each API method individually without relying on the services call.

Talking about services, let's replace the old fetch calls with the new api. ones.

// src/services/grocery-list

import { api } from "../adapters/api";

const resource = "grocery-list";

export const getItems = () => api.get(resource).then((data) => data.json());

export const createItem = (title) => api.post(resource, { title });

export const markItemAsDone = (itemId) => api.put(`${resource}/${itemId}/done`);

export const deleteItem = (itemId) => api.delete(`${resource}/${itemId}`);

Wow, much cleaner! Note that some responsibilities that are on the request level are not here anymore, like converting a JSON object to a string. This was not the services' responsibility, and now the API layer is doing this.

Again, the code has become more readable and testable.

Third Refactor: Creating Hooks

We have the services and the API layers in place, now let's improve the presentation layer, that is, the UI component.

The components are currently calling the services directly. This works fine but holding the state and calling the service is more like a feature of your application instead of a responsibility of each component that needs to call the API.

The first hook that we're going to create is the useGetGroceryListItems(), which contains the getItems() API call.

// src/hooks/grocery-list.js

// Default module import
import * as groceryListService from "../services/grocery-list";

export const useGetGroceryListItems = () => {
  const [items, setItems] = useState([]);
  const [refresh, setRefresh] = useState(false);

  useEffect(() => {
    groceryListService.getItems().then(({ items }) => {
      setItems(items);
    });
  }, [refresh]);

  const refreshItems = () => {
    setRefresh(!refresh);
  };

  return { items, refreshItems };
};

Notice that we basically copied the behavior that was previously on the component to the new hook. We also needed to create the refreshItems(), so we can keep the data updated when we want instead of calling the service directly again.

We're also importing the service module to use it as groceryListService.getItems(), instead of calling just getItems(). This is because our hooks will have similar function names, so to avoid conflicts and also improve the readability, the whole service module is being imported.

Now let's create rest of the hooks for the other features (create, update and delete).

// src/hooks/grocery-list.js

export const useCreateGroceryListItem = () => {
  const createItem = (title) => groceryListService.createItem(title);

  return { createItem };
};

export const useMarkGroceryListItemAsDone = () => {
  const markItemAsDone = (item) => {
    if (item.isDone) {
      return;
    }
    groceryListService.markItemAsDone(item.id);
  };

  return { markItemAsDone };
};

export const useDeleteGroceryListItem = () => {
  const deleteItem = (item) => groceryListService.deleteItem(item.id);

  return { deleteItem };
};

Then we need to replace the service calls with the hooks in the component.

// src/App.jsx

// Hooks import
import {
  useGetGroceryListItems,
  useCreateGroceryListItem,
  useMarkGroceryListItemAsDone,
  useDeleteGroceryListItem,
} from "./hooks/grocery-list";

const App = () => {
  // ...
  const { items, refreshItems } = useGetGroceryListItems();
  const { createItem } = useCreateGroceryListItem();
  const { markItemAsDone } = useMarkGroceryListItemAsDone();
  const { deleteItem } = useDeleteGroceryListItem();

  // ...

  const handleMarkAsDone = (item) => {
    // Validation moved to hook and passing `item` instead of `item.id`
    markItemAsDone(item).then(() => refreshItems());
  };

  const handleDelete = (item) => {
    // Passing `item` instead of `item.id`
    deleteItem(item).then(() => refreshItems());
  };

  // ...
};

And that's it. Now the application is taking advantage of the hooks, which is useful because if you need the same feature in other components, you just call it.

If you're using a state management solution like Redux, Context API, or Zustand for example, you can make the state modifications inside the hooks instead of calling them at the component level. This helps to make things clearer and very well splitted between responsibilities.

Last Refactor: Adding the Loading State

Our application is working fine, but there's no feedback to the user during the waiting period of the API request and response. One solution to this is adding a loading state to each hook to inform the actual API request state.

After adding the loading state to each hook, the file will look like this:

// src/hooks/grocery-list.js

export const useGetGroceryListItems = () => {
  const [isLoading, setIsLoading] = useState(false); // Creating loading state
  const [items, setItems] = useState([]);
  const [refresh, setRefresh] = useState(false);

  useEffect(() => {
    setIsLoading(true); // Adding loading state
    groceryListService.getItems().then(({ items }) => {
      setItems(items);
      setIsLoading(false); // Removing loading state
    });
  }, [refresh]);

  const refreshItems = () => {
    setRefresh(!refresh);
  };

  return { items, refreshItems, isLoading };
};

export const useCreateGroceryListItem = () => {
  const [isLoading, setIsLoading] = useState(false); // Creating loading state

  const createItem = (title) => {
    setIsLoading(true); // Adding loading state
    return groceryListService.createItem(title).then(() => {
      setIsLoading(false); // Removing loading state
    });
  };

  return { createItem, isLoading };
};

export const useMarkGroceryListItemAsDone = () => {
  const [isLoading, setIsLoading] = useState(false); // Creating loading state

  const markItemAsDone = (item) => {
    if (item.isDone) {
      return;
    }

    setIsLoading(true); // Adding loading state
    return groceryListService.markItemAsDone(item.id).then(() => {
      setIsLoading(false); // Removing loading state
    });
  };

  return { markItemAsDone, isLoading };
};

export const useDeleteGroceryListItem = () => {
  const [isLoading, setIsLoading] = useState(false); // Creating loading state

  const deleteItem = (item) => {
    setIsLoading(true); // Adding loading state
    return groceryListService.deleteItem(item.id).then(() => {
      setIsLoading(false); // Removing loading state
    });
  };

  return { deleteItem, isLoading };
};

Now we need to plug the loading state of the page to each hook:

// src/App.jsx

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

  // Getting loading states and renaming to avoid conflicts
  const { items, refreshItems, isLoading: isFetchingItems } = useGetGroceryListItems();
  const { createItem, isLoading: isCreatingItem } = useCreateGroceryListItem();
  const { markItemAsDone, isLoading: isUpdatingItem } = useMarkGroceryListItemAsDone();
  const { deleteItem, isLoading: isDeletingItem } = useDeleteGroceryListItem();

  // Read each loading state and convert them to a component-level value
  const isLoading = isFetchingItems || isCreatingItem || isUpdatingItem || isDeletingItem;

  // ...

  return (
    <>
      <form onSubmit={handleAdd}>
        <input
          required
          type="text"
          onChange={(event) => setTitle(event.target.value)}
          value={title}
          disabled={isLoading} {/* Loading State */}
        />
        <button type="submit" disabled={isLoading}> {/* Loading State */}
          Add
        </button>
      </form>
      <ul>
        {items.map((item) => (
          <li key={item.id}>
            <label>
              <input
                type="checkbox"
                checked={item.isDone}
                onChange={() => handleMarkAsDone(item)}
                disabled={isLoading} {/* Loading State */}
              />
              {item.title}
            </label>
            <button onClick={() => handleDelete(item)} disabled={isLoading}> {/* Loading State */}
              delete
            </button>
          </li>
        ))}
      </ul>
    </>
  );
};

Bonus Refactor: Create an Utility

Notice that in the useMarkGroceryListItemAsDone() hook we have a logic that tells if the item should be updated or not:

// src/hooks/grocery-list.js

const markItemAsDone = (item) => {
  if (item.isDone) {
    return; // Don't call the service
  }

  // Call the service and update the item

This is not the ideal place for this logic because it can be needed in other places, forcing its duplication, and also it is a business logic of the application, and not a specific logic of this hook solely.

One possible solution is to create an util and add this logic there, so we only call the function in the hook:

// src/utils/grocery-list.js

export const shouldUpdateItem = (item) => !item.isDone;

And then call this util in the hook:

export const useMarkGroceryListItemAsDone = () => {
  // ...

  const markItemAsDone = (item) => {
    // Calling the util
    if (!shouldUpdateItem(item)) {
      return;
    }

    // ...

Now the hooks doesn't depend on any logic related to the business: they just call functions and return its values.

Wrapping Up

All the refactors that we did serve the purpose of improving the quality of the code, and make it more readable to humans. The code was working at first, but was not extensible and neither testable. These are very important characteristics of a great codebase.

We basically applied the Single-Responsibility Principle to the code in order to make it better. This code can be used as a foundation to build other services, connect with external APIs, create other components and so on.

As mentioned, you can also plug your state management solution here and manage the global state of the app in the hooks that we've created.

To improve the code even more, it's a good idea to work with React Query to take advantage of its features like caching, refetching and auto invalidation.

That's it! Hope you learned something new today to make your coding journey even better!

If you have any feedback or suggestions, send me an email

Great coding!

Optimistic UI: Enhancing User Experience in React with React Query

Lucas Wolff — Tue, 13 Jun 2023 20:16:02 +0000

In modern web development, delivering a smooth and responsive user experience is crucial. One aspect that may pass unnoticed by the final user is how the application handles data being mutated i.e. created, updated and removed.

This is probably due to the duality of the nature of this feature: if it works well, no one notices; if it doesn't, then the application is considered a bad one.

Users want to feel that they have control over what they're doing. Pretty much every loading state in your application has the potential of distracting the user, who needs to wait until the action finishes. But this is how apps are supposed to work, right?

If your application is solid and works well, you probably have noticed that most of the requests to mutate data in the server are successful. Even though most of the apps use loading states while mutating, then show the updated data when a response is received.

Today I'll explain to you which options do you have available to improve this user flow and why use them. Then I'll show you code examples of each method with step-by-step implementations. Keep reading!

The Traditional Method

The most used and traditional method of mutating data is the Pessimistic UI.

Pessimistic UI is an approach in UI/UX design where changes made by the user are not immediately reflected in the screen until the server response is received and confirmed.

When users perform an action like submitting a form or hitting a button the interface will remain unchanged until a response is received from the server. During this period the user might see a loading indicator and blocked buttons or inputs. When the response is received, then the UI will be updated with new data or a feedback will be given.

This pessimistic approach is employed and useful in situations where data consistency and accuracy are important. By deferring UI updates until the response is validated, the chances of showing incorrect and inconsistent data are reduced.

Some examples of Pessimistic UI uses are bank transactions and app sign in and sign ups, where security and consistency are preferred over a responsive interface.

But sometimes we need to give the user a much more sense of control and also provide a smoother app experience.

Imagine if you see a loading spinner every time you like an Instagram post. That's definitely not ideal, and you would not be fully engaged in the whole app experience.

To solve this issue, we have the Optimistic UI.

Understanding Optimistic UI

Optimistic UI is an approach that aims to provide immediate feedback to the user, and then fire the mutation request in the background.

When performing actions such as clicking on buttons or submitting forms the interface will be updated before the actual request is dispatched, so the user can continue the journey through the application. Meanwhile, the server is processing the request and eventually giving a response back to the frontend. If it's a failure response then the UI updates are rolled back, and if it's a successful response then nothing needs to be done—the UI is already updated.

The Optimistic UI approach is used in scenarios where feedback and responsiveness are crucial. It removes any perceived delay and creates a smoother user experience by assuming a successful response upfront.

As mentioned above, one example of Optimistic UI is the Instagram like button. When the button is clicked (like or unlike), the UI is updated upfront and then the request is dispatched. This is also great because some users may be using a slow network, so Optimistic UI is a problem solver in that case.

Now that you understand the differences and use cases of each method, let's dive into some code examples.

The scenario for our examples

Before jumping into the code, let me show you what we're going to be using in all of the examples.

Let's consider a simple React application which has a "Send message" button that when clicked dispatches a request to the server with, and then a new message is added to a list. Also, when the user enters the page the existing messages should be fetched from the API.

To simulate the API request, a promise will be resolved and a delay will be added to it, so you can understand better the overall behavior. Here are the two mocked API requests that we're going to use

// Default existing messages
const messages = [
  {
    id: 1,
    message: "Existing message",
  },
  {
    id: 2,
    message: "Existing message",
  },
];

// Return all the messages
export const getMessages = () =>
  new Promise((resolve) => {
    setTimeout(() => {
      resolve(messages);
    }, 1500);
  });

// Add a new message to the messages array
export const sendMessage = (message) =>
  new Promise((resolve) => {
    setTimeout(() => {
      messages.push(message);
      resolve(messages);
    }, 1500);
  });

For the styles, I'll be using TailwindCSS.

All of the examples are on my GitHub, so feel free to clone the repository and play with it. All the details of how to run it are described in the README file.

With that said, let's jump to the code!

Pessimistic Updates without React Query

In order to make this work, we need to manage the loading behavior and add the new message to the state. This is basically what most of the apps do behind the scenes.

const PessimisticUpdate = () => {
  const [isFetching, setIsFetching] = useState(false); // Used for initial fetching
  const [isLoading, setIsLoading] = useState(false); // Used when sending a new message
  const [messages, setMessages] = useState([]); // Local state to store messages

  // Load existing messages from API when component mounts,
  // and shows a loading state while fetching
  useEffect(() => {
    setIsFetching(true);
    getMessages().then((messages) => {
      setMessages(messages);
      setIsFetching(false);
    });
  }, []);

  const handleClick = () => {
    setIsLoading(true); // Enable loading

    const newMessage = {
      id: messages.length + 1,
      message: "New message",
    };

    // Dispatch API request to add the new message
    sendMessage(newMessage).then((updatedMessages) => {
      setMessages(updatedMessages); // Update messages in the local state
      setIsLoading(false); // Disable loading
    });
  };

  return (
    <>
      {!isFetching && <MessagesList messages={messages} />}
      <Button
        text="Send message"
        onClick={handleClick}
        isLoading={isLoading || isFetching}
      />
    </>
  );
};

Note that the feedback—isLoading—is defined only after the promise resolves.

Optimistic Updates without React Query

The biggest difference here is that we'll not need isLoading anymore, since we are considering upfront that everything will work fine when sending a message, so the UI feedback will be immediate, and no loading state will be needed for this.

const OptimisticUpdate = () => {
  const [isFetching, setIsFetching] = useState(false); // Used for initial fetching
  const [messages, setMessages] = useState([]); // Local state to keep messages

  // Load existing messages from API when component mounts,
  // and shows a loading state while fetching
  useEffect(() => {
    setIsFetching(true);
    getMessages().then((messages) => {
      setMessages(messages);
      setIsFetching(false);
    });
  }, []);

  const handleClick = () => {
    const newMessage = {
      id: messages.length + 1,
      message: "New message",
    };

    // Update message in the local state upfront
    setMessages((previousMessages) => [...previousMessages, newMessage]);

    // Then dispatch API request to add new message
    sendMessage(newMessage).then(() => {
      console.log(`Message ${newMessage.id} added`);
    });
  };

  return (
    <>
      <h1 className="font-bold text-xl mb-2 text-center">Optimistic UI</h1>
      {!isFetching && <MessagesList messages={messages} />}
      <Button
        text="Send message"
        onClick={handleClick}
        isLoading={isFetching}
      />
    </>
  );
};

It was a pretty small change for a big improvement UX-wise. There are some trade-offs though.

We're not considering if the request fails. Removing the invalid data from the state is not straightforward in some cases and needs to be done manually. You'll probably need to add another state only to keep the temporary messages, along with the state with the actual messages.

Considering that a real-world application has much more things going on, you'll need to make sure to rollback all the UI changes too, and dispatch the correct actions if the request fails. This can be a little bit tricky and can have some complexity involved.

Pessimistic Updates with React Query

The biggest difference here is that React Query manages all the states that are related to messages and requests. Instead of calling the service directly in the component, it's passed to the React Hook and it's called immediately.

const PessimisticUpdateReactQuery = () => {
  const cacheKey = "messages"; // Cache key of the messages
  const queryClient = useQueryClient();

  // Load existing messages from API
  const { data: messages, isLoading: isFetching } = useQuery(
    cacheKey,
    getMessages
  );

  // Dispatch API request to add new message
  const { mutateAsync, isLoading } = useMutation(sendMessage, {
    onSuccess: () => {
      // Invalidate messages cache, since a new message was added.
      // The `messages` var will be automatically updated with fresh data.
      queryClient.invalidateQueries(cacheKey);
    },
  });

  const handleClick = () => {
    const newMessage = {
      id: messages.length + 1,
      message: "New message",
    };

    // Call React Query hook that calls sendMessage
    mutateAsync(newMessage);
  };

  return (
    <>
      {!isFetching && <MessagesList messages={messages} />}
      <Button
        text="Send message"
        onClick={handleClick}
        isLoading={isLoading || isFetching}
      />
    </>
  );
};

The code is much easier to read, since a lot of things are abstracted by the library.

You'll also have caching out of the box. If another call to the same service is made, the React Query hook will return the cached value instead of making a new API call, and you can configure the cache time as you want. This is a big performance improvement.

Optimistic Updates with React Query

As discussed in the example above, React Query will deal with all the server state, and you'll not need to manage any useState from React.

Here we have the optimal version to deal with optimistic updates. All the behavior is under React Query responsibility, so we just need to call its APIs.

The code below may look confusing at first, but let's dive into it and understand all the changes that were made:

const OptimisticUpdateReactQuery = () => {
  const cacheKey = "messages"; // Cache key of the messages
  const queryClient = useQueryClient();

  // Load existing messages from API
  const { data: messages, isLoading: isFetching } = useQuery(
    cacheKey,
    getMessages
  );

  // Dispatch API request to add new message
  // and do the optimistic update.
  const { mutateAsync } = useMutation(sendMessage, {
    onMutate: async (newMessage) => {
      // Cancel any outgoing refetches (so they don't overwrite the optimistic update)
      await queryClient.cancelQueries(cacheKey);

      // Snapshot the previous value
      const previousMessages = queryClient.getQueryData(cacheKey);

      // Optimistically update to the new value
      queryClient.setQueryData(cacheKey, (old) => [...old, newMessage]);

      // Return a context object with the snapshotted value
      return { previousMessages };
    },
    onError: (_, __, context) => {
      // If the mutation fails, use the context returned from onMutate to roll back
      queryClient.setQueryData(cacheKey, context.previousMessages);
    },
    onSettled: (messages) => {
      // Always refetch after error or success:
      queryClient.invalidateQueries(cacheKey);
      console.log(`Message ${messages[messages.length - 1].id} added`);
    },
  });

  const handleClick = () => {
    const newMessage = {
      id: messages.length + 1,
      message: "New message",
    };
    mutateAsync(newMessage);
  };

  return (
    <section>
      {!isFetching && <MessagesList messages={messages} />}
      <Button text="Send message" onClick={handleClick} />
    </section>
  );
}

As mentioned before, this comes with a lot of advantages like caching, automatic invalidation, and refetching.

One great idea in this case is to abstract the optimistic behavior (under onMutate) to a custom hook, then you can just call this hook that has the optimistic feature. The hook can be something like this:

const useOptimisticUpdate = () => {
  const queryClient = useQueryClient();

  const getPreviousData = async ({ cacheKey, newValue }) => {
    await queryClient.cancelQueries(cacheKey);

    // Snapshot the previous value
    const previousData = queryClient.getQueryData(cacheKey);

    // Optimistically update to the new value
    queryClient.setQueryData(cacheKey, (old) => [...old, newValue]);

    // Return a context object with the snapshotted value
    return { previousData };
  };

  return { getPreviousData };
};

And then replace the calls from onMutate with the hook:

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

  const { getPreviousData } = useOptimisticUpdate(); // New hook call

  const { mutateAsync } = useMutation(sendMessage, {
    onMutate: async (newMessage) => ({
      previousMessages: await getPreviousData({ // Get previous data from the hook
        cacheKey,
        newValue: newMessage,
      })
    }),

  // ...

Now you have a reusable optimistic update feature that can be shared across every component that you need.

Wrapping up

The experiences that many types of applications deliver may be always focused on the final user. This is where Optimistic UI shines.

Optimistic updates significantly improve the user experience by providing immediate feedback and responsiveness during data updates. While traditional methods require manual state management and error handling, React Query simplifies the process by offering built-in mutation functions, automatic cache invalidation, and error handling. By leveraging React Query, you can enhance the applications with a smoother user experience, save time and effort in managing data updates manually.

One thing to consider is that not every case will fit this concept, sometimes it will be better to use the Pessimistic UI for many reasons, like security and data consistency.

Be very thoughtful to where apply one concept or another, and think about discussing the decision with designers and POs. They can contribute with other point of views because this decision is heavily based on the user experience.

If you have any feedback or suggestions, send me an email

Great coding!

Exploring React Query: A Powerful Alternative for Server-Side State Management in React

Lucas Wolff — Tue, 06 Jun 2023 11:28:29 +0000

React offers a range of tools for managing state. Traditionally, developers have relied on libraries like Redux, Zustand, and the Context API to handle state management.

However, in the last few years React Query has gained attention for its unique approach to server-side state management. Today we will compare React Query with these established tools, and talk about the advantages it brings to server-side state management in React.

But first, we need to understand what is server-side state management and its difference to client-side state.

Understanding Server-Side State Management

In a typical web application, server-side state refers to information fetched from APIs, databases, and other external sources. Effective server-side state management ensures that the application remains in sync with the server and provides a smooth user experience.

Client-side state (a.k.a. global state), on the other hand, refers to data that is particular to the front-end of the application. Usually the data that is stored in client-side state is meant to be used across the application. Some examples are: isAuthenticated, isDarkMode, theme, userData.

One of the advantages of React Query over other solutions for server-side state is that you don't force asynchronous data to follow the synchronous flow of the application.

It's also worth mentioning that you can use two tools together to manage the states e.g., Redux for client-side and React-Query for server-side. This is considered a good practice, because it will split different responsibilities between more focused tools.

What is React Query?

React Query is a library specifically designed for managing remote data in React applications. Its key principle is to leverage the power of React's hooks to simplify asynchronous data fetching, caching, and synchronization.

React Query offers a straightforward API that is easy to understand and use, making it a great option for beginners. Compared to Redux or Zustand, which require additional setup and boilerplate code, React Query simplifies the process of managing server-side state, reducing the learning curve.

The boilerplate code needed to start using React Query is very small:

// 1. Wrapping the component with the provider
const queryClient = new QueryClient();
<QueryClientProvider client={queryClient}>
  <YourComponent />
</QueryClientProvider>;

// 2. Creating a service
const getItems = async () => {
  const response = await fetch("https://api.example.com/items");
  const data = await response.json();
  return data;
};

// 3. Calling the service in the component
const CACHE_KEY = "items";
const { data, isLoading, isError } = useQuery(CACHE_KEY, getItems);

And that's it! Now the component is ready to start automatically caching, invalidating and refetching data.

Following the above example, if the user navigates to nother page that has the same getItems call, the data will be served immediately from the cache, because React Query caches the result for a certain amount of time, which is configurable.

React Query vs. Redux

Redux is a widely adopted library for managing global state in React applications. It follows a centralized store approach, where the entire application state is stored in a single JavaScript object.

While Redux excels in managing complex state and enabling time-travel debugging, it often requires developers to write a significant amount of boilerplate code. As a result, Redux can be challenging for beginners to understand.

Nowadays Redux has evolved and it's much easier to start with, thanks to Redux Toolkit. It also has a library with the same purpose as React Query called RTK Query. It applies different concepts than React Query but the idea behind is quite the same.

// 1. Creating the store
export const store = configureStore({
  reducer: {
    [api.reducerPath]: api.reducer,
    // ... other reducers
  },
  middleware: (getDefaultMiddleware) =>
    getDefaultMiddleware().concat(api.middleware),
});

setupListeners(store.dispatch);

// 2. Wrapping the component with the redux provider
<Provider store={store}>
  <YourComponent />
</Provider>;

// 3. Creating a service
export const api = createApi({
  reducerPath: "api",
  baseQuery: fetchBaseQuery({ baseUrl: "https://api.example.com" }),
  // Endpoints definition
  endpoints: (builder) => ({
    items: builder.query({
      query: () => "items",
    }),
    // ... other endpoints
  }),
});

// 4. Calling it in the component
const { data, isLoading, isError } = useItemsQuery();

RTK Query is a powerful library, but when I read the above boilerplate code, it feels too much compared to React Query; there's a lot of stuff going on that may be abstracted to the developer.

React Query vs. Zustand

Zustand is a lightweight state management library that embraces a more decentralized approach compared to Redux. It provides a simple API for managing state as isolated stores, making it easier to work with and reducing boilerplate code.

Zustand's simplicity is appealing to beginners, but it lacks built-in server-side data fetching capabilities, which becomes a hurdle for managing server-side state effectively.

// 1. Creating the store
const useStore = create((set) => ({
  items: [],
  fetchItems: async () => {
    try {
      const response = await fetch("https://api.example.com/items");
      const data = await response.json();
      set({ items: data });
    } catch (error) {
      console.error("Error occurred while fetching items:", error);
    }
  },
}));

// 2. Calling it in the component
const { items, fetchItems } = useStore();

Zustand is pretty simple to start with, but its simplicity is also its weakness for dealing with server-side state. Although for managing client-side state it's a great library: easy to use, lightweight and has a great community.

React Query vs. Context API

The Context API is built into React and allows components to share state without prop drilling. It provides a way to pass data through the component tree without explicitly passing props at every level.

While Context API simplifies state sharing, it does not offer advanced features like caching, background data syncing, or error handling out of the box.

Implementing these features manually can be time-consuming and error-prone. There's also a considerable amount of boilerplate code needed to make it work.

// 1. Creating the context
export const ServerStateContext = createContext();

// 2. Creating a service
const getItems = async () => {
  const response = await fetch("https://api.example.com/items");
  const data = await response.json();
  return data;
};

// 3. Creating the provider
export const ServerStateProvider = ({ children }) => {
  const [items, setItems] = useState([]);

  useEffect(() => {
    const fetchItems = async () => {
      try {
        const data = await api.getItems();
        setItems(data);
      } catch (error) {
        console.error("Error occurred while fetching items:", error);
      }
    };

    // 4. Calling the service
    fetchItems();
  }, []);

  return (
    <ServerStateContext.Provider value={{ items }}>
      {children}
    </ServerStateContext.Provider>
  );
};

// 5. Calling the service in the component
const { items } = useContext(ServerStateContext);

Depending on how you implement Context API, you may see a lot of unnecessary re-renders, which can be hard to debug for beginners.

Final thoughts

React Query emerges as a powerful alternative for server-side state management in React applications. It offers simplified data fetching, intelligent caching, background data syncing, and error handling, which can significantly improve development productivity.

Compared to Redux, Zustand, and Context API, React Query provides a more beginner-friendly approach while maintaining advanced features necessary for server-side state management.

By combining React Query and other client-side state manager mentioned above, it's possible to create robust and performant applications, separating the concerns of state management and having a more defined architecture.

Remember, the choice of state management tool ultimately depends on the specific needs of your application. It's essential to evaluate the trade-offs and consider factors like project size, complexity, and development team experience.

If you have any feedback or suggestions, send me an email

Great coding!

7 actionable tips to get your PR approved (+ template)

Lucas Wolff — Mon, 05 Jun 2023 12:13:51 +0000

A great pull request is not only about correct code. Even if your code works and it's aligned with its purpose, it can be rejected by the reviewer. There are many reasons why this may happen, and today we'll discuss how to reduce this friction.

The techniques below are not meant to be applied on the code itself; they consider that all the requirements are fulfilled i.e. you did your job correctly, and also that merge conflicts are fixed, if they existed.

1. Keep your changes small and focused

This is one of the most common mistakes when opening a PR. It's very hard for the reviewer to understand and get context of a lot of files and lines being changed.

A big PR may be the result of your team's agreed workflow, or even of the way that you get the stories. The result is you ending up with a big PR that contains a lot of stuff. This is not wrong, it's just harder to understand.

One possible solution to this is to have one main feature branch, and other related branches that represent the steps to create the feature. When you finish your work, you'll merge all children branches into the main feature, and the main feature into the repository's main. Let me show you:

main
- feature/cart-component (main feature branch)
  - feature/cart-component/create-presentation (feature child)
  - feature/cart-component/create-tests (feature child)
  - feature/cart-component/fix-related-tests (feature child)
  - feature/cart-component/update documentation (feature child)

When using this approach, a good practice is to add links to the children's PRs on the parent, and vice-versa. This will help to not break the expectations of the reviewer when he/she sees an incomplete PR. Remember also to always rebase the new child PRs with the updated feature branch.

It's also very common to add non-related changes to the PR, like small refactors, for example:

Variable names;
Function names;
Indentation;
Improve unrelated logic;
etc.

Refactors are always welcome, but maybe the timing is wrong. If you choose to do these unrelated changes in your PR, be sure to add a comment on the updated lines explaining what and why you did it, and explicitly say that the changes are not related to the PR, but you took the chance to change. You got the idea.

2. All red / all green

I learned this concept with a past manager, and it helped me a lot on my PRs, and also on my code reviews.

The idea here is basically to have a PR where everything (or most of it is) is red or green. I know it's hard to do that, and sometimes can be impossible due to the nature of the feature or fix that you're working.

This is important because it will show upfront and at a high level what is being changed.

On the visual aspect, it's much more comfortable, easy to read and understand a change when everything has the same color. The intention is clear: you're adding or removing code, not replacing. This resonates with the idea behind the Open-closed principle (OCP):

Software entities should be open for extension, but closed for modification; that is, such an entity can allow its behavior to be extended without modifying its source code.

It's interesting to see the effect that this type of detail in your PR can represent at a software engineering level. It doesn't mean that every all green/red PR will be an application of OCP, but sometimes it can be the case.

If you can't have all green/red PRs, a good approach is to have commits applying this idea. This allows the reviewer to navigate between commits and understand their purposes much easier than if you have one huge commit per PR. I'll talk about that in the next topic.

3. Using commits as a documentation

When hiking, you need to strategically place anchors in order to prevent you from falling and losing your progress. When creating commits this is no different—apart from risking your life.

Ideal PRs have commits placed correctly. If you mess up your commits, you can cherry-pick them and re-create your commit history. This can be done via CLI or even using some Git GUI, which is faster and easier.

The same logic used to create focused and small PRs can be applied to commits. The ideal commit serves one purpose, and it's a surgical change on the codebase.

Try to avoid writing generic commit messages like:

fix auth
add cart feature
refactor component
update endpoint

These messages are almost meaningless when read without opening the change. They bring up some questions that can lead the reviewer to misunderstand the purpose of the change, and delay the review.

Instead of that, try to use commit message conventions and descriptive messages. Refactoring the examples above, we can have messages like:

fix auth → fix: correct authentication when token expires,
add mini cart → feat: create mini cart component AND feat: toggle mini cart on header cart icon click
refactor component → refactor: improve readability of UserList component
update endpoint → feat: add pagination params to GET /users endpoint

These improvements took a small effort and represent a great improvement in your PR's overall quality, increasing the chances to be approved.

Don't worry if your PR has a lot of commits with long messages. At the end you'll probably going to squash tem into one commit containing the feature description and merge it to the desired branch.

4. Over communicate in your PR description

Imagine that you enter a bookstore and see a book cover that catches your attention. You're excited and ready to read the book summary, but wait... there's no summary! You need to read some pages to get the idea of the book, and after a couple of minutes you lose your interest.

That's what a PR without a description is. This logic can also be extended to the PR's title.

At the same time, you don't want to copy the story description; the reviewer can go to the story and read all the specifications. The idea here is to describe the PR at the code level. A good idea is to create templates that will be the default description for every new PR. Here is an example:

Related to [#TICKET_NUMBER](#TICKET_URL).

# What?

<!-- Explain the overall effect that this PR will cause. -->

# Why?

<!-- Related to business and/or engineering objectives and goals. -->

# How?

<!-- Explain the design decisions and how you solved them. -->

# How to reproduce

<!-- Guide the reviewer on how to test it. Be very specific here. -->
<!-- Be aware that sometimes extra actions need to be taken to fully test the PR. e.g.. add some env var. -->

# Screenshots or video (optional)

<!-- Good to show the final result of your work in a "human way". -->

# Extra notes

<!-- Extra comments that you may have. -->
<!-- e.g., "Need to update env vars on the server after the deployment." -->

# Checklist

[] Current branch is rebased onto main branch
[] Dependent changes (packages) are merged and published
[] Added the necessary tests
[] New and existing unit tests are passing locally
[] The code follows the style-guide
[] There are no linting warnings and errors
[] No console warnings and errors were introduced
[] Added comments on not so clear logic
[] Documentation is updated

The above template is only an example and it has no means to be the best one. My intention is to give you some ideas to create your own. Keep in mind that having a template is always a work in progress: you will need to improve it, remove some stuff, and add others. It should also be aligned with the repository's purpose (front or backend, for example), and also with your team needs and workflow.

5. Make the reviewer's job easier

Doing code reviews can be an exhausting task. If your PR is the third of the day, probably the reviewer will not have the same attention as if it was the first one.

That's why it's important to give the right resources to the reviewer. Doesn't matter the type of change that is being proposed, you probably can provide some extra resources to help the reviewers on their jobs. Here are a few examples:

Screenshots;
Videos (use async video services like Loom);
Postman collections;
Scripts to run external tasks e.g., database migrations, infrastructure changes;
Specific testing credentials;
Access to third-party services for validation purposes;
etc.

Some of these resources can be critical to testing the PR (e.g., specific testing credentials). By omitting them from the reviewer, you increase the chances of having back and forth communication and a consequently delay on the review, or even a request for changes on the PR.

6. Review your own PR

You don't want to deliver to the world a code that was not even checked by you. Not only the code, but the PR's title, description and other subtle information that may not be contained in these places.

There is some information that may fit better if you put them as near as possible to the code. You can comment on the exact lines that you need, explaining behaviors more specifically and at a code level. A good example of the use of comments, is to explain changes not related to the PR e.g., small refactors.

This is the last step before assigning your PR to other people. Doing this you'll be behaving like a reviewer, seeing exactly what they will see during review. Here are some advantages of self-reviewing your PR:

Catch bugs on the code;
Ensure that all the requirements were fulfilled;
Identify missing information on the description;
Add extra information at code level (e.g., commenting on the lines);
Exercise your code review skills;

You can also create a draft pull request while you have work in progress, and then convert to a PR only when you're ready to assign it to others. Draft PRs doesn't send notifications to the reviewers, and also there are no chances to accidentally merge the code.

7. Review other PRs to gain experience

Doing code review doesn't directly increase the chances of your PRs to get approved. By doing this you'll train your code review skills "in the real world", and as a side effect you will write much better PRs.

Many people recommend reviewing PRs as the first task of your work day. This is a good rule, but depending on your environment this could not work very well. Sometimes a bug fix needs to be merged at the end of the day, or a PR needs to be merged because it's blocking another. Try to have a routine, but be flexible to change it as you go. As a developer, in general, you need to be flexible.

Code review is a huge topic that has content for multiple articles, but here are some actionable tips that you can start applying now:

Don't NIT too much, and if you do, don't block the merge. Every NIT is a chance to improve your linter;
Be kind and don't use aggressive or demanding words;
Be focused and don't multitask during the review;
Understand all the context around the PR before starting the review;
Communicate precisely to avoid back and forth;
Timebox to be more efficient and don't spend too much time.

There are a lot of other techniques, but as I mentioned, this is a topic for another article.

I want to also highlight the importance of doing reviews for the teams' synergy and also to enhance your PR-building skill. This is something that will follow you over your entire career, so it's important to always keep leveling-up.

Wrapping up

Don't take the comments on your code too personal, and don't be passive aggressive on your answers. No one knows everything, and this is fine. By writing good pull requests, you will help to reduce the code review time, and collaborate to increase your team's performance.

Which other techniques do you use? Let me know, I'd be interested to learn!

If you have any feedback or suggestions, send me an email

Great coding!

6 coding best practices to take you to the next level

Lucas Wolff — Wed, 31 May 2023 00:55:51 +0000

Today I'll talk about a topic that will follow you over your entire career as a software engineer: coding best practices. The practices below are more focused on people starting their careers, but they're valid for any level.

It's also worth mentioning that knowing about these practices are not only good for your day-to-day job, but also very important for technical interviews. Demonstrating knowledge on these practices are a great sign of experience and authority over the development process.

Why learn best practices?

Programming is an activity that is not only related to the act of writing code that works, and not restricted to the writing itself. There are a lot of other activities around that, involving conventions, teamwork definitions, and process improvements.

The average developer spends more time reading than writing code. Not only reading, but planning, thinking, debugging, choosing the best approaches, defining the right tools, and so on. These processes can always be improved, and some of them can be delegated to your computer.

It's kinda easy to write code that works, but not so easy to write code that is maintainable and easy to read. This is pretty well stated in this quote from Martin Fowler:

Any fool can write code that a computer can understand. Good programmers write code that humans can understand.

With that said, let's see some good practices that you can apply right now to your coding.

1. Meaningful naming conventions

It's very common to see on programming tutorials examples of variable and function names like:

var numsCount
const numsAmnt
function calcNumsAvg(fnum, lnum)
function calcAge(bdate)

The computer completely understands these commands, in fact, it will understand any name that you add as variable or function names (except reserved words).

The problem here is that you or other developer will need to read and/or give maintenance to this code in the future, when the context that you had when these namings were defined will not be on your head anymore. This can lead to more time spent trying to understand the code, or even a misunderstanding of its purpose.

Even if you understand the code and remember its purpose, another factor that needs to be considered is when new developers join the team. Having not so clear and explicit namings can lead to more time spent ramping-up.

The solution to this issue is to use meaningful naming conventions. Let's refactor the previous examples:

var numsCount → var numbersCounter
const numsAmnt → const numbersAmount
function calcNumsAvg(fnum, lnum) → function calculateNumbersAverage(firstNumber, lastNumber)
function calcAge(bdate) → function calculateAgeFromBirthdate(birthdate)

These namings are giving an explicit and clear context about what's going on to the reader. Talking about file size, the difference is not considerable, it's just a couple more chars. Even if it's more than a couple, it's a tradeoff that is worth it.

Another great advantage is that if you have self-explained namings, you can reduce the comments on the code. In many cases, the code becomes the documentation.

2. Use a code formatter

When you're coding, there are some decisions and procedures that can be delegated to the computer. One common example is the code formatting.

In languages like JavaScript, you need to take some decisions in order to have standards in your codebase:

Should I use single or double quotes?
Should I add semicolons at the end of my statements or not?
Should I use spaces or tabs?
Should the indentation be 2 or 4 spaces?

Having these definitions in place before starting a new project is crucial. When you're part of a team, this is even more crucial. Can you imagine if your team has 4 developers, and each one uses a different formatting rule? The code reviews will be a mess.

One of the tools that aim to solve this is Prettier. It is an opinionated code formatter that supports many languages, and the best part is that it integrates with your editor, so you can expect code formatting on every file save. Pretty cool, right?

You can play with some Prettier configurations on its playground.

3. Have a clear folder structure

When starting new projects, or even working on existing ones, it's important to always stick to a clear and predefined folder structure. This definition can be done based on the architectural pattern that is being used.

Having a clear folder structure has many advantages, like:

Faster ramping-up: when new developers join the team, they know where to find files/features;
Faster decisions: when you need to write new features, you already know where to put new files;
Faster debugging: you can speed up your search through the project;

It's also important to decide if you will use index files, default exports, camel-case or snake-case, for example. These definitions are very important to the standardization and success of the codebase.

There's no right or wrong definition. Choose one, share it with the team members, document if necessary, and stick to it.

Keep in mind that you don't need to keep it forever. If you want to change it in the future, just refactor your code. It can be hard, but it's possible. Nowadays, many IDEs have built-in features to help with that.

4. Know your editor or IDE

Like I've mentioned, usually a developer spends more time reading than writing code. That's why it's important to know how to optimize your editor or IDE use.

I've been using VSCode for a long time. But before that, I used Sublime Text, Atom, and even Eclipse and NetBeans.

Doesn't matter the editor or IDE that you choose. You need to feel comfortable and productive, because you will spend most of your day looking and interacting with it.

There are a lot of shortcuts and plugins that make developers' life easier, so it's very important to always keep an eye on the repetitive tasks that you execute, and also on the complex ones, because these can be simplified with plugins or shortcuts.

Most of the IDEs let you create snippets, which generates pieces of code much faster than if you have to type everything from scratch every time (React devs know the pain).

Here are some useful plugins and integrations that I use on my IDE:

Prettier (format everything on file save);
ESLint (give hints and suggestions about potential issues);
GitLens (integrates with Git and show useful info);
Syntax Highlighters for specific extensions (.hbs, .md, .json, .csv);
Markdown Preview (live preview for markdown files).
And much more.

Another tip is to save your IDE's configuration file (it's usually a JSON) on your GitHub or somewhere else, so you can reuse it if you need to reinstall your IDE, and you can also share it with other people.

5. Use Git wisely

Using the Git basics is simple, but you can level-up this skill with some simple actions.

It's very important, mostly when working on teams, to choose a commit convention and stick to it. This lets everyone know instantly what each commit, branch, and pull request means.

One pattern to write commit messages is to imagine the sentence "This commit will..." before the actual commit message. Conventional Commits is widely used by the community. It's, as defined, "A specification for adding human and machine readable meaning to commit messages". Here are some examples:

feat: create new user page
fix: correct submit button behavior
refactor: improve readability on UserList component
test: create tests for GET /payments endpoint

It's also worth using conventions to connect GitHub to your project management app (e.g., Jira, ClickUp). This is very useful not only for developers, but for other stakeholders.

Another good practice it's to have multiple tiny commits. I heard a great analogy from a past manager that I've worked with, that each commit is like a hiking anchor; if you fall, you'll be hanging on the last anchor that you fixed, so you're safe.

This is useful during code reviews, because each commit will represent one step of the solution, which can give more context to the reviewer and also will act like a documentation for the PR.

Another tip is to have aliases for some common and repetitive git tasks. Here are some examples to give you ideas:

ga → git add .
gs → git status
gc → git commit -m → gc "feat: add hover to buttons"
gps → git push -u → gps origin main
gpl → git pull → gpl origin

These aliases can be defined on the .bashrc, .zshrc, or the respective file that you use to configure your terminal.

There are also some concepts that you're not going to be using in the beginning but at some time they'll be essential to you as a developer:

6. Write code with the SRP mindset

SRP means Single-Responsibility Principle, and it's one of the five SOLID principles that Uncle Bob introduced to define good software engineering practices. The SRP on its definition means:

A class should have one, and only one reason to change, meaning that a class should have only one job.

What I mean by "SRP mindset" is to have attention to some details that may pass when you start coding. Sometimes this can be a helper method that is not very related to the class that it's defined in, a component that does more than one thing, or a logic that is repeated in more than one place.

I know that it's hard to see these improvement opportunities at first, but you'll get there with time and study. Some examples of situations that can be improved are:

A UserClass that also connects to the database, gets the users, parses the result, and returns it;
- It's a good idea to have repositories/entities to deal with database logic;
- Parsing can be extracted to a helper or utility class/function.
A logic that is repeated in many places;
- Abstract this logic into a class or function, and call it in these places.
A React component called ProductsList that also implements each product's presentation, the buttons, the data fetch and has all the logic for each button action;
- Create a ProductCard component to make it reusable;
- Create PurchaseButton and AddToCartButton components with specific logic and make them reusable.
- Abstract the fetch logic into hooks and services;

And the list goes on... This is a very subjective topic, and there are many different opinions around it.

If you want to know more about that, I wrote an article about SRP in React apps.

Conclusion

These coding best practices are only a few of them, and this is a topic that you'll probably be studying for your entire career as a developer. Don't try to apply everything beforehand, first identify the opportunity of improvement on the code or process, and then choose the best solution. After that, analyze and reiterate.

If you have any feedback or suggestions, send me an email: lucashwolff@gmail.com.

Great coding!

How to apply the Single-Responsibility Principle in React

Lucas Wolff — Sat, 27 May 2023 21:20:53 +0000

The simplicity of building components with React is what makes it hard to understand for some people. The idea behind component-based architecture is to create modular and reusable user interfaces, but this is not a rule when building React applications, since the library doesn't force you to follow these principles.

React lets you create components in the way that you want, which is great but can also lead to a codebase that is hard to understand and maintain. Today I'll show you my approach to apply one of the SOLID principles, the SRP (Single-Responsibility principle), to component-building and as a result, have a cleaner and easy-to-test codebase.

What is the SRP?

The Single-Reponsibility principle, also known as SRP, is the first SOLID principle. Those principles were created by Uncle Bob for object-oriented programming, to establish software engineering practices to help maintain and extend the codebase as the project grows. Adopting these practices can also contribute to avoiding code smells, easier testing, and less refactoring.

The SRP on its definition means:

A class should have one, and only one reason to change, meaning that a class should have only one job.

This is quite simple to understand, right? Every class, function, and component, should have a very clear and defined purpose. But wait... React don't use OOP principles. It also doesn't apply or reinforce any OOP mechanism (inheritance, polymorphism, etc.). Even when using class-based components, it doesn't behave as an OOP library (e.g., you cannot call a method from one class on another).

So how are we going to apply SRP to our React code?

Applying SRP to React

You cannot apply the SRP by the book on React, but you can apply de idea behind the principle to your applications.

This is when the concept of layers comes in place. Looking at components with the layers perspective was a game-changer to me when I started learning React. My approach is to modularize not only the component, but also the features and shared logic:

Utilities layer: the utils, containing short and specific functions to build bigger things with;
Feature layer: the hooks, containing reusable features e.g., fetching data, handling forms;
Presentation layer: the components, as specific as possible.

Note that this approach has nothing to do with the layered architecture, clean architecture or any other application-wise modularization. This is more like a way to build reusable and clean components, which you can use along any architectural pattern that you choose.

With all that in mind, let's jump to the code!

The example application

For our examples, let's progressively build a simple UserCards component, which receives user data, shows a loading state, and then renders it on the screen on some pretty cards.

For the sake of simplicity, I'm not showing any CSS code or the content of fetchUsers(), but you can assume that it's an asynchronous function that returns all the users.

If you want to see the entire code, check my GitHub repository. Each commit represents one step of this article. At the end of each section you'll find the link for the respective commit.

Final result:

The code:

// src/components/UserCards.jsx

const UserCards = () => {
  const [users, setUsers] = useState([]);
  const [isLoading, setIsLoading] = useState(false);

  useEffect(() => {
    setIsLoading(true);
    fetchUsers()
      .then((data) => {
        setUsers(data);
      })
      .catch((error) => {
        console.error(error);
      })
      .finally(() => {
        setIsLoading(false);
      });
  }, []);

  const getAgeFromBirthdate = (birthdate) => {
    const birthday = +new Date(birthdate);
    return ~~((Date.now() - birthday) / 31557600000);
  };

  const handleCallClick = (phoneNumber) => {
    window.open(`tel:${phoneNumber}`);
  };

  const handleSendEmailClick = (email) => {
    window.open(`mailto:${email}`);
  };

  return (
    <section className="section">
      {isLoading ? (
        <svg
          aria-hidden="true"
          className="w-16 h-16 text-gray-200 animate-spin fill-teal-600"
          viewBox="0 0 100 101"
          fill="none"
          xmlns="http://www.w3.org/2000/svg"
        >
          <path
            d="M100 50.5908C100 78.2051 77.6142 100.591 50 100.591C22.3858 100.591 0 78.2051 0 50.5908C0 22.9766 22.3858 0.59082 50 0.59082C77.6142 0.59082 100 22.9766 100 50.5908ZM9.08144 50.5908C9.08144 73.1895 27.4013 91.5094 50 91.5094C72.5987 91.5094 90.9186 73.1895 90.9186 50.5908C90.9186 27.9921 72.5987 9.67226 50 9.67226C27.4013 9.67226 9.08144 27.9921 9.08144 50.5908Z"
            fill="currentColor"
          />
          <path
            d="M93.9676 39.0409C96.393 38.4038 97.8624 35.9116 97.0079 33.5539C95.2932 28.8227 92.871 24.3692 89.8167 20.348C85.8452 15.1192 80.8826 10.7238 75.2124 7.41289C69.5422 4.10194 63.2754 1.94025 56.7698 1.05124C51.7666 0.367541 46.6976 0.446843 41.7345 1.27873C39.2613 1.69328 37.813 4.19778 38.4501 6.62326C39.0873 9.04874 41.5694 10.4717 44.0505 10.1071C47.8511 9.54855 51.7191 9.52689 55.5402 10.0491C60.8642 10.7766 65.9928 12.5457 70.6331 15.2552C75.2735 17.9648 79.3347 21.5619 82.5849 25.841C84.9175 28.9121 86.7997 32.2913 88.1811 35.8758C89.083 38.2158 91.5421 39.6781 93.9676 39.0409Z"
            fill="currentFill"
          />
        </svg>
      ) : (
        users.map((user) => (
          <div key={user.id} className="user-card">
            <img src={user.profilePictureUrl} className="profile-picture" />
            <span className="name">{user.name}</span>
            <div className="text-wrapper">
              <span className="role">{user.role}</span>
              <span className="age">
                {getAgeFromBirthdate(user.birthdate)} years old
              </span>
            </div>
            <div className="actions-wrapper">
              <button
                className="button-ghost"
                onClick={() => handleCallClick(user.phoneNumber)}
              >
                Call me
              </button>
              <button
                className="button-primary"
                onClick={() => handleSendEmailClick(user.email)}
              >
                Send email
              </button>
            </div>
          </div>
        ))
      )}
    </section>
  );
};

Well, that's some messy code! Let's improve it, step by step.

GitHub commit for this step.

The Utilities Layer

You can notice that some of the functions and behaviors that UserCards has, aren't only related to it:

getAgeFromBirthdate()
window.open(tel:xxxx)
window.open(mailto:xxxx)

These behaviors can be extracted as utils, so they can be reused across other places of our app that require the same functionality. Let's create these util files:

// src/utils/date.js

export const getAgeFromBirthdate = (birthdate) => {
  const birthday = +new Date(birthdate);
  return ~~((Date.now() - birthday) / 31557600000);
};

// src/utils/contact.js

export const openCallPhoneNumber = (phoneNumber) => {
  window.open(`tel:${phoneNumber}`);
};

export const openSendEmail = (email) => {
  window.open(`mailto:${email}`);
};

Great! We just extracted some functionality that was not restricted to the component, and now other components can make use of it without needing to re-create. Another huge advantage is that we can now test each util function individually, instead of only testing the component as a whole. This makes the application more reliable and decoupled.

Now we need to import the utils into the UserCards component, and replace the old function calls with the new ones. The component will look like this:

// src/components/UserCards.jsx

// Utils imports
import { getAgeFromBirthdate } from "../utils/date";
import { openCallPhoneNumber, openSendEmail } from "../utils/contact";

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

  const handleCallClick = (phoneNumber) => {
    openCallPhoneNumber(phoneNumber); // Calling the util
  };

  const handleSendEmailClick = (email) => {
    openSendEmail(email); // Calling the util
  };

  return (
    <section className="section">
      {/* ... */}

      <div className="text-wrapper">
        <span className="role">{user.role}</span>
        <span className="age">
          {getAgeFromBirthdate(user.birthdate) /* Calling the util */}
          years old
        </span>
      </div>

      {/* .. */}
    </section>
  );
};

GitHub commit for this step.

The Features Layer

The only feature that we have in our example is the one that gets the user, sets it on the state and also manages the load state according to the status of the request. Let's break the "fetch users" feature:

When the component loads, the process of getting the users starts on the useEffect;
The isLoading state needs to be set to true to give feedback to the user;
The function will make an asynchronous request to the API to fetch the data;
If the call succeeds, we set the data to the state (setUsers(data));
Otherwise, we just print the error on the console;
In both cases, at the end, we'll change the isLoading state to false to show the data on the UI.

This behavior is represented on the following code:

// src/components/UserCards.jsx

const UserCards = () => {
  const [users, setUsers] = useState([]);
  const [isLoading, setIsLoading] = useState(false);

  useEffect(() => {
    setIsLoading(true); // Sets loading state
    fetchUsers() // API call
      .then((data) => {
        setUsers(data); // Success: persist data to the state
      })
      .catch((error) => {
        console.error(error); // Print error on the console
      })
      .finally(() => {
        setIsLoading(false); // Remove loading state
      });
  }, []);

  // ...
};

There's nothing wrong with this code. Although, if we need to fetch users on other components, this logic will be duplicated. This is the point where things start to get messy, because this logic will be coupled to each component, making it hard to test (same case as the utils) and also maintain. If the "fetch users" logic changes, you'll need to change it in all the components that you're calling it.

The solution to this issue is abstract the logic into a hook. If a component needs to "fetch users", it just needs to call the hook and that's it. So let's create this hook:

// src/hooks/useFetchUsers.js

export const useFetchUsers = () => {
  const [users, setUsers] = useState([]);
  const [isLoading, setIsLoading] = useState(false);

  useEffect(() => {
    setIsLoading(true);
    fetchUsers()
      .then((data) => {
        setUsers(data);
      })
      .catch((error) => {
        console.error(error);
      })
      .finally(() => {
        setIsLoading(false);
      });
  }, []);

  return { users, isLoading };
};

It's basically copy-paste from the code that we already had. Now let's refactor the UserCards component:

// src/components/UsersCard.jsx

// Hook import
import { useFetchUsers } from "../hooks/useFetchUsers";

const UserCards = () => {
  const { users, isLoading } = useFetchUsers(); // Hook call

  const handleCallClick = (phoneNumber) => {
    openCallPhoneNumber(phoneNumber);
  };

  const handleSendEmailClick = (email) => {
    openSendEmail(email);
  };

  // ...
};

Much cleaner, right? Now you have all the advantages of decoupling, reusability and also a better readability.

GitHub commit for this step.

The Presentation Layer

Last but not least, let's improve our JSX code. There are some elements that can be extracted from this component:

Loading component (SVG);
User card (the code inside the map);
The buttons.

// src/components/UserCards.jsx

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

  return (
    <section className="section">
      {isLoading ? (
        // Loading component
        <svg>{/* ... */}</svg>
      ) : (
        users.map((user) => (
          // User card
          <div key={user.id} className="user-card">
            {/* ... */}

            <div className="actions-wrapper">
              {/* Buttons */}
              <button
                className="button-ghost"
                onClick={() => handleCallClick(user.phoneNumber)}
              >
                Call me
              </button>
              <button
                className="button-primary"
                onClick={() => handleSendEmailClick(user.email)}
              >
                Send email
              </button>
            </div>
          </div>
        ))
      )}
    </section>
  );
};

Let's abstract these components:

// src/components/Loading.jsx

const Loading = () => (
  <svg
    aria-hidden="true"
    className="w-16 h-16 text-gray-200 animate-spin fill-teal-600"
    viewBox="0 0 100 101"
    fill="none"
    xmlns="http://www.w3.org/2000/svg"
  >
    <path
      d="M100 50.5908C100 78.2051 77.6142 100.591 50 100.591C22.3858 100.591 0 78.2051 0 50.5908C0 22.9766 22.3858 0.59082 50 0.59082C77.6142 0.59082 100 22.9766 100 50.5908ZM9.08144 50.5908C9.08144 73.1895 27.4013 91.5094 50 91.5094C72.5987 91.5094 90.9186 73.1895 90.9186 50.5908C90.9186 27.9921 72.5987 9.67226 50 9.67226C27.4013 9.67226 9.08144 27.9921 9.08144 50.5908Z"
      fill="currentColor"
    />
    <path
      d="M93.9676 39.0409C96.393 38.4038 97.8624 35.9116 97.0079 33.5539C95.2932 28.8227 92.871 24.3692 89.8167 20.348C85.8452 15.1192 80.8826 10.7238 75.2124 7.41289C69.5422 4.10194 63.2754 1.94025 56.7698 1.05124C51.7666 0.367541 46.6976 0.446843 41.7345 1.27873C39.2613 1.69328 37.813 4.19778 38.4501 6.62326C39.0873 9.04874 41.5694 10.4717 44.0505 10.1071C47.8511 9.54855 51.7191 9.52689 55.5402 10.0491C60.8642 10.7766 65.9928 12.5457 70.6331 15.2552C75.2735 17.9648 79.3347 21.5619 82.5849 25.841C84.9175 28.9121 86.7997 32.2913 88.1811 35.8758C89.083 38.2158 91.5421 39.6781 93.9676 39.0409Z"
      fill="currentFill"
    />
  </svg>
);

// src/components/Button.jsx

const Button = ({ text, onClick, variant }) => {
  const variantClassName = {
    primary: "button-primary",
    ghost: "button-ghost",
  }[variant || "primary"];

  return (
    <button className={variantClassName} onClick={onClick}>
      {text}
    </button>
  );
};

// src/components/UserCard.jsx

import { getAgeFromBirthdate } from "../utils/date";
import { openCallPhoneNumber, openSendEmail } from "../utils/contact";
import { Button } from "./Button";

const UserCard = ({ user }) => (
  <div className="user-card">
    <img src={user.profilePictureUrl} className="profile-picture" />
    <span className="name">{user.name}</span>
    <div className="text-wrapper">
      <span className="role">{user.role}</span>
      <span className="age">
        {getAgeFromBirthdate(user.birthdate)} years old
      </span>
    </div>
    <div className="actions-wrapper">
      <Button
        variant="ghost"
        text="Call me"
        onClick={() => openCallPhoneNumber(user.phoneNumber)}
      />
      <Button text="Send email" onClick={() => openSendEmail(user.email)} />
    </div>
  </div>
);

And here's our final UserCards component:

// src/components/UserCards.jsx

import { Loading } from "./Loading";
import { UserCard } from "./UserCard";

const UserCards = () => {
  const { users, isLoading } = useFetchUsers();

  return (
    <section className="section">
      {isLoading ? (
        <Loading />
      ) : (
        users.map((user) => <UserCard key={user.id} user={user} />)
      )}
    </section>
  );
};

Like we've seen before, this improves the testability, readability, and also decouples the components as well.

GitHub commit for this step.

Conclusion

My goal here was to show you my approach to component-building, and also give you some ideas for improving your own process. This is not in any kind a rule or the best approach ever to solve the problems that I'd show you.

Always keep in mind that the best process is the one that fits your needs and the needs of your team.

If you have any feedback or suggestions, send me an email: lucashwolff@gmail.com.

Great coding!

Forem: Lucas Wolff

The Responsive Web Design Guide For Developers

CSS Breakpoints and Media Queries

Mobile First Design

The Viewport Meta Tag

Designing for Different Screen Sizes

Leveraging CSS Flex-box and Grid

The Power of CSS Frameworks

CSS Viewport Units

Conclusion

CSS Colors: Understanding RGB, HEX, HSL, and Alpha Values

tl;dr

10 Key Takeaways:

Intro

RGB (Red, Green, Blue)

HEX Codes

HSL (Hue, Saturation, Lightness)

Understanding Alpha Values

Color Palettes and Schemes

Understanding Color Theory and Perception

Color Spaces and Gamut

Conclusion

How to Debug CSS (using CSS)

The border approach

The background-color approach

Wrapping up

Path Mapping in TypeScript with Vite

TypeScript Path Mapping

Vite + TypeScript Path Mapping

Adding paths manually

Using vite-tsconfig-paths

Best Practices for Creating a Folder and File Structure for a React Application

Disclaimer

Top-Level Folder Structure

The src/ Folder

src/adapters

src/assets

src/components

src/contexts

src/hooks

src/pages

src/services

src/utils

File Naming Conventions

Conclusion

The Definitive Guide to Make API Calls in React

The scenario for our example

Creating the API endpoints

1. Retrieving all the items

2. Creating a new item

3. Marking an item as done

4. Removing an item

Final code for the first part of the example

First Refactor: Creating Services

Second Refactor: Abstracting the HTTP call

Third Refactor: Creating Hooks

Last Refactor: Adding the Loading State

Bonus Refactor: Create an Utility

Wrapping Up

Optimistic UI: Enhancing User Experience in React with React Query

The Traditional Method

Understanding Optimistic UI

The scenario for our examples

Pessimistic Updates without React Query

Optimistic Updates without React Query

Pessimistic Updates with React Query

Optimistic Updates with React Query

Wrapping up

Exploring React Query: A Powerful Alternative for Server-Side State Management in React

Understanding Server-Side State Management

What is React Query?

React Query vs. Redux

React Query vs. Zustand

React Query vs. Context API

Final thoughts

7 actionable tips to get your PR approved (+ template)

1. Keep your changes small and focused

2. All red / all green

3. Using commits as a documentation

4. Over communicate in your PR description

The `border` approach

The `background-color` approach

Using `vite-tsconfig-paths`

`src/adapters`

`src/assets`

`src/components`

`src/contexts`

`src/hooks`

`src/pages`

`src/services`

`src/utils`