DEV Community: Samuel Monteiro

Monorepos and Nx

Samuel Monteiro — Wed, 01 Sep 2021 20:22:36 +0000

What's a Monorepo?

A monorepo is a single repository that can have one or more projects inside of it. You can have frontend, backend and helper tools, all in the same monorepo.

You could have a customer and a backoffice applications, both living in separate folders consuming an API living in another folder and a set of interfaces that would be shared by your applications and APIs.

If you had a multi-repo, one repository would contain the customer application, another one, the backoffice, another one would have the API and another for the interfaces. Maybe all of your applications would consume the API and the interfaces through a package published on the npm or some other package manager.

Why should you use it?

If you're working in a company or a team, most certainly they will have best practices and code standards defined and if they don't, they will have them sooner or later.

Also as the company grows in people and in complexity you will have separate teams working to achieve the same or correlate goals. You could have a frontend and a backend team, both working to achieve the same goal in different repositories and this could lead to some problems in the future, like duplicated types, slow development and deliver time and so on.

A monorepo addresses some of those issues by having everything in the same repository. Some of the benefits are:

Maintain your company best practices in one place and apply them without much effort
Every best practice that you have, would be adopted by every project automatically with the help of tools like eslint and prettier
It's easier to share code between your projects
The shared code it's easier to maintain
Changes that you make could be reflected on every project in the same time that that they're made

Drawback of a Monorepo

Even though it's has a lot of benefits, like all things in life, it comes with some drawbacks

Every change to your shared code will reflect on every application that you have. So, you need to make sure that everything is still working as expected in every affected application
Performance issues with your VCS (version system control) as your monorepo grows in size.
It's hard for your team/company to give specific access permissions to specific teams, since everything is in the same repository.
Applying some specific rules to your monorepo could be a problem. Like getting some specific parts of it and make it open-source. That's not easy to accomplish and probably you would need some specific tools to help you with that.

Nx, a tool to help you manage your `monorepo`

And then comes Nx. A tool that aims to facilitate the process of managing a monorepo by providing a set of helpers and commands that the developers and the maintainers could use to organize and develop faster within a monorepo.

It's main structure consists of two folders:

/Apps

It's a place to store all of your applications and their e2e tests. For example, you could have a website for your customer and one for your backoffice, and they both could consume some components created on the libs folder.

/Libs

It's where you'd store every code that you want to share between your applications created on the apps folder. For example, you could have a components library inside that folder and use the components created there inside your applications without a lot of effort. You could also have an API that would be used by your apps for example.

Code example

Imagine that you have the following button inside /libs/button

export const Button = ({ onClick, children }) => {
    return <button onClick={onClick}>{children}</button>
}

And then, you want to use that button inside your application that it's located in /apps/customer. It's easy as that

import { Button } from '<your-monorepo-name>/button';

export const CustomPage = () => {
    function handleClick() {}

    return (
        <div>
            This could be a form
            <Button onClick={handleClick}>Submit</Button>
        </div>
    )
}

Why Nx?

Nx helpers

Nx comes with pre-built generators that aims to facilitate the process of creating Applications and Libraries with React, Angular and many other frameworks. These generators can be used by with the help of commands that you run on your terminal and it will generate and add code inside your folders and update any other files that may be necessary.

And you can also create your own generators to suit your team and company needs.

Other things

It has a very good VsCode extension that make it easier to manage the monorepo
IT has a dependency graph that helps knowing which part of your application should be builded again and tested when somethings changes
It has a single package.json file in the root of the monorepo which aims to make all of your code use the same dependency versions
It caches all of your commands, like build and test ones. So, the first time that you run some command, it could take a while, but after that, it will be blazingly fast because of the cache that was made.

Conclusion

The choice between going with a multi-repo or monorepo is a difficult one, both of them come with their own set of benefits and drawbacks. One thing that I can say to you is to balance them out with your team and organization to choose the right tool for the job.

Feel free to send me a tweet and follow me on twitter 🤙

How to think your application with Relay

