DEV Community: Nícolas Gabriel

EventSource: Real-Time Made Easy

Nícolas Gabriel — Thu, 26 Jun 2025 11:09:33 +0000

Often when you have a problem where you need real-time communication the first thing that comes to mind is... of course, WebSocket, right?

And from a certain perspective, you're not wrong! But at the same time, maybe other options could better fit your use case. Today I want to talk about one of them that is not frequently mentioned: EventSource.

What is it?

EventSource is widely available for all browsers, and it is dead simple.

It’s essentially an HTTP request that stays open, allowing the server to continuously push “messages” to the client as long as the connection remains active.

Those messages, just like WebSocket messages, are strings. So you could either send a "Hello world", or a { "hello": "World" }. Making it a viable option thanks to its simplicity and ease of implementation.

Why not WebSocket?

When considering that, the most important criteria is actually your use case! Because EventSource has one really important limitation: It only sends data from server to client, not client to server. That is, it is a unidirectional communication, not bidirectional like WebSocket.

Given that it is a great fit for use cases where the client only needs to receive updates but not send them. Think of things like live notifications, real-time dashboards, stock prices, sports scores, log streams, or live comment feeds. Anywhere the server pushes data and the client listens, SSE can shine.

But considering that your use case matches that limitation, then EventSource is a good option for you! It avoids all the WebSocket configuration that you need to do in order to support it both for server and client.

But okay, theory is great and nice, but "talk is cheap, show me the code" right? So...

How do I implement it?

Since we have two sides, Backend and Frontend, let's start by the one who initiates the connection, which is the client.

Client (Browser)

The underlying logic differs a bit from WebSocket since it runs over plain HTTP, but the high level logic is the same, it:

Client sends a request to connect to the server.
The server sends back a response with "text/event-stream" content type
client knows it accepted and passively listens for new messages.

In code, this listen is done like this:

const source = new EventSource("https://yourapi.com/notifications")

source.onopen = () => console.log("EventSource started!")

source.onmessage = (event) => {
  // If it is plain text:
  console.log(event.data)
  // If it is a JSON:
  console.log(JSON.parse(event.data))
}

source.onerror = () => console.error("EventSource failed!")

And that's it. As you can see, you can do everything in less than 10 lines of code!

But the server is a bit more varied, as it may change depending on which language and framework you choose, but let's go!

Server

Presuming you're into the Node.JS ecosystem I'll use express in the example.

const express = require('express');
const app = express();

app.get('/notifications', (req, res) => {
  res.setHeader('Content-Type', 'text/event-stream');
  res.setHeader('Cache-Control', 'no-cache');

  const send = () => {
    const data = {
      message: 'Hello from server',
      timestamp: new Date().toISOString()
    };
    res.write(`data: ${JSON.stringify(data)}\n\n`);
  };

  // So every 2s, it will send a new message!
  const interval = setInterval(send, 2000);

  req.on('close', () => clearInterval(interval));
});

And with that you're going to keep sending notifications when the client connects to the route.
Just some observations:

The "text/event-stream" header is mandatory, it is needed for the browser to understand that it needs to keep listening instead of simply closing upon first response.
The "no-cache" header isn't mandatory, but it's a good practice since we want to send data dynamically instead of just once from cache.

Final considerations

As I mentioned earlier, the biggest benefit is avoiding WebSocket configs, but if you're already using it for some other reason, then it's up to you, since both seem good options!

Regarding disconnection, the Browser automatically tries to reconnect if the connection was abruptly interrupted, but not if intentionally closed by one the sides.

Given all that, now you know one more alternative to speak of when people ask you about server-to-client communication! 😉

If you still have any questions, feel free to leave a comment. I hope this article helped you, see ya!

Centralizing type checking with Type Guards

Nícolas Gabriel — Sat, 22 Feb 2025 20:30:23 +0000

Hello my fellow TypeScript developer!

Introduction

Have you ever tried accessing properties on a variable in TypeScript, only to find that TypeScript isn’t sure what type it is? You know it could be one of two things, but TypeScript’s autocompletion is only showing you common properties?

