Forem: Juan Otálora

🎨 👉 Start doing THIS to improve your CSS Architecture

Juan Otálora — Sun, 03 Sep 2023 12:30:14 +0000

In frontend development, there are two types of people: those who enjoy creating layouts and those who use Vanilla CSS. Just kidding. Vanilla CSS can have significant advantages, such as having complete control over your styles and understanding the purpose of each element. But let's be honest: even though the spec keeps improving with each version, using CSS can sometimes be a bit tedious, especially in the beginning when we're not entirely sure what each prop is for, and of course, unexpected results can happen.

Today, I'm here to talk to you about one of the best decisions I've made regarding CSS, which I now incorporate into all my projects (unless I opt for using a library like Tailwind). I'm talking about CSS Modules.

/* style.module.css */

.saveButton {
    color: green;
}

// form.jsx

import styles from "./styles.module.css"

export const Form = () => {
    // ...
    return (
        <form onSubmit={handleOnSubmit}>
            <input name="email" />
            <button className={styles.saveButton} />
        </form>
    )
}

Collisions between ClassNames

If you've used BEM or some class naming convention to improve your CSS architecture, you've probably noticed that as your codebase grows, it becomes easier for these class names to collide with each other. Sometimes, it can even happen with a component library you have installed.

This is chaotic. Moreover, thinking of names for classes and their various derivatives can be a tedious job, even though the component's name and its properties can help with this.

So, what does CSS Modules do to help us with this?

CSS Modules or How to Isolate Your Styles

Using CSS Modules accomplishes three main things:

👉 Avoiding conflicts between class names
👉 Easy and quick refactoring
👉 Avoiding the use of anti-patterns like global scope

Let's delve into each of these in more detail:

Avoiding Collisions

By definition, styles in CSS Modules are scoped, meaning they only affect the element to which they are applied. Therefore, even if there are multiple styles that refer to the same element in your project, it will only be applied to the one that has been explicitly referenced.

For example:

/* style.module.css */

.title {
    font-weight: bolder;
}

// header.jsx

import styles from "./styles.module.css"

export const Header = () => {
    // ...
    return (
        <div>
            <h1 className={styles.title}>Hello world!</h1> {/* ✅ Style applied */}
            <h2 className="title">This is my first post</h2> {/* ❌ Style NOT applied */}
        </div>
    )
}

The importance of all this lies in how this code is processed and how these class names appear when the application runs in the browser. Let's look at an example of what Next.JS does, although the result may depend on the framework you use or the configuration you set up:

👨‍💻 Input:

/* ProgressBar.module.css */

.background, .bar {
    height: 4px;
    border-radius: 999px;
}

.background {
    background-color: var(--color-secondary);
    width: 100%;
}

.bar {
    background-color: var(--color-primary);
}

// ProgressBar.tsx

import styles from "./ProgressBar.module.css";

interface Props {
  percentage: number;
}

export const ProgressBar = ({ percentage }: Props) => {
  return (
    <div className={styles.background}>
      <div className={styles.bar} style={{ width: `${percentage}%` }} />
    </div>
  );
};

🖥️ Output:

<div class="ProgressBar_background__v_qdp">
    <div class="ProgressBar_bar__YFKLn" style="width: 50%;"></div>
</div>

As you can imagine, what CSS Modules does in one way or another to achieve style scoping is to add a hash to the classes. In this case, to make it easier to read and debug the application, the module name appears before the hash, followed by the class name: module_class__hash.

But as mentioned earlier, this is the example for Next.JS; it will work differently with other frameworks or configurations.

If you found this helpful or enjoyable, add a reaction! ❤️ Your likes are appreciated and keep me motivated!

Easy Refactoring

Since we treat CSS files as modules and class names as variables exported by these modules, renaming classes or identifying unused ones is easier than ever.

However, a word of caution! ⚠️ It's essential that even though class name collisions may not occur, the naming of classes should still follow a convention. While BEM may no longer provide much value, it's important for your team to establish a naming convention that works for you. CSS Modules won't solve naming issues.

For example, what if we want to change our Button component to ActionButton? Let's first look at an example with BEM:

/* (BEFORE) Button.css */

.Button_label {
    text-transform: uppercase;
}

/* (AFTER) ActionButton.css */

.ActionButton_label {
    text-transform: uppercase;
}

// (BEFORE) Button.tsx

import "./Button.css";

export const Button = ({ label }) => {
  return (
    <button>
        <span className="Button_label">{label}</span>
    </button>
  );
};

// (AFTER) ActionButton.tsx

import "./ActionButton.css";
import Icon from "icons"

export const ActionButton = ({ label }) => {
  return (
    <button>
        <Icon />
        <span className="ActionButton_label">{label}</span>
    </button>
  );
};

As you can see, changing the component name isn't straightforward because you have to change all the class names (and we're lucky there's only one in this case). Even though modern IDEs have powerful find-and-replace tools, it's always easier when class names aren't coupled to the component name.

Now, let's look at an example using CSS Modules:

/* (BEFORE) Button.module.css */

.label {
    text-transform: uppercase;
}

/* (AFTER) ActionButton.module.css */

.label {
    text-transform: uppercase;
}

// (BEFORE) Button.tsx

import styles from "./Button.module.css";

export const Button = ({ label }) => {
  return (
    <button>
        <span className={style.label}>{label}</span>
    </button>
  );
};

// (AFTER) ActionButton.tsx

import styles from "./ActionButton.module.css";
import Icon from "icons"

export const ActionButton = ({ label }) => {
  return (
    <button>
        <Icon />
        <span className={style.label}>{label}</span>
    </button>
  );
};

As you can see, by not referencing component names, they are more decoupled, and it's easier to make changes like this.

Avoiding Anti-Patterns

