Forem: Felipe Sousa

Automating Front End Development with Anima

Felipe Sousa — Tue, 10 Dec 2024 20:43:35 +0000

Over the last decade, we’ve seen an increasing number of tools that assist us in creating software projects. These tools have become essential in our workflow, not only saving time but also helping us meet the market demand for speed in adapting to changes and delivering continuously.

In the frontend space in particular, concepts such as SPAs, web-components, modularization, and new ways of styling and building applications have made workflows more robust and full of opportunities. These advancements have significantly improved web applications and opened up endless possibilities for products.

The big challenge, however, is that frontend development is extensive. There are countless details to consider when creating a frontend application that interacts with clients at a basic level. Here are some key points:

Project setup: installing and carefully syncing all the tools we’ll be using.
Developing interfaces that reflect the designed layouts.
Applying responsiveness to ensure smooth navigation across various platforms.
Setting up APIs, backend endpoints, and creating services to connect with data.
Configuring page routes and user navigation flow.
Making calls to fetch data and rendering it within the pages.
Handling loading states, errors, etc.
Implementing custom functionalities like search, filters, and page navigation.
…
… and much more!

The list is long and keeps growing. For this reason, among the tools that claim to automate frontend development, very few offer true end-to-end integration—covering design, data integration, responsiveness, and deployment.

Luckily—and thanks to significant technological advancements—things seem to be changing. Today, we’ll explore a fascinating tool that promises to help us build and deliver frontend applications in record time while integrating tools we already use in our daily workflows.

Introducing Anima! 🎉

Anima App is a tool for frontend developers that assists in creating projects from design to deployment. The platform offers extensions that help streamline workflows, whether working within design tools like Figma and Adobe XD or directly in VSCode through Frontier, leveraging AI to support daily tasks.

Anima enables the creation of frontend applications from the initial setup, allowing you to choose programming languages like JavaScript/TypeScript and libraries such as React, Vue, or plain HTML. It also integrates seamlessly with interface libraries like Material UI, Antd, Shadcn, TailwindCSS, and more. Additionally, it supports on-demand code integration through Gen AI, helping with all the details of your application. Examples include fetching data, rendering UI elements, managing application states, creating custom functions, and more. All of this culminates in the export of clean, functional, and production-ready code.

Example Project

Let’s create a mini product entirely with Anima, named ‘Your Next Party’—a small application that cover the points mentioned earlier, including setup, frontend interface creation, server calls, data rendering, state management, and more. This will allow us to see how the tool assists in all these steps.

The complete application design is available at this link. It is a web page where users can find venues to visit. The page will display a list of venues with their respective details (name, location, rating, price per person, and music genre), allowing users to filter via a search field and navigate between music genres, simulating some of the small tasks we perform daily in a real project.

Design

The goal is to use Anima to transform our design version into a project, rather than directly creating all the steps of the interface. The application UI has very simple elements: a header containing the application title, an icon, and a search bar; a navigation section for quickly filtering the page data; and a list displaying the venue results.

1. Install and Login

To get started, you need to create a new account on Anima’s official website. For this example, we will use a Figma template from the community. Open the application and install the Anima plugin. Once the plugin is installed, run it, log in with your account, and you’re ready to begin.

2. Project Setup and Preferences

With our Figma template designed and the plugin installed, the next step is to configure the technologies we will use to create our application.

As mentioned, Anima offers extensive compatibility, allowing you to define the technologies for your final project. The configuration process is straightforward: open the Anima plugin, select the layer, and choose the desired settings for your project.

For our project, I will configure it to use React with TypeScript, Shadcn with Tailwind.

Where the magic happens 🪄

The process to convert the design into code is simple. Within Figma, with the Anima plugin open, simply select the area you want to export as code:

When exporting, you receive a .zip file of the project fully configured with the chosen technologies, staying as true as possible to your template. It reuses components from your application and implements them with the tools you selected. With just one click, you get your entire application set up, with the interface built and ready to deploy! 😮

Fetching Data and Custom actions

The second part involves integrating data and adding extra functionalities such as search, navigation, and listing data from a real API. To implement these features, we will use Anima’s Gen AI, which allows us to implement these functionalities via prompts.

Some considerations regarding the data implementation:

For the backend and APIs, I will use Supabase, which requires specific configuration within the project.
When page loads, the application should fetch data from a table called events via Supabase and render it in the venues list on the interface.
The user should be able to navigate between the categories listed at the top and update the venues displayed on the screen.
The user should be able to filter the results by name.

To achieve these functionalities, I will use the following prompts:

1. at ui page, create a supabase instance

2. use https://juwlfiepovrtgsuwcvmc.supabase.co as supabaseUrl, and <my-key> as public-anon-key.

3. when the page loads, get the data from supabase in a table called events, that will be the data that I want to show, the response is shaped as {id, genre, location, price, image}[]

4. at the search input, filter the events in base of their names (be aware to use the names as a lowercase to avoid non-match)

5. filter items in base of they genre when click at navbar items and when the category is selected, shows a border bottom to show users which one is selected.

To implement the prompts and update the initial codebase, you need to click the Add Prompt feature within Figma.

Once activated, you will see an interface where you can add your prompts. After that, click Done. Once the changes are applied, you can click to generate and Download your project with all the necessary updates.

Once generated and exported, we have the functional application source code that can be deployed to any hosting service. In this case, I will use Vercel. Here you can check out the Live Demo and see the final result!

Live Demo

The result is EXCELLENT and very positive! ✅ The customizations quickly applied data fetching, rendering, and all implementation details while creating a visual interface that meets expectations with clean, production-ready code.

Anima has tremendous potential to greatly aid in project development, even for more tasks such as Design Systems, and beyond. It’s definitely worth investing time to explore and make the most of what Anima has to offer!

Here are some important links:

Thank you for reading!

JS Async: async/await