Let’s say you have an Animal type, which can either be a Bird or a Dog. You need to figure out whether the animal you’re working with is a bird before performing bird-specific logic.

In this situation, it would be easy to fix this problem, to know if the animal provided is a bird or not, we would only need to check its name (or some sort of identifier).

This works because TypeScript can infer that the animal is a Bird by the return of our function, and therefore provides the correct type information. But it is not ideal, doesn't follow well DRY principles... For example if we need to do the same check in another place we would need to do the same animal.name === "bird" again...

And if someday we end up changing "bird" to "eagle", every file with this check would need to be updated. So how could we center the logic in order to be easier to maintain and re-use?

Simple! We can create a Type Guard, which is a function that is able to assert that a variable is from a specific type, making the process of checking types easier and centered in one place.

Creating a Type Guard

In practice, a Type Guard is a function that returns a boolean, and this boolean is the assertion if a variable is or not from a specific type.

If we want to create a Type Guard for the above scenario, it would be written this way:

If it returns true then animal is a Bird, if it is false it is a Dog.

The important part here is the value is Type syntax, which is the core of a Type Guard. With it, we can use this function anywhere and our typings will be more powerful.

Using the Type Guard

Let's try applying it to our previous example:

And as you can see, if it is true it enters the if statement, which has the correct type for Animal: Bird. TypeScript is able to assume that because of our type-guard :).

And TypeScript is smart, so if we add an else, then it would be considered a Dog on it!

A good detail is that the value is Type syntax can be used in any function, even in callbacks! So for example you can also use it on a find, every, a filter or anywhere you think it would be helpful.

Conclusion

I hope I helped you learn something new today! If you still have any questions, feel free to comment them below or connect to me in my social medias.

See you!

How to use Cookies with Ky

Nícolas Gabriel — Sat, 08 Feb 2025 00:53:30 +0000

Hello dear dev!

Ky has been around for several years now, presenting itself as a lightweight, modern alternative to browser fetching. Built on top of the Fetch API, it offers handy features such as hooks and the much-anticipated retries.

But it's not all smooth sailing, for example I'm in a project requiring cookie-based authentication, and I decided to use Ky from the start. However, I quickly ran into an issue... Ky's documentation didn't mention cookies anywhere! After digging into the docs and some trial and error, I found a solution. To save others time, I'm here sharing my approach :).

First, to manage cookies, we'll use tough-cookie, a library that allows you to store, retrieve, and manipulate cookies programmatically. First, install the library and initialize it like so:

import { CookieJar } from "tough-cookie";

const cookieJar = new CookieJar();

Now as I mentioned before, one of the cool features about Ky is their "hooks" right? But what exactly are hooks?

Ky provides hooks, which are functions that run before or after a request. Currently there are four types: beforeRequest, afterResponse, beforeError, and beforeRetry. For handling cookies specifically, the most useful hooks are beforeRequest and afterResponse.

And to use them we need to extend Ky's functionality using ky.extend. These hooks will automatically handle cookies: beforeRequest will inject stored cookies into the request headers, and afterResponse will capture and store new cookies for future requests.

const apiClient = ky.extend({
    hooks: {
        beforeRequest: [
            async (request) => {
                const url = request.url;
                const cookies = await cookieJar.getCookies(url);
                const cookieString = cookies.join("; ");
                request.headers.set("cookie", cookieString);
            },
        ],
        afterResponse: [
            async (request, options, response) => {
                const url = request.url;
                const cookies = response.headers.getSetCookie();
                if (cookies) {
                    for (const cookie of cookies) {
                        await cookieJar.setCookie(cookie, url);
                    }
                }
            },
        ],

    },
});

The only thing is that everywhere which needs or sets cookies, you will need to use that apiClient which you just created instead of the plain ky.

And there you have it! With these simple hooks in place, your Ky requests will automatically handle cookies, saving you time and effort.

I hope this solution helps you as much as it helped me. :)
Have a great day!