While CSS doesn't prevent poor CSS architecture, it does help with following some best practices like componentizing your projects or avoiding global styles.

Let's talk about componentization, a practice that became tremendously popular with the rise of web frameworks and libraries like Angular, React, or Vue. It's crucial for achieving reusability in your application (although, like everything, you need to determine the limit of how much you refactor).

CSS Modules motivate us to have a style file for each component, with these styles always going hand in hand with changes in component naming. In other words, it doesn't matter if the component goes from being called Button to ActionButton; the styles are decoupled as they are scoped.

Getting Started with CSS Modules 🚀

Unlike Vanilla CSS, CSS Modules may require some preparation before use. It depends on your bundler, pre-processors, and whether you're using TypeScript in your project or not:

Webpack: This is one of the cases that requires more documentation, but fortunately, you'll find several boilerplates like this one.
Next.JS: The trendy web framework has native support for CSS Modules. You just need to start creating .module.css files.
Vite: CSS Modules are also natively compatible with Vite, so you won't have to do anything special to start using them.

I'd love to hear your thoughts on this! What do you think? Feel free to drop a comment below and share your perspective with me! 💬

✨🕵️‍♂️ Top 7 things I check most in PRs as a Frontend engineer

Juan Otálora — Sat, 26 Aug 2023 10:25:47 +0000

In my time as a frontend developer, I've noticed that I end up reviewing the same errors in Pull Requests. Here are some of the most common ones I've come across.

1. Tricky layouts

Until FlexBox came along, CSS layouts were a complicated thing, and that's why all the webs in the 90's ended up looking the same. A header at the top, menus on the sides, and in the middle, a main section where the content went (poorly structured).

Now that we have FlexBox (one of my favorite CSS properties), sometimes we think it's a cure-all, that it's good for absolutely everything. To a hammer, everything looks like a nail.

CSS Grid arrived to solve many of the problems that frontend developers were still facing despite all the advantages of FlexBox. Often, we insist on using Flex for a certain layout when Grid can be much more interesting.

For example, one of the most underrated properties for creating frontend layouts is grid-template-areas. Take a look at its documentation and you'll see how it simplifies layout creation.

Here are some resources for you to learn more about the topic: 😊

2. Really bad naming

Just because you understand a function right now doesn't mean you'll understand it a month from now. Even less so if it is read by a teammate.

Naming is one of the most critical things when we develop. Bad naming means spending more time figuring out what certain parts of the application do, which makes us less productive and causes more frustration.

If you're concerned about your lines getting too long, use a formatter like Prettier and reach a consensus within the team.

// ❌
const elements = await getElementsFromGroup();
// ✅
const groupElements = await getElementsFromGroup();

// ❌
const getDate = () => {...}
// ✅
const getCurrentISODate = () => {...}

// ❌
const selected = selectedElement.id === element.id;
const focus = focusElement.id === element.id;
// ✅
const isSelected = selectedElement.id === element.id;
const isFocus = focusElement.id === element.id;

3. Inline variables

Sometimes, we try to simplify our code so much that we end up seriously impair its readability. The issue with lengthy files, classes, or functions isn't necessarily because you're leaving blank lines between your statements; it might be a problem with separating responsibilities (as discussed in the previous two sections).

To enhance the readability of your codebase, I recommend extracting as many constants as possible. Your project will become much more semantic, easier to read, and less prone to human errors.

// ❌
if (date > Date.now()) {...}
// ✅
const isFutureDate = date > Date.now();
if (isFutureDate) {...}

// ❌
<Button disabled={cart.elements.length === 0} />
// ✅
const isShoppingCartEmpty = cart.elements.length;
<Button disabled={isShoppingCartEmpty} />

If you found this helpful or enjoyable, add a reaction! ❤️ Your likes are appreciated and keep me motivated!

4. Unused code

Most of the time, when we refactor code, we tend to forget to review the old codebase we wanted to replace.

To keep projects as clean as possible, don't forget to remove all those files, functions, classes, hooks, or constants that got scattered throughout the project and are likely to be forgotten.

I recommend using one of the inspection tools provided by your IDE or installing a plugin to assist you with this task.

5. Magic literals

Sometimes, we think it might be a good idea to have literals dispersed throughout our codebase, what we commonly call magic numbers, but they can also be strings or booleans.

These values are typically used for default values or configurations, but it's important to give them meaning.

// ❌
const [zoom, setZoom] = useState(100);
// ✅
const DEFAULT_ZOOM = 100;
const [zoom, setZoom] = useState(DEFAULT_ZOOM);

// ❌
const createUser = (name) => ({
  name,
  isPremium: false
})
// ✅
const DEFAULT_IS_PREMIUM_USER = false;
const createUser = (name) => ({
  name,
  isPremium: DEFAULT_IS_PREMIUM_USER
})

6. Incorrect use of Testing Library

Testing Library is the library that has saved the most computers from being thrown out of the window. Testing interfaces is now much easier, but if you're not too experienced, there's one thing that can be tedious: rendering and the asynchrony problems that come with it.

When to use act() and when not to use it? When to use findBy, getBy or queryBy? Should I always use waitFor to avoid problems?

Kent C. Dodds, the creator of this library, wrote an article in which he described some of the most common mistakes we tend to make when using Testing Library. No matter how skilled you are at using the library, you're bound to be surprised by some of Kent's comments.

// ❌
const { getByRole } = render(<Form />);
const button = getByRole("button");

// ✅
render(<Form />);
const button = screen.getByRole("button");

7. Typos

Please, if your IDE doesn't have a spell-check tool, install a plugin that performs this function (even if English is your native language).

Your team members will thank you. 🙂

Now, seriously. The names we give to variables, functions, or classes are often challenging to read because we can't add spaces to separate the different words. There are some naming conventions like "snake case" or "kebab case" where typos are more easily detected, but before imposing casing conventions on the team, install a plugin that helps you detect typos.