Felipe Sousa — Tue, 08 Sep 2020 21:55:35 +0000

This post is the last of the JS Async series, 3 posts to explain and show how to work with asynchronous data in JavaScript.

You can check out the other 2 previous articles:

Today we’ll talk about async/await and see some examples of how and what we can do with it:

Async

The keyword async was implemented in ES2017. It makes it possible to create naturally asynchronous functions using the following notation:

async function myAsyncFunction() {}

Something important and even more interesting about this implementation is that every async function returns a Promise, meaning that we can use all the interfaces we already know in the article about promises. Let's look at an example to better understand:

async function myAsyncFunction() {
  return "Hello!";
}

myAsyncFunction().then(payload => {
  console.log(payload); // Hello!
});

The async functions use the success values as the values that will be arranged within the.then pipeline in the promise that will be returned, in case you need to export an error, it is necessary to trigger an error within the scope of execution to be sent to the .catch pipeline, let's see an example:

async function myAsyncFunctionWithError() {
  throw "something wrong happen";
}

myAsyncFunctionWithError().catch(error => {
  console.log(error); // something wrong happen
});

Await

The use of await is restricted only within a function declared with the keyword async, basically what it does is wait for the Promise response value or convert the value into a resolved Promise.

async function myAsyncFunction() {
  const payload = await { name: "felipe", age: 22 };
  console.log(payload); // { name: 'felipe', age: 22 }
}

myAsyncFunction();

In cases where we are not returning any value from our function, the execution call remains as normal function calls without using .then.

Catching errors with try/catch

Await always expects the success value of the promise, so we have no way to capture the error directly, to do this we have to make use of the try/catch which receives the reject value if it happens, within the promises that are being executed inside the try block:

async function myAsyncErrorFunction() {
  throw "ops, something wrong happen";
}

async function myAsyncFunction() {
  try {
    const response = await myAsyncErrorFunction();
  } catch (error) {
    console.log(error); // ops, something wrong happen
  }
}

myAsyncFunction();

Executing this block, the error happens inside the promise myAsyncErrorFunction and is captured inside the try/catch catch block.

In summary, the joint use of the implementations makes our code extremely simple and readable, making handling asynchronous (or synchronous) data more directly and effectively.

I hope you enjoyed this series, see you later!

🔭

JS Async: async/await - pt-br

Felipe Sousa — Mon, 31 Aug 2020 23:00:48 +0000

Esse post é o ultimo da série sobre JS Async, 3 posts para explicar e mostrar como trabalhar com dados assíncronos em JavaScript.

Versão original publicada na minha página pessoal.

Você pode conferir os outros 2 artigos anteriores:

Hoje falaremos sobre o async/await e veremos alguns exemplos de como e o que podemos fazer com ele:

Async

A keyword async foi implementada na versão ES2017. Ela possibilita criarmos funções naturalmente assíncronas utilizando a seguinte notação:

async function myAsyncFunction() {}

Algo importante e ainda mais interessante acerca dessa implementação é que toda async function retorna uma Promise, significando que podemos utilizar todas as interfaces que já conhecemos no artigo sobre promises. Vejamos um exemplo para entender melhor:

async function myAsyncFunction() {
  return "Hello!";
}

myAsyncFunction().then(payload => {
  console.log(payload); // Hello!
});

As funções async utilizam os valores de sucesso como os valores que vão ser dispostos dentro do pipeline .then na promise que vai ser retornada, em caso de necessitar exportar um erro, é necessário disparar um erro dentro do escopo de execução para ser enviado para o pipeline .catch, vejamos um exemplo:

async function myAsyncFunctionWithError() {
  throw "something wrong happen";
}

myAsyncFunctionWithError().catch(error => {
  console.log(error); // something wrong happen
});

Await

O uso do await é restrito apenas dentro de uma função declarada com a keyword async, basicamente o que ele faz é esperar o valor resposta de uma Promise ou converte o valor em uma Promise resolvida.

async function myAsyncFunction() {
  const payload = await { name: "felipe", age: 22 };
  console.log(payload); // { name: 'felipe', age: 22 }
}

myAsyncFunction();

Nos casos onde não estamos retornando nenhum valor da nossa função, a chamada de execução se mantém como as chamadas de funções normais sem o uso do .then.

Capturando erros com try/catch

O await sempre espera o valor de sucesso da promise, logo não temos como capturar o erro diretamente, para fazer isso temos que fazer uso do try/catch que recebe o valor de reject se caso aconteça, dentro das promises que estão sendo executadas dentro do bloco try:

async function myAsyncErrorFunction() {
  throw "ops, something wrong happen";
}

async function myAsyncFunction() {
  try {
    const response = await myAsyncErrorFunction();
  } catch (error) {
    console.log(error); // ops, something wrong happen
  }
}

myAsyncFunction();

Executando esse bloco, o erro acontece dentro da promise myAsyncErrorFunction e é capturada dentro do bloco catch do try/catch.

Em resumo, o uso em conjunto das implementações fazem com que nosso código seja extremamente mais simples e legível, fazendo com que tratar dados assíncronos (ou síncronos) seja de forma mais direta e eficaz.

Espero que tenha gostado dessa pequena série, nos vemos nos próximo post!

🔭

JS Async: Promises

Felipe Sousa — Mon, 31 Aug 2020 00:07:38 +0000

This post is the second in a series of 3 posts to explain and show how to work with asynchronous data in JavaScript.

In this article, I will focus on Promises and how we can use them, what are the rules, and some examples to see in practice how they work.

if you haven't checked out the first article in this series on JS Async where I talk about callbacks and how they work just access here.

What are Promises?

Promises are a native JavaScript implementation to more elegantly and simply handle asynchronous data.