Hate on Tailwind... I have seen that before!

Nícolas Gabriel — Sat, 04 Nov 2023 17:50:20 +0000

In 2013, a company called Facebook introduced a framework called "React," which allowed developers to blend their JavaScript logic with their HTML code without having to modify the document directly.

This, my friends, was JSX, or JavaScript Extended, where you could write HTML within your JavaScript! I was just 9 years old, and I didn't know anything about programming, but the rest of the community had strong opinions about it when it was released.

"The audience was skeptical. Most people thought React was a significant step backward." - at JS ConfUS 29/05/2013

React was innovative because it challenged many established best practices of its time.

Separating JavaScript from HTML? Discarded.
Direct DOM manipulation? Discarded.
Two-way data flow? Discarded.

However, its boldness was a double-edged sword. Just as there were people excited about this innovation, others thought it didn't make sense. "Mixing JS with HTML? It will create more complexity and reduced maintainability.".

Some had been mixing JS and HTML before, such as in the MVC design pattern, which had a Model to manage logic, a View to render the UI, and a Controller to mediate between them.

Creating code that resembles React:

In computer science, there is a concept called "Separation of Concerns," which involves separating sections into their own contexts. In other words, you write your HTML in an HTML file, your CSS in a CSS file, and so on. This was a significant reason many opposed React.

Fast forward to today, React is the dominant framework. It's quite remarkable. But how does all of this relate to Tailwind? What about today?

Similar to React's history, Tailwind challenges many of the best practices we used to preach. Some people appreciate the advantages it offers, while others believe that the benefits don't outweigh the drawbacks.

Some dislike it due to its verbosity, but that doesn't make much sense (example in the image):

Verbosity - the quality of being wordy, speaking excessively, or using too many words to express oneself.

The real problem is with the "separation of concerns" mentioned earlier, and in this respect, Tailwind falls short. It's okay for CSS to have 1,000 lines if it has its own file, but a class with 1,000 words pollutes our HTML/JSX.

There are third-party libraries like Tailwind Fold, but there's no native solution that resolves this 100% and is considered a good practice (im looking to you @apply).

With this article, I didn't intend to persuade you or provide a solution, but rather to tell a story and help you understand that this kind of debate has occurred in the past.

As George Santayana said, "Those who cannot remember the past are condemned to repeat it."

Who knows, maybe in 10 years, Tailwind will also become one of the most famous ways to write CSS? Only time and its evolution will tell.

Anyway, thank you for reading!
Have a good day 😄

O problema com vh no mobile

Nícolas Gabriel — Fri, 13 Oct 2023 20:58:25 +0000

Olá, tudo bem? Sabe aquela coisa chata de quando você coloca um min-height: 100vh no seu body e no mobile ele fica com um scroll sem nenhum motivo aparente? Realmente é uma coisa bem irritante e que antigamente era complicada de ser resolvida sem uma certa "gambiarra". Mas vamos começar do começo!

Para caso não saiba, o "vh" do css é uma unidade relativa a 1% do viewport do usuário, porém essa viewport inclui todo o navegador, desconsiderando por exemplo elementos que possam estar cobrindo a tela (como é o caso de celulares)

Por isso funciona no desktop, mas em mobile deixa um scroll!

Já a medida "svh" é o equivalente a "small viewport height", ou seja 1% do menor viewport considerando justamente os elementos que possam cobrir a tela como a barra de endereços do mobile.

Ou seja, perfeito pra celulares pois é muito mais preciso para o que o usuário vê!

Já o "lvh" (large viewport height) é o exato oposto, ele pega o maior viewport possível, desconsiderando a barra de endereços ou uma UI que possa estar cobrindo a tela.

Para desktop ele funciona muito bem como pode imaginar, mas pra mobile depende do seu caso de uso. 🤔

Afinal, um é bom pra desktop e outro bom pra celular, eu teria que usar uma media query pra adaptar então??

Não :D