Samuel Monteiro — Tue, 22 Jun 2021 23:16:28 +0000

Introduction

First impression

I didn't have a good first impression about Relay when I've started using it. I found it difficult to understand, verbose to use, and I didn't saw the benefits from it.

Even though I didn't like it, I was part of a team, and as a team we choose to stick with Relay and see in the long term if it was a good choice or not.

As the time goes by, I've started to get along with it and to understand how to use it. I still didn't have the full idea, but just to realize how I could use it to solve simple problems like data fetching, and to know what I was doing was enough for me at the time.

Responsibilities

Months later, I was promoted to tech lead and with that came the responsibility to understand and to explain to my team why we're using the stuff that we're using. I had a challenge. I needed to understand why we use Relay and not something else.

And I believe that like any other solution, if you don't know how and why you use it, you're going to face the same or even worse problems that you're trying to solve with it.

This article

This article is a grasp of that process of understanding why we use Relay. I'm going to show you how to think your application using Relay, because I believe that to understand other solutions that Relay provides you need to understand first what problems we have right now.

What's Relay?

It's a JavaScript framework that tries to facilitate the process of fetching data on front-end using GraphQL. It's developed by Facebook and was conceived with the same ideia of React componentization.

React components and Relay

The ideia behind components in React it's to decrease the complexity of your app by dividing it into smaller parts called components. These components are easier to understand and to maintain, and that increases the capability of your app to scale.

And how does that relates to Relay?

The ideia behind Relay is that you have your data dependencies collocated with your component and that it's beneficial for some reasons:

It's easier to understand which data is needed for your component to work.
If your component needs any other data from your server, you don't need to change your entire query structure, just your component. (Not every case works this way, but most of them)
It's easier to test your component isolated from your entire structure.

How to use Relay?

To understand it, let's take that YouTube page below:

We can divide it in four components that receive the data from the servers.

VideoPlayer: used to render the video that we're watching. Probably need the videoSrc from the server.
VideoDetails: show the video details like title, description, author, number of likes and dislikes.
RelatedVideos: it's a list of videos that the YouTube algorithm believes that you would like to see.
UserImg: renders the logged user profile image.

Just remembering that all of that it's just an example. For sure the real YouTube architecture it's much more complex than this.

With these components in mind, we have two approaches to get the data from the server using Relay.

1. Each component fetches the data that it needs

We can draw a diagram like this to represent that solution:

On the left side, we have a simplified version of the YouTube page. Where each component is represented by a gray circle and they call the server through a GraphQL query, like this one:

graphql`
  query NavbarQuery {
    user {
      profileImg {
        src
      }
    }
  }
`

Benefits

With this solution, we could show different loading indicators in each part of our application. Something like this:

By doing that we improve the user experience by not blocking entirely his access to the screen and show which data we're fetching and what we already fetched.

Here's an article explaining why you should use loading skeletons in your interface.

Downsides

The first problem is related with the tree architecture where a component depends on another one to render. As an example, let's get just the structure responsible for showing us the video:

Here, we're only going to get the data with the videoSrc when the component VideoPlayer is fully rendered. And if for some reason any of these components above the VideoPlayer take a long time to load, we would need to wait that time until we can call the server and start loading the video.

With that we would have two times to load the video:

rendering the components above the VideoPlayer.
recieving the response from the server with the videoSrc data.

Another problem is that we would end up with a lot of requests to the server, where each one of them will ask just for a single part of the data. And it makes sense that once the connection is open with the server, we ask for all the data that we need.

Ok, so we have these two problems. What it's the alternative?

2. The recommended solution

Instead of fetching the data on each component, we fetch them once on the page load, in other words, every page is a query.

But didn't you said that Relay is built on colocating the data dependencies with the components that need them?

Yes, I did. When I said data dependencies I didn't mean the fetch function, I mean the declaration of the data that it's needed. We only fetch once, at the page render. It would look like this

Benefits

With that, we ask for all the data that we need to render the page on the page load. This comes with the following benefits:

We decrease the amount of request made to the server.
Since we're not waiting for some component to load, we decrease the load time to show relevant data to the user.

Colocating the data dependencies with Fragments

In order to colocate the data dependencies of a component close to it, we can use Relay Fragments.

A Fragment, in Relay, it's a declaration of the data that a specific component need.

It's like what we had with every component making a fetch, but instead of a fetch, we're only declaring the data that we need, and the fetch only occurs once. The implementation would look like this:

// page component
graphql`
  query PageQuery {
    user {
      ...NavbarFragment_user
    }
  }
`

// navbar component
graphql`
  fragment NavbarFragment_user on UserType {
    profileImg {
      src
    }
  }
`

This way, the Navbar declares exactly what it needs and if something change, we will only change on the fragment, not on the page query.

Even though this is nice, we have a problem :(

Downsides

At the version 10 of Relay we can't have a loading indicator per component, we need to show a loading indicator on the entire page before showing some data to the user, something like this:

You have two ways to solve this problem.

You could use the first approach to solve this problem, where each component calls a fetch and while this fetch don't return a response, you show a loading indicator.

The other way and the one that I recommend, is to upgrade your Relay to version 11 and start to use the @defer directive from GraphQL alongside Suspense component from React.

With the @defer directive you could say that a specific piece of your query, like a fragment, should be loaded asynchronously and while the response of that piece doesn't return from the server, you show a loading indicator passed to your Suspense component.

Here's the Relay documentation where they explain in more details how to do that and in this video how they're using that on Facebook.

Conclusion

Just as React once was, Relay still a not much used library and because of that there's not much articles and tutorials explaining how it works.
I do hope that this article increased your understanding about how to use Relay on your application or how its main idea works.

If you missed a more technical explanation, or if you still have some questions that I didn't cover, feel free to send me a tweet or a DM 🤙

Como implementar Type guards no seu código

Samuel Monteiro — Thu, 20 May 2021 00:21:19 +0000

Imagine que você tem a seguinte situação:

Você tem uma aplicação que busca por músicas no Spotify e nessa aplicação você mostra o email do usuário logado e a música que ele está escutando naquele momento.

Você então cria 2 funções para acessar a API do Spotify

getUser para chamar a API que irá buscar os dados do usuário
getSong que irá retornar uma lista de músicas do Spotify

Então você teria o seguinte código:

type APIResponse<T> = {
  data: T;
  error: Error;
}

type User = {
  email: string;
}

type Song = { id: string; title: string };

const getUser = async (fetchUrl: string): APIResponse<User> => {
    const res = await fetch(fetchUrl);

    return res;
}

const getSong = async (fetchUrl: string): APIResponse<Song> => {
    const res = await fetch(fetchUrl);

    return res;
}

Depois de implementar as 2 funções, você percebe que elas são muito parecidas. As 2 recebem uma url que é passada para dentro do método fetch. Esse método faz a chamada para a API e depois retorna o resultado.

E aí, você pode pensar

poxa, já que elas são tão parecidas, acho que vou criar uma função que reduz a quantidade de código repetido

const fetchApi = async (fetchUrl: string): APIResponse<User | Song> => {
    const res = await fetch(fetchUrl);

  return res;
}

const userResppnse = await fetchApi('https://apiUser...');
const songResponse = await fetchApi('https://apiSong...');

Já parece que ficou melhor. Agora temos menos código duplicado e menor possibilidade de erro.

Mas você vai ter um problema de Typescript 😟

O tipo da variável userResponse está como APIResponse<User | Song> então se você tentar fazer isso:

const userResponse = await fetchApi('https://...');

console.log(userResponse.data.email);

Você vai tomar o seguinte erro:

Property 'email' does not exist on type 'User | Songs[]'.
  Property 'email' does not exist on type 'Songs[]'

O Typescript não consegue dizer se a propriedade data da variável userResponse é um User ou um Song e por isso ele previne que você chame a propriedade email que é exclusiva do User.

Isso garante que se por exemplo isso acontecer:

const userResponse = fetch('https://apiSong...');

Você não vai ter problemas mais pra frente.

Type guards

Os type guards são uma forma de dizer para o Typescript qual tipo nós esperamos.

Podemos criar um type guard de usuário que garante o tipo User da seguinte forma:

const isUser = (data: User | Song): data is User => (data as User).email !== undefined;

Estamos criando a função isUser que aceita o tipo data: User | Song e que retorna um data is User. A expressão is User diz que eu, como desenvolvedor, garanto que o retorno da minha função é do tipo User.

O que falta é a implementação dessa verificação. Já que o tipo Song não tem o campo email podemos verificar se a variável data possuí ele.

Se possuir, podemos dizer que data é do tipo User.

E com isso, podemos executar o seguinte código sem problemas de Typescript:

if(isUser(userResponse.data)) {
  console.log(userResponse.data.email)
};

Assim, o Typescript não vai mostrar um erro porque você disse que a função isUser retorna User e nada mais.

Não tem possibilidade da variável data ser do tipo Song por exemplo.

E para finalizar, o type guard do tipo Song seria assim:

const isSong = (data: User | Song): data is Song => (data as Song).title !== undefined;

if(isSong(songResponse.data)) {
  console.log(songResponse.data.title);
}

Através dos type guards você consegue ter maior controle sobre a tipagem do seu código. Tudo isso em tempo de runtime, o que é bem legal 🤘

Apesar de ser uma boa adição na sua base de código, o type guards é propenso a falhas já que quem define a função para validar o tipo é o próprio desenvolvedor.

Para resolver essas falhas e realmente trabalhar com um typchecking em runtime, sugiro dar uma lida nesse artigo do pessoal do Unsplash. O artigo destaca o porquê de type guards definidos pelo usuário não serem tão seguros e o que fazer nesses casos.

Galera, é isso por hoje. Fiz esse artigo porque acabei me deparando com algumas situações na minha aplicação que funcionariam melhor se tivesse um type guard implementado. E apesar de serem muito úteis, não vejo muita gente usando no dia a dia, então fica aqui minha contribuição. Espero que consigam aproveitar de alguma forma 😉

E se vocês sentiram falta de alguma explicação, ficaram com alguma dúvida ou só querem trocar uma ideia, podem me marcar ou mandar DM no twitter 🤙

Create git-graphs easily

Samuel Monteiro — Wed, 23 Sep 2020 19:04:26 +0000

Why?

Have you ever struggled while trying to explain how the git flow on your squad,team or company works to one of you coworkers?

I've already struggled with this situation and back in the time I've created a new folder, started a new git with git init and simulated all the flow.
The problem with this approach is that it doesn't have any visualization of the git graph that's been created. And we all know that in the beginning, git is hard and with experience and time, git continues being hard 🙃

How?

So with that in mind, I found a lib that creates git graphs in svg and they already had a port for React.
Then, I just created a website that facilitates the creation of the graph svg by manipulating the gitgraphjs api and here it is.

Here it is

https://git-graph-creator.netlify.app/

It's under development and there's some improvements that could be made in order to be more complete and make use of full gitgraphjs api. It's also an open source project and I'm open to any feedback that you may give 🤙

repo link

DEV Community: Samuel Monteiro

Monorepos and Nx

What's a Monorepo?

Why should you use it?

Drawback of a Monorepo

Nx, a tool to help you manage your monorepo

/Apps

/Libs

Code example

Why Nx?

Nx helpers

Other things

Conclusion

How to think your application with Relay

Introduction

First impression

Responsibilities

This article

What's Relay?

React components and Relay

How to use Relay?

1. Each component fetches the data that it needs

Benefits

Downsides

2. The recommended solution

Benefits

Colocating the data dependencies with Fragments

Downsides

Conclusion

Como implementar Type guards no seu código

Type guards

Create git-graphs easily

Why?

How?

Here it is

Nx, a tool to help you manage your `monorepo`