Just like promises in the real world, promises in JavaScript can or not happen, technically we can say that we have control of the moment of success and error of the flows we are dealing with, but you can think, "but I also already have this possibility of handler with callbacks", and yes you can handler your errors using callbacks too, but imagine being able to compose, pipe your operarations and also get errors in a more elegant and literally more declarative way, that's just a little bit of what Promises can do.

Creating a Promise

The promises have 2 stages, creation and consume. Let's check the basics to create a new promise:

const myPromise = new Promise(function (resolve, reject) {
  // do something
  if (true) {
    // ...
    resolve(); // resolving the promise;
  } else {
    reject(); // rejecting the promise;
  }
});

Here we're creating a new Promise instance that receive a function as a parameter, this function accept 2 methods: resolve and reject, the resolve method which is responsible for capturing the success value and reject which captures the error if it exists.

Now let's create a new function that returns a fake payload 5 seconds and embrace it using the Promises.

function handlerPromise(resolve, reject) {
  setTimeout(function () {
    let data = { name: "felipe" };
    resolve(data);
  }, 5000);
}

const myPromise = new Promise(handlerPromise);

The handlerPromise function call the resolve method after 5 seconds exporting the variable data as a Promise's payload.

Consuming a Promise

To capture the success values of a promise we use the .then method, it can take up to 2 functions as parameters, the first one capturing the result exported by resolve methods and the second capturing errors exported by reject method. Therefore, not only for success stories but optionally the .then method can also handle error data.

myPromise.then(
  function (payload) {
    console.log(`My name is ${payload.name}.`);
  },
  function (error) {
    console.log("oooppps, something wrong happen.");
  }
);

Try changing the handlerPromise function by calling reject instead of resolve so you can see how error cases work.

An alternative way to catch the error when executing a promise is to use the .catch method, which in turn accepts a function that receives the error triggered as a parameter:

myPromise.catch(function (error) {
  console.log("ooops, something went wrong");
});

Something important and super practical when working with promises is that the .then method when it returns some value, that value is also a promise, which means that you can chain together several .then to handle the values as pipelines.

Imagine the same example as before, but now in each step of execution we have to modify the initial payload:

myPromise
  .then(function (payload) {
    return { ...payload, age: 22 };
  })
  .then(function (payload) {
    return { ...payload, role: "developer" };
  })
  .then(function (payload) {
    console.log(payload);
    // { name: 'felipe', age: 22, role: 'developer' }
  })
  .catch(function (error) {
    console.log(error);
  });

Within our first .then I'm adding the age property, in the second the role property within the original payload, while our third pipeline receives the payload changed according to the previous pipes. It is important to remember that only the .then continues the flow after a return, the .catch after being executed ends the process.

In addition to the pipelines to treat cases of success and error, the promises also have a method that is always executed, even after an error, this method is .finally, it also takes a function as a parameter and can be used in some interesting cases to avoid duplication of code, execute a function or trigger an event that removes a loading from a user's screen, for example.

myPromise
  .then(...)
  .catch(...)
  .finally(function () {
    // always executed
  })

Composition

Promises also have 2 methods that help us work with asynchronous processes in parallel, they are Promise.all() and Promise.race(). Both methods receive an array of items and work as follows:

Promise.all(): Returns a promise with the results array after all the iterables in the list are completed. Returns an error if any of the items are rejected/fail.
Promise.race(): Returns a promise when the first iterable is resolved/rejected.

In the examples below we will use 2 similar promises, one executed in 200ms and the other in400ms, as a result they bring "200" and "400" respectively.

const first = new Promise(function (resolve, reject) {
  setTimeout(function () {
    resolve("200");
  }, 200);
});

const second = new Promise(function (resolve, reject) {
  setTimeout(function () {
    resolve("400");
  }, 400);
});

Example of how Promise.all() works:

Promise.all([first, second]).then(function (payload) {
  console.log(payload); // ['200', '400'];
});

Example of how Promise.race() works:

Promise.race([first, second]).then(function (payload) {
  console.log(payload); // '200';
});

With this type of functionality, some managements that previously would require a few lines of code, can be encapsulated inside a few pipelines.

It is important to remember that even before the Promises are implemented natively in JavaScript, some libraries such as q.JS and when.JS already came with this concept of similarity and applicability.

Thank you very much for reading, in the next post of this series I will talk about working with asynchronous processes using async/await!

I hope you enjoyed, see you next time!

🦐

JS Async: Promises - pt-br

Felipe Sousa — Thu, 27 Aug 2020 17:30:07 +0000

Esse post é o segundo de uma série de 3 posts para explicar e mostrar como trabalhar com dados assíncronos em JavaScript.

Nesse artigo focarei nas Promises e como podemos utilizá-las, quais as regras e alguns exemplos para vermos na prática como elas funcionam.

Caso não tenha conferido o primeiro artigo dessa série sobre JS Async onde falo sobre callbacks e como elas funcionam basta acessar aqui.

O que são Promises?

As Promises - ou Promesas - são uma implementação nativa do JavaScript para tratar de maneira mais elegante e simples dados que são assíncronos.

Assim como promessas do mundo real, as promessas dentro do JavaScript podem ou não acontecer, de maneira técnica podemos dizer que temos controle do momento de sucesso e erro dos fluxos que estamos tratando, porém você pode pensar, "mas eu também já tenho essa possibilidade de tratamento dentro das callbacks", e sim você pode tratar seus erros usando callbacks também, porém imagine poder compor, tratar valores em formas de pipes e ainda por cima tratar os erros de forma mais elegante e literalmente mais declarativa, isso é só um pouco do que as Promises podem fazer.

Criando uma Promise

As Promises possuem 2 passos: criação e consumo. Vejamos um exemplo básico para criar uma nova promessa:

const myPromise = new Promise(function (resolve, reject) {
  // do something
  if (true) {
    // ...
    resolve(); // resolving the promise;
  } else {
    reject(); // rejecting the promise;
  }
});