Felizmente também existe o "dvh" (dynamic viewport height) que se ajusta de acordo com o dispositivo, agindo tanto como svh ou dvh de acordo com o necessário.

Entretanto alegria de pobre dura pouco, e eles ainda não estão disponíveis em todos os navegadores :(

O firefox e IE por exemplo ainda não possuem suporte...

Por isso, eu recomendo usar porém junto de um fallback! Se liga na dica:

body {
  /*
   primeiro você usa o fallback: vh
  */
  min-height: 100vh;

  /*
    e em seguida, você usa a versão nova!
    pois caso ela não funcione, será ignorada e
    o vh informado anteriormente será usado no lugar
  */
  min-height: 100dvh;
}

São propriedades super úteis e hoje em dia uma mão na roda pra evitar bugs de UI desnecessários :)

E é isso, espero que tu tenha aprendido algo novo hoje!
Obrigado por ler, boa sorte no css e até mais! :)

A base de Redux Toolkit e React Redux

Nícolas Gabriel — Thu, 28 Sep 2023 22:08:28 +0000

Está querendo aprender Redux num ambiente js ou react e ainda não sabe por onde começar?
Neste artigo eu vou explicar os conceitos junto do código de forma direta para fazer você entender melhor na prática como ele funciona!

Tabela de conteúdos:

O que é Redux?
Store, a raiz da nossa árvore de estados
Criar coleções usando Slices
Ler valores com Selector
Criando a lógica para alterar valores com Reducers
Alterando valores usando Actions
O fluxo final
Finalização

O que é Redux?

Primeiro vamos entender que Redux é uma biblioteca de gerenciamento de estados de forma mais "global" do que os estados que temos convencionalmente no React por exemplo. Ele facilita com que diversas áreas da aplicação possam interagir entre si e centralizar sua informação.

Store, a raiz da nossa árvore de estados

No Redux, o que engloba todos esses estados globais nós chamamos de "store". Pra caso tu já tenha usado, é como um provider da Context API do React.

Aqui vou criar um objeto chamado store, para você tentar pegar uma ideia de como isso é representado.

// apenas uma representação visual pra assimilar melhor:
const store = {
  // por enquanto
  // ela está vazia
}

// exemplo real
import { configureStore } from '@reduxjs/toolkit'

const store = configureStore({
  // em breve vamos adicionar as propriedades aqui
})

Criar coleções usando Slices

Indo de fora pra dentro, na nossa store nós podemos criar "slices", que são coleções nas quais contém dados. Cada slice é nomeado, e esse nome é utilizado para acessar os seus dados mais pra frente. A mesma lógica serve para um objeto:

Vamos adicionar por exemplo um slice de configurações pra armazenar as coisas do nosso usuário:

// apenas uma representação visual pra assimilar melhor:
const store = {
  configuracoes: {
    tema: "escuro",
    notificacoes: true
  }
}

// exemplo real
import { createSlice } from '@reduxjs/toolkit';

const configuracoesSlice = createSlice({
  name: 'configuracoes',
  // este é o estado inicial, aqui você insere propriedades
  // que devem ser inicializadas com este slice logo de cara
  initialState: {
    tema: "claro",
    notificacoes: false
  }
});

Ler valores com Selector

Ok Ok, até aí tudo bem, mas como nós podemos ler o valor guardado no slice? É igual um objeto store.configuracoes.tema?
Não é tão simples assim, mas no contexto de React nós chamamos isso de Selector, que é quando você vai extrair um dado de dentro da store. No contexto JS isso é apenas uma leitura normal (selector pode acabar confundindo com querySelector).

Existe a forma "nativa" de se pegar o valor, e existe a forma usada na biblioteca "react-redux", vou deixar ambos os exemplos aqui:

Usando apenas o redux toolkit:

const tema = store.getState().configuracoes.tema

Usando react-redux:

import {
  useSelector,
  Provider
} from "react-redux"

/*
  OBS: Pra usar o React-Redux, você precisa primeiro
  adicionar o Provider dele à sua aplicação:
*/
const App = () => {
  return (
    <Provider store={store}>
      // ...seus componentes  
    </Provider>
  )
}