// ❌
const youAreAnAwesmePerson = "🙂";
// ✅
const youAreAnAwesomePerson = "🙂";

BONUS! Don't check your own PR

When we start developing a new user story, our initial idea of it is often quite different from what it will be when we finish.

As we progress in development, we encounter situations that weren't covered in the acceptance criteria. Therefore, it's quite normal for our code to pivot as we realize these details that were initially overlooked.

Sometimes, we think the best developer to review a Pull Request is the one with the most time on the project or the most senior developer. But I believe the person who can review a PR best is the one who code it. Why?

👍 They know the task and its acceptance criteria the best.
👍 They are most familiar with the functions/classes/components they created.
👍 They can quickly spot code that's no longer in use.
👍 They are the ones who best realise how things could be done better.

However, it's crucial to be honest with oneself. Otherwise, it's a waste of time.

Still, it's always a good practice to have another colleague take a look to catch things you might have missed. Or if you prefer, you can use other tools like Pair Programming. It's up to you.

I'd love to hear your thoughts on this! What do you think? Feel free to drop a comment below and share your perspective with me! 💬

How to shift the mindset of a development team?

Juan Otálora — Mon, 21 Aug 2023 19:14:40 +0000

It's challenging to make core changes within a team when the established way of working is deeply ingrained, everyone follows the same methods, and they are unaware of the negative impact this is having on the project.

From technical debt to poor architecture or even communication issues, the perfect team doesn't exist, and we shouldn't expend effort trying to achieve it. According to statistics, reaching perfection, attaining that 100% in a team, is too costly for the limited value it can provide. This is analogous to speed; the fastest we can go is C the speed of light in space, but the immense amount of energy required to reach this speed makes going at 90% C a much more intelligent decision.

The first step in changing a team's way of working is identifying its shortcomings, analyzing them, and finally deciding which one to solve first. In this case, I will share my personal experience of changing the front-end architecture in an application developed by multiple teams simultaneously.

Get Them Involved in the Change

Allocate time (as much as needed, depending on the scale of the change) to communicate the problem to the team. It's crucial that they understand it. The sooner the problem is understood, the sooner there will be a willingness to change.

Beware of analysis paralysis. It's essential to contemplate the change and be aware of its repercussions, but get to work as soon as possible. If you're still not certain, develop proof of concept tests. Involve the rest of the team in these trials; it will help them understand the reason behind the change.

Keep in mind that people tend to stick to their routines and resist changes, especially when those changes could affect their standing in the team. For instance, if you want to revoke a suggestion made by a fellow team member, it might be tougher to persuade them compared to others because it challenges their established thought process and values. In such situations, I suggest having a conversation with that individual beforehand, addressing the issues arising from the proposed action, and attempting to gain their support for the adjustment.

In summary: learn to listen, understand others' problems, and respect different viewpoints. Attacking someone's ideals is essentially counterproductive, no matter how misguided their thinking might seem.

If you found this helpful or enjoyable, add a reaction! ❤️ Your likes are appreciated and keep me motivated!

"Why" Before "How"

James Clear explains in Atomic Habits that there are three ways to sustain habits over time:

Because we have to.
Because we have a milestone to achieve.
Because we believe in it and its benefits.

Clearly, the path we choose will yield different results. The first, the path of obligation, is easy to start but challenging to maintain because there's no underlying incentive. The second, the milestone path, is somewhat more complex because we need a reasonable goal that we wholeheartedly believe in, but its duration ends once the milestone is reached. The last one is the most challenging of all. It requires a mindset change, a shift in principles, which isn't hard, but once achieved, it will help sustain the change as long as the new mindset persists.

For making changes within a team, I strongly discourage the first option unless it's a temporary measure requiring urgent application. The second is usually relatively easy to apply; it doesn't require much preparation time (just defining a milestone), and it can be combined with the third and most interesting option, as it can lead to a lasting change in the team.

Another advantage of instigating a mindset change in the team is that you create a self-sustaining network that doesn't need anyone to govern them. When the team believes in what they're doing, they don't require bosses to give orders, only leaders to help them keep growing.

Keep the Leaders Close

Something not essential but highly beneficial is to identify and stay close to the leaders of the teams. And mind you, don't confuse leaders with bosses. People obey a boss because they have power over them, but they follow a leader because they believe in and trust what they do and say. In some cases, the boss figure may coincide with the leader, but it doesn't necessarily have to.

Identify those individuals who have the trust of the teams you want to change and involve them in the process. Explain the solution you propose, the advantages it will bring (why before how), and listen to their suggestions.

Remember, if you can convince them of the principles underlying the proposed change, everything else will become much more straightforward.

Practice, Practice, Practice

No matter how much effort you've put into the previous points, you'll realize that you won't always have the confidence or attention of 100% of the team. In these cases, it's a good idea to carry out a small practical activity just before implementing.

In the case of a front-end architecture change, conducting a "kata" led by the person who spearheaded the change is usually a good idea. You'll notice that many people who seemed absent in the analysis meetings will join the change train when they firsthand understand the benefits.

You may have spent a lot of time trying to explain the "why" behind things, but some people simply lack the motivation or understanding and may not express their confusion. Don't judge them; not all people behave the same way. This practical activity exists to convince the remaining team members who may have been left behind.

My recommendation is that the latter practice should be face-to-face. Remote work has many advantages, but interpersonal relationships don't necessarily benefit from it. You'll see much more participation.

Conclusion

Here's what we know:

100% perfect teams can't be efficient. Aim for 90% or 95%.
Involve the team in the change from the beginning.
Changing a team is challenging, especially if it challenges the ideals of some individuals.
Learn to listen, explain, and respect other opinions.
Change the team's mindset for fruitful and lasting changes.
Team leaders are your best allies.
Practical examples will help you persuade team members to embrace the change.