Aqui estamos criando uma nova instância de classe Promise que recebe uma função como parâmetro, esta função aceita 2 métodos: resolve e reject, o método resolve que é responsável por capturar o valor de sucesso e reject que captura o erro se ele existir.

Agora vamos criar uma nova função que retorna um fake payload em 5 segundos e adotá-la usando os conceitos de Promises:

function handlerPromise(resolve, reject) {
  setTimeout(function () {
    let data = { name: "felipe" };
    resolve(data);
  }, 5000);
}

const myPromise = new Promise(handlerPromise);

A função handlerPromise chama o método resolve após 5 segundos exportando a variável data como o valor para a promise.

Consumindo uma Promise

Para capturar os valores de sucesso de uma promessa usamos o método .then, esse pode receber até 2 funções como parâmetros, sendo a primeira a que captura o resultado exportado pelo métodos resolve e a segunda captura os erros exportados pelo método reject. Logo, não somente para dados casos de sucesso mas opcionalmente o método .then também pode tratar os dados de erro.

myPromise.then(
  function (payload) {
    console.log(`My name is ${payload.name}.`);
  },
  function (error) {
    console.log("oooppps, something wrong happen.");
  }
);

Experimente mudar a função handlerPromise chamando reject ao invés de resolve e assim poderá ver como funciona os casos de erro.

Uma forma alternativa para a captura do erro na execução de uma promessa é usar o método .catch, esse por sua vez aceita uma função que recebe o erro disparado como parâmetro:

myPromise.catch(function (error) {
  console.log("ooops, something went wrong");
});

Algo importante e super prático quando se trabalha com promessas é que o método .then quando retorna algum valor, esse valor também é uma promessa, o que significa que você pode encadear vários .then para tratar os valores em formato de pipelines.

Imaginemos o mesmo exemplo anterior porém agora em cada passo de execução temos que modificar payload inicial:

myPromise
  .then(function (payload) {
    return { ...payload, age: 22 };
  })
  .then(function (payload) {
    return { ...payload, role: "developer" };
  })
  .then(function (payload) {
    console.log(payload);
    // { name: 'felipe', age: 22, role: 'developer' }
  })
  .catch(function (error) {
    console.log(error);
  });

Dentro do nosso primeiro .then estou adicionando a propriedade age, no segundo a propriedade role dentro do payload original, já o nosso terceiro pipeline recebe o payload alterado de acordo com os pipes anteriores. É importante lembrar que apenas o .then continua o fluxo depois de um return, o .catch depois de executado finaliza o processo.

Além dos pipelines para tratar casos de sucesso e erro, as promessas também possuem um método que é sempre executado, até mesmo depois de um erro, esse método é o .finally, também recebe uma função como parâmetro e pode ser usado em alguns casos interessantes para evitar duplicidade de código, executar uma função ou disparar um evento que remove um loading da tela de um usuário, por exemplo.

myPromise
  .then(...)
  .catch(...)
  .finally(function () {
    // always executed
  })

Composição

As Promises também possuem 2 métodos que nos ajudam a trabalhar com processos assíncronos em paralelo, são eles Promise.all() e Promise.race(). Ambas as funções recebem um array de itens e funcionam da seguinte forma:

Promise.all(): Retorna uma promise com o array de resultados depois de todos os iteráveis da lista estarem completados. Retorna um erro caso algum dos itens seja rejeitado/falhe.
Promise.race(): Retorna uma promise quando o primeiro iterável for resolvido/rejeitado.

Nos exemplos abaixo vamos utilizar 2 promessas similares, uma executada em 200ms e outra em 400ms, como resultado trazem "200" e "400" respectivamente.

const first = new Promise(function (resolve, reject) {
  setTimeout(function () {
    resolve("200");
  }, 200);
});

const second = new Promise(function (resolve, reject) {
  setTimeout(function () {
    resolve("400");
  }, 400);
});

Exemplo de como funciona o Promise.all():

Promise.all([first, second]).then(function (payload) {
  console.log(payload); // ['200', '400'];
});

Exemplo de como funciona o Promise.race():

Promise.race([first, second]).then(function (payload) {
  console.log(payload); // '200';
});

Com esse tipo de funcionalidade, alguns manejos que antes necessitariam de umas tantas linhas de código, pode ser encapsulado dentro de uns poucos pipelines.

Importante lembrar que antes mesmos das Promises serem implementadas nativamente dentro do JavaScript, algumas bibliotecas tais como q.JS e when.JS já vinha com esse conceito de similiaridade e aplicabilidade.

Muito obrigado pela leitura, no próximo post dessa série eu irei falar sobre como trabalhar com processos assíncronos usando async/await!

Espero que tenha gostado do conteúdo, nos vemos no próximo!

🦐

JS Async: Callbacks

Felipe Sousa — Tue, 18 Aug 2020 21:45:09 +0000

This article was originally published at my personal website.

Asynchronous patterns are part of everyday life, can be a timer, reading a file or making a request, etc., at some point, you will need to manipulate this pattern and it is very important to know how to work with them and which strategy is best for each one of the cases that may happen.

This post is the first in a series of 3 posts to explain how to work with asynchronous patterns in JavaScript. In this article, I will focus on Callbacks and how we can use them, what are the rules, and some examples to see in practice how it works.

If you have questions about what asynchronous functions are, how they work, and/or why they exist, recommend reading this article which explains well how calls and functions work within JavaScript.

Callbacks

Also known as the oldest way to handle asynchronous data, callbacks allow us to inject a function into an asynchronous execution so that we can control the result(s) when they are available. In a very indirect way, it's as if we're sending a "spy" who will inform us when something happens within the call we are executing.

We'll create a simple example to get started, a function that returns a new Date():

function getNewDate() {
  return new Date();
}

const result = getNewDate();

console.log(result);