// Agora sim você pode ler o valor
const componente = () => {
  const tema = useSelector(state =>
    state.configuracoes.tema
  )
}

Criando a lógica para alterar valores com Reducers

Perfeito, já temos configurado a nossa store, nosso slice e conseguimos ler nossos dados... porém atualmente eles estão fixos, como podemos fazer para modificar os valores?

O que usamos para isso é o que chamamos de "Reducers", eles interagem com nossos slices para mudar os seus valores usando uma lógica definida por você. Inclusive tu pode até assimilar isso com o próprio useReducer do React, que também usa uma lógica customizada para definir um valor.

Vamos criar alguns reducers e atualizar a store para listar eles!

const configuracoesSlice = createSlice({
  // propriedades mencionadas acima...
  reducers: {
    // state é o slice atual
    // action.payload é o valor recebido
    setarTema: (state, action) => {
      state.tema = action.payload
    },
    setarNotificacoes: (state, action) => {
      state.notificacoes = action.payload
    }
  }
});

// Agora que temos os reducers criados, precisamos
// atualizar a store pra incluir eles!
const store = configureStore({
  reducer: configuracoesSlice.reducer
})

Alterando valores usando Actions

Com os reducers criados, podemos usá-los pra alterar os valores do nosso slice! Isso é o que vamos chamar de "Action".

A action executa um reducer e lhe fornece um resultado, daí você precisa executar um dispatch para que o resultado seja persistido (salvo) na nossa store.

Novamente, mostrarei a forma nativa / react-redux

Usando apenas redux toolkit:

// Use o dispatch para salvar a modificação
store.dispatch(
  // Use a action passando o novo valor
  configuracoesSlice.actions.setarTema("escuro")
)

Usando react-redux:

import { useDispatch } from "react-redux"

const Componente = () => {
  const dispatch = useDispatch(); 
  // O ato de salvar com dispatch continua igual, mas
  // ao invés de vir da store, ele vem do react-redux
  dispatch(
    configuracoesSlice.actions.setarTema("escuro")
  )
}

O fluxo final

Já cobrimos muitos tópicos da base de como se utilizar Redux Toolkit e também React Redux, mas queria te fazer uma pergunta: Acabou de notar que fizemos um CRUD?

Pois nós conseguimos:

Criar dados usando Slices
Ler os dados usando Selectors
Atualizar por meio de Reducers/Actions
E também dá pra deletar com reducers

Com essas informações agora conseguimos entender este diagrama que exemplifica o fluxo de dados do Redux:

Com os métodos ensinados neste artigo você deve conseguir se dar bem com o Redux, mas caso queira checar melhor a implementação feita neste artigo, vou disponibilizar ambos os arquivos finais para uma consulta mais fácil:

Arquivo final usando apenas redux toolkit: Gist
Arquivo final usando react-redux: Gist

Ambos estão fazendo a mesma coisa, porém em ambientes diferentes! O primeiro sendo um javascript comum, enquanto o segundo é num ambiente React.

Finalização

E é isso pessoal! Agora vocês já sabem o kit de sobrevivência pra Redux Toolkit e também React Redux!
Espero ter te ajudado de alguma forma, e sinta-se livre para deixar comentários de dúvidas ou feedback :)

Eu sempre falo de programação no Twitter, se quiser acompanhar meu conteúdo, welcome!

👋 Até uma próxima.

How to use serverless functions on Netlify (JS/TS)

Nícolas Gabriel — Mon, 20 Jun 2022 14:20:18 +0000

Repository created in this blog: netlify-functions-tutorial
When trying to use Serverless Functions on Netlify I really struggled to understand how it works and how to use it, even with videos, blogs... So taking in mind my mistakes and doubts I decided to create this article for you, developer, that may be interested but doesn't know how or even why using it.

So, first of all there's always a question...

Why should I use Netlify Functions?