I'd love to hear your thoughts on this! What do you think? Feel free to drop a comment below and share your perspective with me! 💬

🧪💨 Test x10 faster in JavaScript with Object Mothers

Juan Otálora — Fri, 04 Aug 2023 14:53:35 +0000

Object Mothers in JavaScript are overpowered, and today I'm going to explain why you should start using them in your projects, both on the front-end and back-end. (Because yes, you also need to write tests on the front-end).

Martin Fowler might not have been the first to talk about Object Mothers, but he certainly popularized them. The idea is simple: to have functions capable of returning objects for use in our tests, although they could also be used for mocks or in any file where we need fake data.

Why are Object Mothers OP in JavaScript?

Alright, let's get to the point. Why are front-end Object Mothers so cool? For several reasons:

They are easy to create.
They are easy to maintain.
They are easy to extend.
They are easy to customize.

Do you need more reasons to start using them? You should stop creating objects directly in your tests and use object mothers to improve readability (and most importantly) the speed at which you write tests. Because, let's be honest, tests are a hassle. No one enjoys writing them (even less to maintain them), but they are necessary in our code.

Let's look at an example of what we don't want to do:

describe("when A", () => {
    it("then B", () => {
        const name = "Book"
        const product = {
            name,
            price: 12.99,
            reference: "123456",
            availableToPurchase: true
        }

        const result = getNameProduct(product)

        expect(result).toBe(name)
    })
    it("then B.2", () => {
        const price = 12.99
        const product = {
            name: "Book",
            price,
            reference: "123456",
            availableToPurchase: true
        }

        const result = getProductPrice(product)

        expect(result).toBe(price)
    })
    // Please, kill me...
})

And now an example of what we should do. First, we create a mother for Product:

export const aProduct = (partial: Partial<Product>): Product => {
    return {
        name: "Book",
        price: 12.99,
        reference: "123456",
        availableToPurchase: true,
        ...partial
    }
}

And now we make the tests much faster, readable, and scalable.

describe("when A", () => {
    it("then B", () => {
        const name = "Book"
        const product = aProduct({name})

        const result = getNameProduct(product)

        expect(result).toBe(name)
    })
    it("then B.2", () => {
        const price = 12.99
        const product = aProduct({price})

        const result = getProductPrice(product)

        expect(result).toBe(price)
    })
    // I want to do more tests 🙂. Ok no, but you know
})

Object Mothers and Faker.JS

If you want to take it to the next level, I recommend using Faker.JS, a library that generates random data for your tests. Yes, there might be times when your tests pass and times when they don't because of this, but if you run your tests always with the same data, we can agree that they aren't very realistic.

Here's an example of an object mother using Faker.JS:

export const aProduct = (partial: Partial<Product>): Product => {
    return {
        name: faker.commerce.productName(),
        price: faker.commerce.price(),
        reference: String(faker.number.int({ min: 1000000000, max: 1999999999 })),
        availableToPurchase: faker.datatype.boolean(),
        ...partial
    }
}

Now your tests won't just be easier to write and maintain, they'll be running within a chaotic dataset that can help us detect issues in our code. Because that's what tests are for, to catch errors, not just to increase project coverage.

Mastering Dependency Injection in React

Juan Otálora — Tue, 01 Aug 2023 18:26:37 +0000

In the first article of this series, we learned the principles of hexagonal architecture. In the second article, I showed an example of a folder structure for a React project with Redux. In the previous one, we discussed how to dispatch Redux actions from the repository implementation.

In this article, we will see how to easily and simply perform dependency inversion in React, allowing us to decouple the infrastructure from all the functional logic of our application.

Don't import infrastructure from the use case, inject it

Dependency inversion is one of the 5 SOLI(D) principles designed to guide software design towards more robust, flexible, and maintainable structures. In the case we will see today, we will use it alongside the repository pattern, decoupling the use case from the repository implementation through an interface. This way, any change in the backend connection or state management will be completely transparent to our use case.

Creating our first repository interface

As I mentioned before, we are going to implement the repository pattern, which involves creating an interface with the methods we need to communicate with the infrastructure and then implementing that interface, which we will later inject into our use cases. The theory may seem overwhelming, but with some practical examples, everything becomes clearer:

export interface TasksRepository {
    getAll: () => Promise<Array<Task>>;
    findById: (id: string) => Promise<Task>;
    save: (task: Task) => Promise<Task>;
    delete: (task: Task) => void;
}

This approach also solves one of the main problems when performing integration tests on the front end, as we can mock the repository implementation and perform tests that simulate real user flows without the need for end-to-end tests with the server. However, we'll talk about that in the last episode.

Implementing a repository

Having this interface already created, we can implement repositories using the above interface as a guide. The following example shows the implementation of a REST repository. We could implement it using Local Storage if we don't have the backend ready yet or mock the results as we'll see in the testing episode:

export const tasksRestRepository: TasksRepository = {
  getAll: () => {
    return fetch("https://api.com/tasks")
      .then(res => res.json())
      .then(tasks => tasks.map(mapTaskFromRest))
  },
  findById: (id: string) => {
    return fetch(`https://api.com/tasks/${id}`)
      .then(res => res.json())
      .then(mapTaskFromRest)
  },
  // ...
}

Use currying and no more DRY in hexagonal

From now on, use cases won't directly invoke repositories, but instead, they will receive them as parameters. This is what is known as dependency inversion.

How could the definition of a use case look now? Like this:

export const findTaskByIdUseCase = (repository: TasksRepository, id: string): Promise<Task> => {
  // ...
}