In this case, we save the result value in the variable result, print it on the screen and everything works as expected, but if this information happens to be within a call to an endpoint, timer, or some other execution that is not immediate, what happens?

Let's simulate the same case, but now the getNewDate function will only return the value after 4 seconds:

function getNewDate() {
  setTimeout(function () {
    return new Date();
  }, 4000);
}

const result = getNewDate();

console.log(result); // undefined

When executed, we receive undefined as a result of the variable result. This is because the value returned by the getNewDate function is executed 4 seconds later, and our result variable expects the value at execution time, that is, we have to get this value ONLY when it is available, in case otherwise we will not be able to manipulate or store this value.

The solution for this case is quite simple, let's pass a function that is outside the scope of the getNewDate function to receive the real value that we want to manipulate, in this case, new Date ().

function getNewDate(callback) {
  setTimeout(function () {
    callback(new Date());
  }, 4000);
}

function getPayload(payload) {
  console.log(`The date is: ${payload}`);
}

getNewDate(getPayload);

To manipulate the result data of the getNewDate function, I created a function calledgetPayload, this is sent as a parameter to our main function that instead of returning the value as before, now executes the callback function passing the value of result as a parameter, like this the getPayload function is executed only when the value is available to be captured, simulating a" wait "within the execution. The function getPayload in turn only receives the payload that contains the result of the execution and prints on the screen: 🥳.

Callbacks are just the starting point, in the next article in this series we'll see how to work using Promises which, in addition to a better interface, has a couple of API's to better handle our asynchronous cases.

See you at the next one!

🐊

Automatizando documentação para projetos TypeScript com Github e Typedoc

Felipe Sousa — Sat, 21 Mar 2020 04:12:41 +0000

"Automatizando" e "TypeScript" na mesma frase pode soar hype até demais, porém ambas não ganharam famas a toa, automatizar vem sendo cada vez mais buscado entre todas as camadas de produtos, desde um fluxo automatizado de envio de emails ou publicação de uma biblioteca no npm a partir de algum hook, etc. Independente do nível, automatizar quase sempre vai ser uma ótima opção.

Nos últimos projetos que tenho trabalhado, optamos por usar TypeScript e tirar proveito o máximo que puder de acordo com o caso. Documentar projetos é um trabalho que posso confessar, é cansativo, e principalmente quando se trata de uma documentação de código, sim, aquela que você escreve pra outro dev entender - ou você mesmo em um futuro -. Obrigar alguém a ler seu código a partir de um editor é algo além de bem antigo, não tão funcional a nível de entendimento de código, o que atrapalha em possíveis bugs e/ou features.

O que vamos fazer e o que vamos usar?

TypeScript + Typedoc + Github Actions + Github Pages = 🚀! É isso, vamos criar uma documentação automática com Typedoc, criaremos um pipeline com Github Actions e publicar automaticamente a documentação no GitHub Pages.

Getting Starting

Vamos definir alguns steps de config inicial e instalação do projeto para termos uma base:

criar um novo diretório e criar um package.json.
iniciar um novo projeto TypeScript e definir as configurações iniciais.
configurar Typedoc e .gitignore.
configurar npm scripts.
configurar pipelines do Github Actions.
atualizar readme com o status dos pipelines e link da aplicação.

Publicarei o código nesse link, irei deixar os commits com cada step que temos acima para uma melhor consulta. 🧐

1 - Criar um novo diretório e criar um `package.json`.

$ mkdir typescript-docs && cd typescript-docs && npm init -y

2 - Iniciar um novo projeto TypeScript e definir as configurações iniciais.

Execute o comando para criar o arquivo de configuração inicial tsconfig.json.

$ npx tsc --init

Depois, necessitamos atualizar nosso arquivo tsconfig.json com a seguinte propriedade outDir para enviar o código compilado para a pasta dist na raiz do projeto, além de configurar os formato do modulo que vai ser gerado:

"outDir": "./dist"

3 - Configurar Typedoc e `.gitignore`.

Para utilizar o Typedoc necessitamos fazer previamente sua instalação :

$ npm i --save-dev typedoc

Após a instalação, vamos executar o comando para gerar a documentação dos arquivos da pasta ./src/ e criar um diretório chamado ./docs:

$ ./node_modules/typedoc/bin/typedoc --out docs src

Após isso adicionamos as pastas dist e docs no nosso .gitignore:

dist/
docs/
node_modules/

4 - Configurar npm scripts.

Vamos adicionar algumas linhas mais dentro do nosso package.json:

"scripts": {
    "dev": "tsc -w",
    "docs": "./node_modules/typedoc/bin/typedoc --out docs src"
}

Dessa forma, temos como executar de uma forma melhor o compiler de docs e do typescript.

5 - Configurar pipelines para Github Actions.

Esse artigo não tem um foco de explicar como funciona, regras, sobre o GitHub Actions, basicamente é uma infraestrutura de automatização e entrega, como os conhecidos Travis CI, Circle CI e muitos outros. Para mais detalhes sobre Github Actions você pode ver aqui.

Em resumo, vamos criar o arquivo de configuração para nosso(s) pipelines na pasta .github/workflow/main.yml:

name: workflow

on:
  push:
    branches:
      - master

jobs:
  docs:
    name: Publish Docs to Github Pages
    runs-on: ubuntu-latest
    steps:
      - name: Action Checkout
        uses: actions/checkout@v1

      - name: Use Node.js 10.x
        uses: actions/setup-node@v1
        with:
          node-version: 10.x

      - name: Install Dependencies and Generating Documentation
        run: npm install && npm run docs

      - name: Publishing on Github Pages
        uses: peaceiris/actions-gh-pages@v3
        with:
          deploy_key: ${{ secrets.ACTIONS_DEPLOY_KEY }}
          publish_dir: ./docs

De maneira geral estamos:

Definindo o nome do nosso workflow.
Definindo em qual ação para qual branch .
Definindo um job chamado Publish Docs to Github Pages que tem 4 steps, sendo os 2 últimos os mais importantes, o terceiro que vai instalar e gerar a documentação e o quarto que utiliza uma "action" da store do Github actions. Note que a propriedade publish_url tem que ter o mesmo nome do seu output de documentação, que no nosso caso se chama docs.

A Action peaceiris/actions-gh-pages necessita de uma configuração para permitir acesso para a branch gh-pages - que é onde vai ficar nossa documentação -. Veja as instruções de instalação e configuração aqui..

Após a configuração da action de permissão acima, já podemos enviar nosso projeto para o GitHub.

$ git remote add origin <YOUR_REMOTE_URL> && git push origin master

Para acompanhar o processo do workflow, você pode acessar a aba "Actions" dentro da repositório no Github.

6 - Atualizar readme com o status dos pipelines e link da documentação.

Vamos copiar o link do badge do pipeline para termos sempre o status atualizado dos nossos builds sem necessitar verificar os pipes. Dentro da aba de actions você pode gerar os badges para cada workflow que você tem, é só copiar e colar! 😁

Depois disso vamos criar um readme.md básico e colar nosso badge:

### TypeScript Docs

> Projeto usado como exemplo no artigo sobre automatização de documentação para projetos typescript