Netlify is a website hosting service, but it only hosts our front-end, while our back-end must be hosted anywhere else. And that usually is what you do, but if I'm just planning to build a small project that would be like filling a cup of water with an ocean, there is no need for that.

Netlify Functions comes to solve this problem, you can keep your back and front-end together by using Functions that can be called just like a back-end api. And it makes the code easier to edit since it's all in one folder.

- Ok ok Nick, I understood, but how do I use that thing?
Good question, I'll divide the answer in two separate topics: How to implement it using Javascript and how to implement it using Typescript.

Serverless with Javascript

1. Install netlify-cli
Im presuming you already created a folder to your project, so before continuing we must install a package into it.
To install, execute this command in your terminal:

npm install netlify-cli --dev

2. Create a folder for your functions
So, to begin we need to create a folder for our functions, its name can be anything you want, but for the purpose of this blog I'll name mine as "functions".
If you already installed the netlify-cli package your folder must be like this:

> functions
> node-modules
package.json
package-lock.json

3. Create netlify.toml
Now we'll specify to Netlify where our functions are, and to do that, we need to create a file called netlify.toml.
Inside it you should write this code:

[build]
  functions = "./functions"

The "./functions" is the path to your functions folder, so remember to replace that if you put another name or in a different place than the root directory.

4. Set the redirects
The base url for acessing your functions is localhost:8888/.netlify/functions/functionname but that's a really long and unnecessary url, so I like to set up a redirect in my projects.
To do that you must create a file called _redirects(without extension) and put this code inside it:

/api/* /.netlify/functions/:splat 200

The /api/* will be our new url to acess the functions, meaning that now we can acess localhost:8888/api/functionname. The /.netlify/functions/:splat is the url it will be redirected to, replacing the :splat with the function you inserted. And 200 is just the status code that will be returned to the redirect.

5. Creating functions
This is the last step we need. The function I will create is just an example, but feel free to expand it however you want.

Let's create a file called "helloworld.js" inside our functions folder.
The first code we will insert is basically an export, this way Netlify can retrieve the function and execute it when you or someone acesses the api url.

module.exports.handler = async (event, context) => {
}

If you want and know how to it, you can change how you export it, but keep in mind you can't change the "handler" name, else the function will not be readable.

In our function my plan is to return a string with a message. If the user sends a "name" to our api, it will send "Hello name!", if not, then it sends "Hello world!". Pretty simple concept, let's do it!

We will pick the name from the query string parameters. They are specified after a "?" in the url, with a key=value.

I created a destructuring that picks elements from the event parameters, and then a variable "message" with a string that can be either "Hello name!" or "Hello world!"

module.exports.handler = async (event, context) => {
  const { name } = event.queryStringParameters
  const message = `Hello ${name || "world"}!`
}

Ok, now we need to send back the answer to our requisition, and to do that we only need to return an object, containing a body (The data we want to send back) and a status code.

module.exports.handler = async (event, context) => {
  const { name } = event.queryStringParameters
  const message = `Hello ${name || "world"}!`

  return {
    statusCode: 200,
    body: message
  }
}

Amazing! It's done! To test your API just run the command netlify dev in your terminal. It will say the functions that were loaded and also the server being used (in my case "localhost:8888")

If you go in your browser and enter the url localhost:8888/api/helloworld you should receive a string containing "hello world" just like this:

If you insert your name as a parameter in the url like this: localhost:8888/api/helloworld?name=Nick, it will return a different response:

To gather that data from the front-end you simply need to do a local request, an example would be fetch("/api/helloworld"), since both front and back run on the same host.

6. Bonus: Sending JSON's
For most cases you don't want to return just a string, instead you want to return a JSON, basically an object that can be readed by the browser. And the implementation is really straighforward, you just need to send your response body as a JSON.stringify().
Look at this example:

module.exports.handler = async (event, context) => {
  const { name } = event.queryStringParameters
  const message = `Hello ${name || "world"}!`

  return {
    statusCode: 200,
    body: JSON.stringify({ data: message })
  }
}

Instead of returning a string, this time we will return a JSON of an object containing a property called "data" that contains our message.
If we enter the url again...

Awesome, it worked! With Netlify Functions you can create anything you want, from token authorizations, database modifications...

Serverless with Typescript

The process is almost the same as Javascript, with the only exceptions being the function creation and some packages you need to install.
Along with the netlify-cli you installed before, you need to install @netlify-functions to get the function types. To do it, just run this in your terminal:

npm i @netlify/functions --dev

Now we'll adapt the previous Javascript function we created into a Typescript function.

// I imported the "Handler" type to use in the function
import { Handler } from "@netlify/functions";

// Created a variable called handler, with the type Handler
// and being an asynchronous function
const handler: Handler = async (event, context) => {
  // This code is almost the same, I only added a
  // nullish verification in the query parameters
  const { name } = event.queryStringParameters ?? {}
  const message = `Hello ${name || "world"}!`

  return {
    statusCode: 200,
    body: JSON.stringify({ data: message })
  }
}

// Instead of using module exports, we will
// use export { handler }, and just as javascript,
// handler is a reserved word, other names will not be readed
export { handler }

And that's it, every file you create will be a new endpoint.
I don't explained Typescript detailed as Javascript simply because the process is almost the same, and it would be kind of redundant to do so.

Ending

This took me some hours to write, I hope I helped you, but if there's still any questions, feel free to DM me on Twitter and I will try to help in your specific case :).
Also I don't write too many articles, but anyways, see ya!

Como criar um README dinâmico usando Javascript

Nícolas Gabriel — Wed, 23 Mar 2022 19:50:07 +0000

Olá! Você já pensou como seria poder gerar um README dinamicamente para aquele seu projeto do GitHub?
Eu já, mas nunca pensei em como funcionaria... até eu pesquisar se era possível e acabar me surpreendendo.

Depois de algumas pesquisas descobri uma feature do GitHub chamada "GitHub Actions", e ela consegue executar um código que você especificar, em diversas situações como: após um push, pull-request, e até mesmo em um intervalo especificado. Isso era justamente o que eu precisava, e com essa feature em mãos comecei a escrever meu Javascri- calma...

...Como isso é um guia, melhor eu documentar como fiz e como você também pode fazer e utilizar de diversas maneiras como quiser. Então vamos começar pelo começo:

1. Criando uma base

Gerar um markdown direto do Javascript não é tão prático assim, pois para visualizar você precisaria executar o Javascript, e repetir isso para cada mudança definitivamente não é viável a longo prazo (vamos ignorar o nodemon). Por isso eu recomendo criar um arquivo base em markdown, e modificá-lo usando Javascript, ao invés de gerá-lo por completo.

Como exemplo, vou criar um novo repositório no GitHub e disponibilizarei ao final do blog. Então vamos começar por essa base em markdown (que nomeei como "readme_base"), definindo nela as informações que serão fixas, e quais serão geradas:

# %{titulo}
Eu coloquei o titulo dentro de `%{}` apenas para evitar que
haja alguma ambiguidade com textos comuns.

Todas as partes desta base podem ser manipuladas e modificadas,
por exemplo aqui eu irei inserir uma lista de nomes:
%{listaDeNomes}}

2. Modificando a base

Para testamos se está tudo funcionando, vamos criar um arquivo em Javascript, no qual nomearei como "index.js", para modificar a base:

/* o fs é quem irá ler o arquivo e gerar um novo,
ele vem por padrão no node, então não se preocupe */
const fs = require('fs')