The above use case has a problem. We need to pass the repository as a parameter every time we invoke it. This is tedious, clutters the code, and also doesn't facilitate testing, as we will see. That's why my favorite alternative is to use currying:

export const findTaskByIdUseCase = (repository: TasksRepository) => (id: string): Promise<Task> => {
  // ...
}

const findTaskByIdWithRepositoryResolved = findTaskByIdUseCase(tasksRestRepository);

const task = await findTaskByIdWithRepositoryResolved("1");
const anotherTask = await findTaskByIdWithRepositoryResolved("2");

Using contexts to resolve dependency inversion

Now, another problem arises: how do we resolve this dependency in a React application? We will use React contexts, but in such a way that everything remains fully typed:

interface ContextValue {
  findTaskById: ReturnType<typeof findTaskByIdUseCase>;
}

const ApplicationContext = createContext<ContextValue>({} as ContextValue);

export const useApplication = (): ContextValue => {
  return React.useContext(ApplicationContext);
};

interface Props {
  children: React.ReactNode;
  dependencies: {
    tasksRepository: TasksRepository;
  };
}

export const ApplicationProvider = ({ children, dependencies }: Props) => {
  const { tasksRepository } = dependencies;
  return (
    <ApplicationContext.Provider
      value={{
        findTaskById: findTaskByIdUseCase(tasksRepository),
      }}
    >
      {children}
    </ApplicationContext.Provider>
  );
};

We wrap our application with this context so that all components can access it.

const createDependencies = () => ({
    tasksRepository: tasksRestRepository,
})

export default function App() {
  return (
    <ApplicationProvider dependencies={createDependencies()}>
        <Routes />
    </ApplicationProvider>
  );
}

Now we can go to any page/component and use this context to invoke a use case without worrying about the injected repository dependency:

export const TaskCard = ({id}) => {
    const {findTaskById} = useApplication();

    const [task, setTask] = useState();

    useEffect(() => {
        findByTask(id).then(setTask)
    }, [id, findByTask, setTask])

    if (!task) return null;

    return (
        <div>
            <h2>{task.title}</h2>
        </div>
    )
}

And that concludes this article on dependency inversion with React using contexts. I recommend you check out the rest of the posts in the "Clean Frontend Architecture" series to learn more about applying best practices to your code!

Everything you need to know about microfrontends in 5 minutes

Juan Otálora — Sat, 01 Jul 2023 10:40:00 +0000

Microfrontends (MFE) are an architectural approach that allows large web applications to scale quickly and efficiently while minimizing code duplication. Similar to backend microservices, MFEs divide applications into independent projects without sacrificing cohesion. This enables agile development by multiple teams without the need to duplicate common code.

Microfrontends vs Component Libraries

One common question teams often ask is whether they need a microfrontend or a component library. While the line between them may not always be well-defined, let's explore how an application built with a web component framework like React behaves with each approach:

Component library:

Injected into the application at build time, resulting in the library's code being included in the final application bundle.
Requiring a new release of both the library and the clients to update.
Primarily focused on reusing visual components or utilities, often lacking business logic hosting.

Microfrontends:

Injected at runtime, with no dependency added during development. Only the URL where the bundle can be downloaded is provided. When invoked, the application downloads and injects the MFE.
Clients can be updated simply by releasing the MFE in the project. Since it is injected at runtime, there is no need to rebuild the clients.
MFEs act as standalone applications, enabling REST calls, execution of business logic, and display capabilities.

Considerations for Adoption 🐥

Typically, the backend holds most of the business logic for an application, while the frontend serves as a simplified representation. If the frontend's representation layer remains stable even as the backend scales, adopting a microfrontend architecture may not be advisable.

For new projects aimed at testing viability, it is not recommended to immediately adopt a microfrontend architecture. The time required to set up a productive environment should be used to assess the project's feasibility.

In summary, only use microfrontends when your code necessitates it. Listen to your code, diagnose it, and split the monolith only if necessary! 🤟

Splitting the Monolith 🔪

The process of splitting backend monoliths aligns closely with the work involved in adopting microfrontends. The goal is to identify application domains and determine if they contain enough entities to exist as separate projects.

🧪 For our e-commerce example, we could divide the project into teams responsible for product management, cart functionality, and sales. Each team represents an essential part of the business and is logical enough to be treated as an independent project.