![workflow](<https://github.com/felipesousa/typescript-docs/workflows/workflow/badge.svg>)

Clique aqui para verificar o resultado.

O processo de tudo é teoricamente simples, alguns steps e tudo funciona bem sem necessidade de reescrita, isso é só uma pontinha simples do que podemos fazer com integrações, Github actions, etc!

Até a próxima! 🏆

Usando relative paths com TypeScript

Felipe Sousa — Fri, 20 Mar 2020 11:14:56 +0000

Diante da quantidade de funcionalidades que vemos recebendo dentro das linguagens de programação, consigo também "atualizamos" as responsabilidades de buscar novas formas de melhorar, automatizar, limpar e criar boas práticas para que tenhamos uma aplicação além de melhor, mais escalável e consistente.

No mundo onde modularizar e distribuir traços de código virou padrão (não podemos esquecer do famoso caso da biblioteca de 11 linhas que causou um problema consideravelmente grande!), naturalmente vamos ter momentos onde teremos uma cadeia de imports seja de dependência ou de importação local grande demais, o que não consideravelmente é algo negativo, mas o problema começa quando pensamos em algo comum: refatorar.

Introdução

Imaginemos um caso de uso onde temos uma árvore de código simples similar a essa:

src/
- config/
  - constants.ts
- components/
  - hello.ts
- services/
  - service.ts
- screens/
  - home/
    - home.screen.ts
tsconfig.json

O arquivo src/screens/home/home.screen.ts têm o seguinte código:

import Hello from '../../components/hello';
import Service from '../../services/service';
import config from '../../config/constants';

class HomeScreen ...

Nada de novo e sem novidades, porém observando mais atenciosamente os paths das linhas 1, 2 e 3, estamos importando os arquivos de forma bastante manual, em caso de movermos um arquivo, ou uma pasta inteira para outro ponto da aplicação, teremos que manualmente importar cada arquivo, hoje não é um problema, mas imagine ter uma aplicação grande, com bastante arquivos, dependências... Ordenar um possível refactor seria no mínimo cansativo e pior ainda, estressante.

Existe solução?

Muitas soluções, desde auto-imports, plugins para identificar export/import, integrações para VSCode, Vim, etc. Porém são ferramentas adicionais e que dependem de um editor para funcionar, a ideia não é automatizar somente, mas sim, resolver o problema de escrever ou saber exatamente o caminho exato para um arquivo.

Para solucionar esse problema, vamos apenas adicionar 2 propriedades dentro do nosso arquivo tsconfig.json:

    "moduleResolution": "node",
    "baseUrl": "./src/"

A propriedade moduleResolution é como vamos definir a estratégia de importação, onde nesse caso, os possíveis valores são: node ou classic sendo esse, o valor default. Quando com valor node as importações vão seguir o modelo base/relative, modelo comumente conhecido quando estamos importando algo que existe dentro da pasta node_modules, onde não necessitamos definir definir o node_modules/module e sim apenas o nome do modulo, sendo esse base o diretório que você define dentro da propriedade baseUrl, que define a pasta onde vão partir as importações.

No nosso caso, o valor de baseUrl foi configurado definir nossa pasta src/ logo, toda importação que você fizer dentro da aplicação, deve tomar conta que você vai estar fazendo referência desde a pasta ./src/ e não mais dentro do real path do arquivo que você está editando. Vejamos o mesmo exemplo do código de home.screen.ts para entender melhor:

import Hello from 'components/hello';
import Service from 'services/service';
import config from 'config/constants';

class HomeScreen ...

Para cada arquivo que você importa, o compiler do typescript vai assignar o path escrito como o valor relativo do real path, assim completando o modelo comentado antes base/relative, onde o base é tomado dentro do baseUrl em momento de compilação. Assim apenas conseguimos resolver problema de importação sem mais ter que se preocupar se você assignou o arquivo certo, ou não esqueceu uma sequência de ../durante as importações.

Até a próxima! 😁

Capturando erros com React Error Boundary

Felipe Sousa — Wed, 18 Mar 2020 04:19:32 +0000

Um conhecimento em React lifecycles é indicado, caso tenha dúvidas ou não conheça, esse guia pode lhe ajudar!

Introdução

React 16.x trouxe consigo ótimas e boas implementações e melhorias significantes, uma delas é extremamente útil para controle de erros dentro da aplicação, conhecido por error boundary é uma estratégia de captura de erros que naturalmente quebrariam a aplicação (comportamento natural de aplicações javascript), agora podem ser controlados e escalados com simples lifecycles React! Até o momento apenas classes components têm suporte aos ciclos de vida que são necessários para a captura e controle, mais detalhes pode encontrar na documentação oficial.

Os lifecycles são static getDerivedStateFromError e componentDidCatch que podem ser usados juntos ou separados, mas o conjunto dos dois métodos possibilitam um controle melhor.

Como funciona?

Genericamente falando, o lifecycle captura um error em qualquer ponto da árvore abaixo dele, qualquer erro que ocorra dentro do mesmo nó só será capturado pelo primeiro boundary da árvore no nível superior ao do nó. De maneira geral e como indicação como boas práticas, se aplica BoundaryWrapper para capturar os erros genéricos, como forma de centralizar as capturas de erros, facilitando um debugging, mudança, etc. Os outros boundary's específicos devem ser criados e aplicados de acordo com a necessidade, mas sempre atento a regra anterior de captura por nível.

Uma forma de assemelhar bem o uso de um error boundary é comparar com o catch natural que captura os erros dentro do javascript comumente já conhecido.

Demo

Vamos simular um erro em uma requisição simples de API e disparar um error dentro do catch como conhecemos geralmente:

import MyBoundary from './my-boundary';

class DispacthError extends React.Component {
  componentDidMount = async () => {
    try {
      const response = await fetch('https://fake.url'); // fake url to crash

    } catch(e) {
      throw new Error(e.toString()); // throwing a new error
    }
  }

  render() {
    <div>
      <p>hi!</p>
    </div>
  }
}

const App = () => (
  <MyBoundary>
    <DispacthError />
  </MyBoundary>
)

ReactDOM.render(
  document.getElementById('root'),
  <App />
);

O component MyBoundary é o responsável por capturar o erro e mostrar uma mensagem:

export default class MyBoundary extends React.Component {
  constructor(props) {
    super(props);
    this.state = { error: false };
  }

  static getDerivedStateFromError(data) {
    return { error: true }; // update the state object
  }

  componentDidCatch(error, data) {
    // handle the error content here.
  }

  render() {
    const { error } = this.state;
    const { children } = this.props;

    if (error) return <p>Something wrong happen! 🧐s</p>;

    return children;
  }
}

O método componentDidCatch contém as informações do erro e todos os detalhes do que disparou o erro. Já o método getDerivedStateFromError retorna o novo estado para a classe, que nesse caso atualiza o state que está sendo utilizado dentro do método render, onde retorno uma mensagem de erro genérica ou o child que foi adicionado dentro de App.js.

Resumo

O React de uma forma geral cada vez mais aproxima a biblioteca e todo o seu "ecossistema" o mais próximo possível da linguagem nativa, o que ajuda muito em questão de performance, curva de aprendizagem e implementação, fora as melhorias de testes, debugging, escalabilidade e compartilhamento. Capturar erro dessa forma é simplesmente uma das estratégias mais simples que me parecem hoje em dia, visto que antes, um controle a alto nível requeria um trabalho um pouco mais manual e bem mais verboso, o error boundary é uma ótima spec que ajuda e muito na qualidade e praticidade.

Existem boas referências nas quais você pode se aprofundar ainda mais e controlar melhor os casos de erros mais específicos ou mais genéricos, o artigo Exploit React Error Boundaries to Improve UX do Jim Medlock é com certeza uma boa recomendação além da documentação oficial do React.

Até a próxima!

Storybook: Why, When and How.

Felipe Sousa — Thu, 27 Jun 2019 18:45:09 +0000

Applications based at components aren't news for nobody, libraries like React, VueJS, and Angular are basically our first option when we're creating a new project, it's because they are really good for us developers.

The Storybook is a library that allows us to divide our components, simulating your behavior, actions, properties, etc.

Ps: all examples here will be based on React. If you wanna see how setup using another library, check out that link.

Alright, are you starting your project, you enter in your src folder and create a new file called Button.js, after that, you call this component inside your index.js file and open your browser to check the component. You'll repeat it every time that create a new one! Ok, it's not a problem if you are working alone or in a small project, but imagine that the project is big, or you are working with a team (most common case). If someone else needs to use your component, this person will need to open your Button.js file, check the properties, styles, actions, etc. It's a painful process that cost time and of course, patience!.

Setup

Alright, let's start a new create-react-app project.

$ create-react-app your_project && cd your_project

After that, we can set up the Storybook running the command:

$ npx -p @storybook/cli sb init

Now you only need to run:

$ yarn storybook

A local server will be created at http://localhost:9009 and you will see something like that:

That's all you need to set up and run your storybook dashboard. Now, we'll check how you can add your own components on Storybook Dashboard.

Before we go to the next section, a folder called .storybook was created in your root project, that folder contains all the setup generated by the Storybook CLI, don't care about it now, we'll talk about it later.

Adding your own components

Now, after setup, go to the file src/stories/index.js, you'll see that:

import React from 'react';

import { storiesOf } from '@storybook/react';
import { action } from '@storybook/addon-actions';
import { linkTo } from '@storybook/addon-links';

import { Button, Welcome } from '@storybook/react/demo';

storiesOf('Welcome', module).add('to Storybook', () => <Welcome showApp={linkTo('Button')} />);

storiesOf('Button', module)
  .add('with text', () => <Button onClick={action('clicked')}>Hello Button</Button>)
  .add('with some emoji', () => (
    <Button onClick={action('clicked')}>
      <span role="img" aria-label="so cool">
        😀 😎 👍 💯
      </span>
    </Button>
  ));

Here you can check all the components that are showing at http://localhost:9009, all the components are registered here to be added on the Storybook Dashboard.

Ok, let's add a new component called Card.js inside our src/components folder.

import React from 'react';
import PropTypes from 'prop-types';

const Card = ({ title, description, }) => (
  <div>
    <h1>{title}</h1>
    <p>{description}</p>
  </div>
);

Card.propTypes = {
  title: PropTypes.string,
  description: PropTypes.string,
};

Card.defaultProps = {
  title: 'Default Title',
  description: 'Default Description', 
};

export default Card;

Our Card component is so simple, the component receives two optional properties, title and description, if the component doesn't receive the props, it will show your default values already defined.

Now let's add our Card component to src/stories/index.js file.

...
import Card from '../components/Card';

...

storiesOf('Card', module)
  .add('default', () => (<Card />))
  .add('with props', () => (<Card title="Lorem Impsum" description="Hi everyone" />))

The first thing that you need is to call the method storiesOf, that receive two params, the first one is the name of your story (or component) and, the second one is a param provided by storybook called module.

After that, I added a pipe called add, that receive also two params, the first one is the story name about the component (or expected behavior), I added "default" because I'm not passing any param, so I expect to see the default state of the component, the second one is the component, in this case, only calling the component without props. The second add pipe, receive a different name and in this case, I'm calling the component with their props, now, if I open my dashboard, I'll be able to see the 2 expected behaviors from my component.

Add-ons

Alright, Storybook works fine, you now can divide your components see one by one separately, but if you were able to edit within the dashboard itself the properties of your component? or see the actions log? that would be great, right?

Storybook can do more than only see our components divided, with it we are able also to do more things like: simulate actions, change our props on our dashboard, see jest updates, accessibility, change the state of your component (in React case), etc.

By now, I'll show how we can change our props and simulate actions. If you interest in others add-ons, you can check it here.

Alright, let's update our Card component, now we'll add a button that will call a prop called onButtonClicked. Let's do it:

import React from 'react';
import PropTypes from 'prop-types';

const Card = ({ onButtonClicked, title, description }) => (
  <div>
    <h1>{title}</h1>
    <p>{description}</p>
    <button onClick={onButtonClicked}>Click here</button>
  </div>
);

Card.propTypes = {
  title: PropTypes.string,
  description: PropTypes.string,
  onButtonClicked: PropTypes.func,
};

Card.defaultProps = {
  title: 'Default Title',
  description: 'Default Description',
  onButtonClicked: () => null,
};

export default Card;

Now, let's back to our src/stories/index.js file and add a new prop to our Card Stories:

...

import Card from '../components/Card';

...

storiesOf('Card', module)
  .add('default', () => (<Card />))
  .add('with props', () => (
    <Card
      title="Lorem Impsum"
      description="Hi everyone"
      onButtonClicked={() => {console.log("button was clicked")}}
    />))

Now, if you open the Dashboard and click on the button, the console will show the message button was clicked. Alright, no news so far, let's first able our props be edited using the dashboard.

The first thing that you need to do is install the addon-knobs module:

 $ yarn add @storybook/addon-knobs --dev

After that, you need to change your .storybook/addons.js file:

import '@storybook/addon-actions/register';
import '@storybook/addon-links/register';
import '@storybook/addon-knobs/register';

Ok, now open you src/stories/index.js file and import the module and change the props title and description:

...
import { withKnobs, text } from '@storybook/knobs';
...

storiesOf('Card', module)
  .addDecorator(withKnobs)
  .add('default', () => (<Card />))
  .add('with props', () => (
    <Card
      title={text('title', 'lorem impsun')}
      description={text('description', 'Hi everyone')}
      onButtonClicked={() => {console.log("button was clicked")}}
    />))

If you check detailed, I added a new pipe after the storiesOf method, the .addDecorator add the support to use knobs. The title and description props now are receiving a method called text, that receive as first param the name of the property, the second one is a default value, now, check your dashboard and on footer section, click on Knobs tab, you'll see the that props are able to be edited! 🥳

Alright, let's track now the onButtonClicked action, to do that, we need to use the action module and change our prop on Card Component:

...
import { action } from '@storybook/addon-actions';
...

storiesOf('Card', module)
  .addDecorator(withKnobs)
  .add('default', () => <Card />)
  .add('with props', () => (
    <Card
      title={text('title', 'lorem impsun')}
      description={text('description', 'Hi everyone')}
      onButtonClicked={action('button clicked')}
    />))

Now, back to your dashboard and select the table Actions and try to click on the button. 🚀

Alright, as you can see, Storybook is a super library that can help us to create more productive and smart apps, this post was only an introduction and you can check more things here.

That's all folks, thank you for your time!

Bye!

Forem: Felipe Sousa

Automating Front End Development with Anima

Introducing Anima! 🎉

Example Project

Design

1. Install and Login

2. Project Setup and Preferences

Where the magic happens 🪄

Fetching Data and Custom actions

Live Demo

JS Async: async/await

Async

Await

Catching errors with try/catch

JS Async: async/await - pt-br

Async

Await

Capturando erros com try/catch

JS Async: Promises

What are Promises?

Creating a Promise

Consuming a Promise

Composition

JS Async: Promises - pt-br

O que são Promises?

Criando uma Promise

Consumindo uma Promise

Composição

JS Async: Callbacks

Callbacks

Automatizando documentação para projetos TypeScript com Github e Typedoc

O que vamos fazer e o que vamos usar?

Getting Starting

1 - Criar um novo diretório e criar um package.json.

2 - Iniciar um novo projeto TypeScript e definir as configurações iniciais.

3 - Configurar Typedoc e .gitignore.

4 - Configurar npm scripts.

5 - Configurar pipelines para Github Actions.

6 - Atualizar readme com o status dos pipelines e link da documentação.

Usando relative paths com TypeScript

Introdução

Existe solução?

Capturando erros com React Error Boundary

Introdução

Como funciona?

Demo

Resumo

Storybook: Why, When and How.

Setup

Adding your own components

Add-ons

1 - Criar um novo diretório e criar um `package.json`.

3 - Configurar Typedoc e `.gitignore`.