// esta parte lê o arquivo "README_BASE"
fs.readFile('README_BASE.md', 'utf-8', (err, data) => {
    if (err) {
        throw err;
    }

/* aqui é onde acontecem as substituições, por exemplo
substituindo %{titulo} por "Dynamic Readme" */
    const substituicoes = {
        titulo: 'Dynamic Readme',
        listaDeNomes: `- Carlos\n- Ana\n- Sérgio`
    }

/* aqui é o que verifica e executa as substituições, um
regex bem simples com object literals, não precisa mexer aqui */
    const modificado = data
        .replace(
            /%{.*}/gm,
            e => substituicoes?.[e.slice(2, -1)] || e
        )

/* após ter feito as mudanças ele cria um arquivo
chamado "README.md" com a nova versão */
    fs.writeFile('README.md', modificado, 'utf-8', (err) => {
        if (err) {
            throw err;
        }
        console.log('✔ Processo finalizado!');
    });
});

Este código será executado via node, então sinta-se livre para adicionar o que quiser, sejam pacotes, requisições em apis, gerar imagens, está em suas mãos.

3. Automatizando o processo

"Mas isso apenas gerou o arquivo pois fui eu quem iniciou o javascript, então para executar esse processo automaticamente eu precisaria de um host?"

Felizmente não, pois no caso do GitHub ele disponibiliza o github actions no qual eu havia falado. Ela permite que o processo rode em diversas circunstâncias, e no caso deste exemplo usarei o schedule que permite que o código seja executado a cada intervalo especificado.

Para isso iremos criar uma pasta chamada .github, e dentro dela uma outra chamada workflows, com um arquivo main.yaml.
Resumindo: .github/workflows/main.yaml.

No arquivo main.yaml é onde diremos ao github quando, como e o quê rodar.

# Nome do processo
name: Update automático

on:
  schedule:
    # cron é o "intervalo" de execução, recomendo usar
    # o site crontab.guru para lhe ajudar a definir.
    # nesse caso aqui, ele irá rodar a cada 10 minutos.
    - cron: '*/10 * * * *'

# Aqui vem os passos que a ação segue
jobs:
  build:
    # Inicia uma máquina virtual ubuntu
    runs-on: ubuntu-latest

    # Checa o código atual do repositório
    steps:
    - name: Checkout repo
      uses: actions/checkout@v2

    # Instala o node na versão 16.10
    - name: Use Node.js
      uses: actions/setup-node@v1
      with:
        node-version: 16.10
    - run: npm install
    - run: npm run build --if-present
      env:
        CI: true

    # Aqui em index.js você insere
    # o nome do seu arquivo javascript
    - name: Roda o arquivo
      run: |-
        node index.js
        cat README.md

    # E no final commita e faz um push caso haja alguma diferença
    # comparada ao código atual do repositório
    - name: Commit e push
      run: |-
        git diff
        git config --global user.email "bot-readme@example.com"
        git config --global user.name "bot automático"
        git add -A
        git commit -m "Arquivo atualizado!" || exit 0
        git push

Com isso feito, sua pasta/repositório deve estar mais ou menos assim:

> .github
  > workflows
    > main.yaml
> index.js
> readme_base.md
> README.md (gerado)

Se estiver assim, perfeito, tá tudo certo. Casos os nomes estejam diferentes ou não tenha gerado o README ainda, tá tudo bem também.

Mas só avisando que caso você mande tudo pro GitHub, e em 10 minutos seu repositório não atualize, calma. O GitHub Actions nem sempre é imediato, algumas vezes leva mais tempo do que o especificado. Por exemplo no meu teste desse repositório, apesar de eu especificar 10 minutos levou 25 😅.

Você pode acompanhar as actions por aqui, sempre que uma for executada ela irá aparecer:

E falando no repositório, aqui está o link pra ele: Dynamic Readme. Se quiser pode fazer um fork e modificar ou seguir este tutorial, como preferir.

4. O final

Opa! Gostou do blog? É o meu primeiro, mas tentei deixar ele completo e simples de se entender, espero ter conseguido ^^.

E não pensa que dá pra fazer só essas coisinhas de trocar texto por texto não! No meu readme eu fiz uma seção que atualiza mostrando minhas atividades mais recentes, e até gera uma imagem utilizando a api do github para pegar um seguidor aleatório meu!

Tô ansioso pra ver o que vocês também conseguem criar.
Me marca no Twitter caso faça algo bacana com isso. 'Inté!