In the backend, communication between the swarm of microservices is crucial, employing mechanisms such as events, REST, or gRPC. Similarly, in the frontend, we not only require communication between components (which we'll address in a future post), but also cohesive rendering of the application for the user. This is where the shell comes into play.

Shell: Split and Reassemble 🍱

The shell serves as the orchestrator of microfrontends, an independent project responsible for determining what to render based on various data, such as the router path or browser events.

Ideally, the shell should contain minimal business logic. It can handle user authentication, log publication in the ingest service, and manage common variables like the user's country. However, keep in mind that adding too much to the shell compromises independence.

🧪 In our e-commerce example, the shell would include the application's header with the company logo and various links leading to different sections, such as the user profile or home page. Additionally, the shell should be aware that any paths starting with /product should load the product microfrontend, paths starting with /cart should load the cart microfrontend, and paths starting with /checkout should load the sales microfrontend.

One Project, Multiple Microfrontends 🦄

It's important to note that when we talk about a project, we're not necessarily referring to a single microfrontend. A project can expose multiple microfrontends that can be consumed by the shell or other microfrontends. As previously mentioned, microfrontends act as web components, but they are injected at runtime, providing endless possibilities.

🧪 The cart team, for example, exposes two microfrontends. The first one is the cart page, which displays information about products, units, prices, and the final cost. This microfrontend is loaded in the shell when the user accesses the /cart path, as we discussed earlier. The team also exposes a cart icon microfrontend, which appears in the header of the website at all times.

This article serves as an introduction to the concept of microfrontends, and subsequent articles will delve into more advanced topics, such as microfrontend communication, shared state management, and more!

Stay tuned for the next articles in this series as we explore the exciting world of microfrontends.

How to implement Redux in a clean architecture

Juan Otálora — Fri, 02 Jun 2023 18:08:23 +0000

A note before start. State management in React is one of the most complex topics I have work so far. Different functionalities require different state management systems. Once this series is finished, we will have a more serious discussion about state management. 🙂

In previous articles, we have talked about what clean architecture is and how to organize the folder structure of a project using hexagonal architecture. Today, we are going to dive a little deeper into the implementation of Redux, one of the most recognized state management libraries in React. Despite facing increasing competition, Redux remains a good option for handling complex state management.

I won't go into detail about whether Redux is a good choice or not. My opinion remains positive when it is implemented in applications that require complex state management. For other cases, alternatives like React Query or SWR tend to be a better option. But as with everything in life, it depends. In future articles, and if this series receives a lot of support (❤️), we can try to implement a clean architecture using one of these alternatives.

What modifies the Redux state?

Once we have set up Redux and have all the components reading from the store, in my opinion, the most important decision remains: What modifies the store? What dispatch de action?

In my opinion, considering the architecture I'm presenting in this series of articles, Redux should behave like a database. In other words, its operation should not be tightly coupled with the functional logic of the application. For this reason, in my view, each reducer should have only two operations: "save" and "delete" (where "save" means saving to the store or updating if it already exists). This way, we transform our store into a collection of objects that can be added or removed based on our needs.

All the examples of Redux implementation code were developed using Redux Toolkit.



export const tasksSlice = createSlice({
  name: "tasks",
  initialState: [] as Array<Task>,
  reducers: {
    addTasksToStore: (state, action: PayloadAction<Array<Task>>) => {
      pushIntoReduxStateOrUpdateIt(state, action.payload);
    },
    deleteTasksFromStore: (state, action: PayloadAction<Array<Task["id"]>>) => {
      const taskIds: Array<Task["id"]> = action.payload;
      return state.filter((prevTask) => !taskIds.includes(prevTask.id));
    },
  },
});

// Implementation of pushIntoReduxStateOrUpdateIt
// If the object exists, update it, if not, push it in the state

interface ObjectWithId {
  id: string;
  [key: string]: unknown;
}

export const pushIntoReduxStateOrUpdateIt = (
  state: WritableDraft<ObjectWithId>[],
  elements: Array<ObjectWithId>
) => {
  for (const element of elements) {
    const index = state.findIndex((prevElement) => prevElement.id === element.id);
    if (index === -1) {
      state.push(element);
    } else {
      state[index] = element;
    }
  }
};

In the traditional method of using Redux, each action corresponded to a use case, tightly coupling our application to the state management library and making it very difficult to switch to another one when the project's needs change.

Once we have set up our reducers, we need to revisit the million-dollar question: What modifies the Redux state? In this case, I think that the repository implementation should modify it, meaning we need to abstract the use case from the existence of Redux. This offers several advantages:

If in the future we want to change Redux to another state management library or eliminate it altogether, it will be relatively straightforward as we would only need to modify the repository implementations.
It is less error-prone by having all state mutation logic in the repository, abstracting this concept from the use cases and the domain.

Redux as an infrastructure component

Now that we have decided to move the dispatch invocation to the infrastructure layer, let's see an example of a repository implementation:

For instance, the implementation of a "get" or "find" retrieves the information from the REST API and stores it in Redux so that all connected components can consume it. Additionally, to allow more flexibility, we also return the data in case we want to use it in the use case or in the component.



  export const getAll = async (): Promise<Array<Task>> => {
    const taskDtos = await tasksApiRestClient.getAll();
    const tasks = taskDtos.map(mapTaskFromApiRest);

    store.dispatch(addTasksToStore(tasks));
    return tasks;
  }

For "create" or "update," the process is quite similar. In this case, we make the API call, and if the promise resolves successfully, we update the state by invoking the dispatch. Using this approach, you can implement optimistic updates easily.



  export const save = async (task: Task): Promise<void> => {
    // Another option could be update the store before invoke the API (optimistic update)
    store.dispatch(addTasksToStore([task]));

    const taskDto = mapTaskToApiRest(task);
    await tasksApiRestClient.save([taskDto]);
  }

Lastly, in the case of "delete," it is quite similar to the previous examples, with the difference that once the call is resolved, we need to remove the data from the store instead of updating or creating it.



  export const delete = async (taskIds: Array<Task["id"]>): Promise<void> => {
    store.dispatch(deleteTasksFromStore(taskIds));

    await Promise.all(taskIds.map(tasksApiRestClient.deleteById));
  },

This way, as you can see, we are updating the state at the same time we make the request to the server, preventing the front-end or back-end from becoming out of sync at any point. Furthermore, by decoupling Redux actions from functional logic and moving this logic to use cases, changing the state management library is as simple as changing the repository implementation.

In the next article (I'll try not to take as long as this time 🙄), we will talk about dependency injection with React contexts, creating a wrapper that we could take to any application developed with another framework or JS library, and our application would continue to function.

📂✨ Folder structure in a React hexagonal architecture

Juan Otálora — Thu, 04 May 2023 19:32:10 +0000

Certainly, the folder structure is one of those decisions that if not made well from the beginning can lead to many problems as the code scales: the folder structure.

Bad folder skeletons exist, just as good ones do. Fortunately, modern IDE refactoring tools allow files and folders to be moved without many complications.

In this post, we will look at the folder structure that I propose for a clean architecture for React with Redux and TS, so you will see naming specific to these technologies, but it can be applied to any other front-end library/framework. Feel free to adapt it to your needs 🙂

React Folders

Although in the previous article we discussed why React components (and their styles and hooks) are part of the infrastructure, it is also important to consider that they are a very important part of the application. Ultimately, SPAs may have business logic, but without a user interface, it is nothing. That's why in the structure I propose, *the basic React folders are located at the root of the project *(/src), as in most front-end projects.

Here we will find some folders such as /components, /pages, /router, /hooks, /styles, ... In an upcoming article in the series, I will explain how to structure these folders with a tweaked Atomic Design, so I won't give it too much importance in this post.

Vertical Slicing

Let's set aside the onion-like UI that represents hexagonal architecture for a moment. The first thing that comes to mind when we have to divide our code is to divide it into layers: one folder for the domain, another for the application, and one last for infrastructure. If these folders start to grow, we can divide each one into folders for different functionalities: one for "tasks", another for "goals", another for "users", ...

But let's put ourselves in the shoes of someone who has to develop a new feature for a moment: for example, deleting tasks. Does it make sense to be moving through the different /tasks folders in domain, infrastructure, and application?

Vertical slicing tells us that it's better to make the first division by functionality and then by layers. That is, at the first level, have folders for /tasks, /goals, /users, ... And within each of these three folders, have /domain, /application and /infrastructure.

Now, let's go into more detail on each of these three folders located into a /modules or /features folder.

If you found this helpful or enjoyable, add a reaction! ❤️ Your likes are appreciated and keep me motivated!

Domain ⚙️

/modules/<slice>/domain

Mainly in this folder, we will have 3 things:

Domain types and enumerations
Repository interfaces
Domain utilities

Let's start with the types. It's important to define all the types that represent entities of our business: "Task", "Goal" and "User". Also, enums that represent states such as "TaskStatus" or "GoalType". These will be used from different points of the application, so let's try to put effort into creating them.

In the same files as the types, we will place the creator functions, responsible for creating an object of that type based on parameters. It's interesting to bring the concept of named constructors to functional programming.



// Declare the type
export type Task = {
  id: string;
  title: string;
  status: TaskStatus;
  goalId?: Goal["id"];
};

/* Declare the constructors.
In this case, we receive by parameters
all the task props and in the constructor
we only ensure the task is valid */
export const createTask = (task: Task): Task => {
  ensureTaskIsValid(task);
  return task;
};

Along with the types, the repository interfaces such as "TaskRepository" or "GoalRepository" will serve us to implement the repositories in the infrastructure.



export interface GoalsRepository {
  getAll: () => Promise<Array<Goal>>;
  save: (goal: Goal) => Promise<void>;
  delete: (goalId: Goal["id"]) => Promise<void>;
}

Finally, a utility functions folder where we will place all domain services, guards, or that logic specific to our domain. I place them all under a folder called utils.



export const calcPercentageOfDoneByTasks = (tasks: Array<Task>): number => {
  const doneTasks = tasks.filter((task) => task.status === TaskStatus.DONE);
  if (doneTasks.length === 0 || tasks.length === 0) return 0;
  return doneTasks.length / tasks.length;
};

There are many things in DDD that I won't go into detail about, such as favouring composition over inheritance or value objects. If you're interested, we can do an article later on looking at best practices we can apply with DDD in front-end projects.

Let's allow our business to express itself freely in this folder. All the logic that we can push to the domain (if it belongs to the domain, of course) is better. You will surely find a lot of validations in your components that you have developed in the same component but should be in a domain utility. Can you create a task with an empty string as the title? This smells like business, let's try to push it there.

Application 🚀

/modules/<slice>/application

We move to the next layer, the application layer. Here, all the use cases that the user can execute are located. These use cases are usually related to actions that the user can perform in the interface such as "Create a task", "Delete a goal", or "Assign a task to a user". The premise of use cases is that it doesn't matter how you design the interface, the use case should be invariant.

You have to be careful because sometimes very general use cases are created such as "Save task" or "Save goal". If your use case is "Assign a task to a user", don't assign the task to the user on the front-end and send the modified task to the use case. It's better if you pass the task and the user to whom it is assigned to the use case and decouple all this functional logic from the interface.



export const getTaskNoteOrCreateOneUseCase = async (
  notesRepository: NotesRepository,
  taskId: Task["id"]
): Promise<Note> => {
  const note = await notesRepository.getByTaskId(taskId);
  return note ?? createNoteByTaskId(taskId);
};

Some use cases will need to access repositories (whose implementation we will talk about later). In this case, it may make sense to call the repository implementation directly from the use case, but we would be dirtying it (application cannot import infrastructure). Instead, we will receive the repository implementation as a parameter and for that, we will use the interface that we will have generated in the domain.

We will talk about dependency injection in a couple of chapters, but for now, we stay with this and with the fact that we can use currying to make our code more readable.

Infrastructure 🔌

/modules/<slice>/infrastructure

Finally, in this folder, we find all the logic of connection with the backend or implementations such as Local Storage and even the Redux dispatch that we will talk about in more detail in the next chapter.

I like to implement the repository as a typed object with the domain interface. This way, if we want to use it, we just have to do repositoryName.getAll(), being much more semantic than having to call a function getAll() or getAllFromRepositoryName().



/* Yes. I modified the store in the
implementation of the repository. 
We'll talk about this in future articles */
export const goalsRepository: GoalsRepository = {
  getAll: async (): Promise<Array<Goal>> => {
    const dtos = await getAllGoalsApiRest();
    const goals = dtos.map(mapGoalFromApiRest);

    store.dispatch(saveGoalsAction(goals));
    return goals;
  },
  save: async (goal: Goal): Promise<void> => {
    store.dispatch(saveGoalsAction([goal]));

    const dto = mapGoalToApiRest(goal);
    return saveGoalApiRest(dto);
  },
  delete: async (goalId: Goal["id"]): Promise<void> => {
    store.dispatch(deleteGoalAction(goalId));

    return deleteGoalApiRest(goalId);
  },
};

Some people like to include the technologies they use in the repository name. For example, apiRestReduxRepository. In the backend, with many more connections to external services, it may make more sense, but in the front-end, I have found a few cases where I like to do it that way.

What else do we have in this layer besides the repository implementation?

Clients connect with external servers, for example, the REST client that executes the fetch and that we will call from the same repository.



export const deleteGoalApiRest = async (id: string): Promise<void> => {
  await apiRestClient(`${PATH}/${id}`, {
    method: "DELETE",
  });
};

DTOs define the types used in calls to external services to comply with the contract. These DTOs don't have to be the same as our domain types. They can contain some differences, and it's important to keep them separate. For example, GraphQL contaminates objects with a __typename property that we're not interested in the domain.



export type TaskApiRestDTO = {
  id: string;
  title: string;
  goalId?: string;
  status: string;
};

Mappers transform DTOs into domain entities and vice versa. I call them from the repository just before making the client call.



export const mapTaskToApiRest = (entity: Task): TaskApiRestDTO => {
  return {
    id: entity.id,
    title: entity.title,
    status: mapTaskStatusToApiRest(entity.status),
    goalId: entity.goalId,
  };
};

export const mapTaskFromApiRest = (dto: TaskApiRestDTO): Task => {
  return {
    id: dto.id,
    title: dto.title,
    status: mapTaskStatusFromApiRest(dto.status),
    goalId: dto.goalId,
  };
};

Assemblers, although not very common in the front-end, help us compose domain objects based on several DTOs. In mature applications with Backend For Frontend, it is usually not necessary, but in an MVP they can save us a lot of development time.

Conclusion

Vertical slicing allows us to be more agile when developing new functionality. By dividing everything by layers and following the hexagonal architecture, we achieve code with functional logic that is decoupled from the interface and infrastructure, which saves us time when refactoring, scales much better, and is much more readable.

There are some things I haven't explained in depth because I will delve into them in more detail in future articles. In the next one, we will see how to manage Redux, how to read from its store, and where to execute dispatch.

I'd love to hear your thoughts on this! What do you think? Feel free to drop a comment below and share your perspective with me! 💬

A clean frontend architecture for React and Redux

Juan Otálora — Mon, 01 May 2023 15:46:21 +0000

Since I started working on frontend projects, I've been looking for clean architectures that align with some of my basic development principles: maintainable, scalable, and readable code. After a long search, I've come to the conclusion that the architecture depends on the project, not the technologies we use. Therefore, although we're applying this model to React and Redux, it can be used with many other web frameworks or libraries.

The ultimate goal is to have a general picture of how to model our frontend projects with React and your preferred state manager. We'll cover folder structure, hexagonal architecture, component management, CSS architecture, and of course, testing.

A Brief History of Frontend Development

The development of clean architectures in the frontend has been organic. We come from a time when all business logic was in the backend. The web was nothing more than static pages rendered by a server with little business logic. Then we moved on to jQuery, which gave us a bit more autonomy, such as validations or UI logic, until we reached the current technologies: SPAs, which allow us to build real applications executed in the user's browser.

From the first to the last, only a few years have passed, and with such rapid growth, few companies have stopped to consider whether it really makes sense to start standardizing the code written in the front-end. After all, we're just rendering things on the DOM, right?

Why clean architectures?

Clean architectures have a purpose beyond (usually) increasing the number of files in our project: decoupling the business logic from the rest of the application elements. In this case, decoupling it from both the backend connections and the interface. Let's imagine the case of a Trello-style application. It's independent of how the component to create a task is displayed, the logic that will be executed when clicking the "Save" button will be the same. Now imagine if all the save logic is on that component. It would be hard to find, and refactoring that component would be like disarming a bomb.

Now imagine that when clicking on the save button, a use case is invoked with the parameters that the user has introduce. This use case performs the validations and creates a new object with all the data, which it sends to the repository responsible for persisting it. The repository, decoupled from the rest of the logic, is currently saving the information in local storage because we want to create an MVP to see if the project is reliable, but in the future we'll want to connect it to an API. This repository also updates the state in Redux so that the change is reflected in the UI.

In this brief case, we have used several patterns and best practices such as the repository pattern or the hexagonal architecture. We will delve into each of these topics in more detail in the upcoming chapters of the series. But let's take a closer look at what hexagonal architecture is all about.

The hexagonal architecture (or ports and adapters architecture) is a model designed to decouple the domain logic, application logic, and infrastructure.

As many of you may already know how this works, I will be as brief as possible. However, if you are interested in a more detailed article, I can write one that focuses more on the frontend

This architecture should be viewed as an onion with three layers (from the outside in): infrastructure, application, and domain. Where infrastructure knows about application and domain, application knows about domain, and domain only knows about itself.

Where does React fit in the hexagonal architecture?

We come to the million-dollar question: Where does React fit in the hexagonal architecture? To answer this complicated question, we have a simple answer: in the infrastructure layer. As explained in its documentation, React is a library for building user interfaces, nothing more. Therefore, we will fit it there, just like other libraries or frameworks such as Vue or Svelte. So the previous case is structured as follows:

React, JSX components, hooks, interface logic, styles, and Redux are all located in the infrastructure layer. The repository implementation and Local Storage client (which will be replaced with a REST client in the future) are also located here.
Use cases such as creating a new task, assigning it to a user, adding a note, or deleting a task are located in the application layer.
Finally, in the domain layer, we have domain element types, repository interfaces, and domain logic in general.

Sounds better, doesn't it? Now we have everything in its place. It's easier to find, but for that, we need to have a good folder structure, which is what we'll cover in the next chapter of the series.