DEV Community: Lucas de Medeiros

Minha experiência migrando projetos para estrutura de Monorepo com lerna.js

Lucas de Medeiros — Mon, 14 Sep 2020 15:26:32 +0000

Recentemente, adotei a estrutura de Monorepo em um de meus projetos pessoais, o Game Slot. Alguns motivos que me levaram a tomar essa decisão envolvem:

o escopo bem fechado e definido, sendo uma aplicação React, armazenada em um repositório chamado game-slot, que se comunica com uma API feita em NodeJS, antes no repositório game-slot-api;
features que realizavam mudanças no backend e no frontend da aplicação agora podem ser resolvidas em uma única Pull Request para apenas um repositório;
maior praticidade de lidar com configurações e dependências.

A princípio, fazer isso me pareceu uma tarefa simples, mas fui me deparando com alguns aspectos que irei discorrer ao longo deste artigo que acabaram tornando o processo um pouquinho menos trivial.

Versionamento

Inicialmente, pensei em apenas copiar todo o código da API que existia no repositório game-slot-api e colar dentro de uma pasta backend/ no game-slot, repositório que consistiria o monorepo, e também mover o código React para uma pasta frontend/. Isso transformaria a estrutura do repo em algo parecido com isso:

root/
├── backend/
│   ├── .eslintrc
│   ├── package.json
│   └── ...
├── frontend/
│   ├── .eslintrc
│   ├── package.json
│   └── ...
├── .gitignore
└── README.md

Porém, simplesmente copiar e colar o código da API dentro do monorepo significaria perder todos os commits que já tinham sido feitos no game-slot-api e apenas criaria um commit cheio de alterações.

Você pode até pensar que a perda desse histórico pode não se tornar algo crítico ou até não ser algo relevante para se preocupar. Eu concordo que, para o meu caso, não iria ter tanto impacto, mas fazer isso definitivamente não é uma boa prática, principalmente se você toma essa decisão em um cenário em que vários projetos e pacotes que já estão em produção e sendo utilizados por uma quantidade considerável de usuários são afetados.

Incomodado com essa situação, pesquisei sobre alguma forma de manter o histórico de um repositório em um monorepo, e descobri que utilizar o lerna poderia tornar minha vida muito mais fácil, já que é uma ferramenta feita especificamente para gerenciar projetos em JavaScript feitos em múltiplos pacotes, como sua própria descrição diz. Um de seus comandos é o lerna import, que importa o projeto (ou pacote) de um repositório, preservando os autores, as mensagens e datas dos commits.

Então, iniciei um novo projeto lerna dentro da pasta raiz do repositório game-slot com npx lerna init, e rodei o seguinte comando:

npx lerna import ~/game-slot-api --dest=backend

Dependendo do tamanho e organização do projeto que você tentar importar, esse comando pode causar alguns problemas. Você pode acessar a documentação do comando import e verificar algumas flags adicionais que possam auxiliar no processo.

Isso gerou uma pasta packages/, que contém todos os pacotes do monorepo, e mandou para lá o novo pacote backend com todos os commits existentes no repositório antigo automagicamente! Depois, movi o código React já existente para packages/frontend. Também renomeei a pasta packages/ para game-slot/ e fiz as modificações necessárias no arquivo lerna.json e package.json a fim de poder chamar meus dois "pacotes" de @game-slot/frontend e @game-slot/backend.

Dependências

Agora eu tinha meus dois projetos importados dentro de um único repositório preservando os commits de todos, do jeito que eu queria! Mas depois, percebi que não estava tirando proveito de uma das melhores vantagens de se usar Monorepo: facilidade no gerenciamento de dependências.

Existiam várias dependências que eram compartilhadas entre os dois projetos, como o node-fetch, eslint, entre outras, que estavam nos arquivos package.json de ambos backend e frontend.

Depois de uma análise de dependências que apareciam nos dois pacotes e para cada uma encontrada, adicionei como dependência global do projeto, rodando o seguinte comando na pasta raiz:

npx lerna add <nome-do-pacote>

Novamente, para ter acesso a flags e opções a mais do comando add, verifique sua documentação

Isso me possibilitou algo que achei bastante vantajoso: usar a mesma versão de cada uma das dependências em ambos os projetos e uma maior praticidade para gerenciá-las futuramente. Lindo, né?

Deploys

Com os dois projetos configurados e com um fácil gerenciamento de dependências, agora foi a vez de resolver o problema do deploy, tanto do backend quanto do frontend. Eu já estava utilizando o Heroku para deploy da API do Game Slot e o Netlify para o sistema web com React, e acabei encontrando soluções pesquisando por casos similares de problemas que outras pessoas já passaram e resolveram.

Para o frontend, eu utilizei o guia do Netlify para configurações comuns de build para variados estilos de projeto, incluindo monorepo.
Já no backend, eu segui este tutorial para automatizar os deploys no Heroku em uma estrutura de monorepo, fazendo adaptações para o meu caso.

Fluxo de desenvolvimento

O fluxo de desenvolvimento se manteve quase o mesmo, qualquer pessoa pode criar uma issue e atribuí-la a mim ou a ela mesma para que seja resolvida. Então, é aberta uma PR que irá passar pelo processo de review. A única mudança é que agora o repositório também receberá issues e contribuições de backend também.

Para desenvolver, primeiramente deve-se configurar as variáveis de ambiente necessárias, explicadas no README de cada um dos projetos, e em seguida rodar os comandos abaixo para rodar backend e frontend:

yarn bootstrap # instalação de todos os pacotes e dependências do projeto
yarn start:backend # rodar o backend em modo de desenvolvimento
yarn start:frontend # rodar o frontend em modo de desenvolvimento

# ou opcionalmente

npm run bootstrap # instalação de todos os pacotes e dependências do projeto
npm run start:backend # rodar o backend em modo de desenvolvimento
npm run start:frontend # rodar o frontend em modo de desenvolvimento

Conclusão

Algumas motivações citadas que me levaram a aplicar Monorepo no meu projeto podem variar facilmente de um contexto para outro. Dando uma boa pesquisada, você vai encontrar argumentos a favor e contra a sua utilização, e também debates bem acalorados em fóruns e discussões por aí.

É bom citar que o meu caso consiste em um projeto pessoal de faculdade em que eu apliquei um pouco mais de esforço, e a única pessoa realmente responsável pelo desenvolvimento desse código sou eu, não existe um time. Ou seja, obviamente isso pode não funcionar em times com organizações e tamanhos diferentes. Adotar ou não esse padrão requer muito debate, e todos os integrantes do time devem ter espaço para opinar!

Dito isso, espero que tenham gostado desse artigo, e que tenha sido útil de alguma forma 😄.

Criar um App com a Slack Web API para impulsionar seu time

Lucas de Medeiros — Mon, 11 May 2020 15:33:11 +0000

Ter um workspace no Slack para seu time/empresa é uma ótima opção para tornar a comunicação interna mais profissional que outras plataformas de mensagens de texto instantâneas e sem a "burocracia" das trocas de e-mail. Para atingir esse objetivo, o Slack disponibiliza uma infinidade de features, como ampla capacidade de customização, praticidade para compartilhamento de arquivos, snippets, chamadas de voz, entre outras. E ainda tem um plus: também é disponibilizada uma API muito completa para desenvolvimento de aplicações incríveis!

Como uma aplicação slack poderia ser útil?

Com uma aplicação customizada, você tem ainda mais opções para expandir os benefícios do seu workspace Slack, como criação de bots e interações automáticas para aumentar a praticidade e comodidade, criação de comandos slash, criar ferramentas internas, automatizar a gerência do seu workspace, de canais, e muito mais. Você pode se aprofundar e ler mais sobre Slack Apps aqui.

Vamos agora criar uma pequena aplicação capaz de lidar com comandos slash customizados e realizar ações no workspace. Todo o código produzido aqui está disponível no Github.

Etapa 1: Criação de um workspace

O primeiro passo a ser tomado é garantir que você tenha privilégios de administrador em um workspace Slack. Se você ainda não obedece essa condição em nenhum dos workspaces em que você está cadastrado, acesse a página inicial do Slack, selecione a opção Criar um novo workspace e siga o fluxo de criação.

Preencha as informações restantes, e seu workspace estará criado! Você será redirecionado automaticamente ao término do processo de criação. Lá, conclua a configuração de algumas informações (como sua senha de acesso) e, caso queira, faça o pequeno tutorial de utilização da plataforma.

Etapa 2: Criando o Slack App

Acessando a página Applications da API do Slack, você verá um botão em cima com a opção "Create New App". Ao selecioná-la, você deverá informar o nome da sua aplicação (neste exemplo, usarei Slack App Example) e o seu workspace de desenvolvimento, que é o workspace em que você usará para testar sua aplicação enquanto estiver em modo de desenvolvimento. Futuramente, você pode distribuí-la e permitir que seja instalada em outros workspaces.

Se tudo ocorreu bem até agora, você será redirecionado para a tela de informações básicas do seu app:

No menu lateral, selecione App Home, e lá você deve clicar no botão Review Scopes to Add:

Na seção Bot Token Scopes, você deve, basicamente, definir que permissões seu app/bot terá no workspace. Para ler mais sobre permissões e escopos do Slack, acesse este link.

As permissões e escopos necessárias para a aplicação que vamos desenvolver são:

chat:write
Send messages as Slack App Example

chat:write.public
Send messages to channels @slack_app_example isn't a member of

commands
Add shortcuts and/or slash commands that people can use

im:read
View basic information about direct messages that Slack App Example has been added to

Após selecionar as permissões, ao voltar para a App Home no menu lateral, veremos uma mudança na página. Agora, nosso app tem um Bot Token, que permite que ele se comunique e realize determinadas ações no nosso workspace baseadas nas permissões que definimos anteriormente. Você pode customizar o nome que o nosso bot terá e decidir se quer que ele apareça sempre online.

Ao terminar a configuração, você deve ir para a página Install App, também acessível pelo menu lateral, e instalar sua aplicação no workspace.

Pronto, nosso app está criado e instalado no workspace!

Claro, ele ainda não é magicamente capaz de se comunicar no workspace do jeito que queremos, nem de disponibilizar nossos comandos slash automaticamente, mas vamos torná-lo capaz disso nas próximas etapas. Perceba que na página agora tem um Bot User OAuth Access Token, com um prefixo xoxb-. Spoiler: precisaremos dele.

Etapa 3: Criando um pequeno servidor com Express

Para lidar com as requisições dos nossos comandos slash, precisamos criar uma API própria. Para que isso seja feito da maneira mais simples possível neste tutorial, vou criar um servidor básico com node e express. Caso ainda não esteja familiarizado com essas tecnologias, siga esse tutorial para configurar seu ambiente com NodeJS e o gerenciador de dependências npm (você também pode querer instalar o yarn). Para ter acesso à mais informações do express, você pode acessar a documentação a partir de sua página inicial.

Para iniciar o desenvolvimento, abra o terminal e digite:

mkdir slack_app_example
cd slack_app_example
npm init -y

Isso vai iniciar um projeto node dentro da pasta slack_app_example, a raiz do nosso projeto. Agora vamos criar um diretório chamado src e lá estarão o arquivo index.js e as pastas routes, services e controllers. Assim será definida a estrutura do nosso projeto. No terminal, instale o express, cors, @slack/web-api e, caso prefira, também o nodemon em modo dev para facilitar o desenvolvimento com reload automático:

npm i express cors @slack/web-api
npm i -D nodemon

No arquivo package.json, adicione os seguintes scripts:

"scripts": {
    "start": "node src/index.js",
    "dev": "nodemon src/index.js"
}

Agora, no arquivo index.js, inicie seu servidor express:

const express = require("express");
const cors = require("cors");
const app = express();
const routes = require("./routes");

const SERVER_PORT = 5500;

app
  .use(cors())
  .use(express.json())
  .use(express.urlencoded({ extended: false }))
  .use(routes)
  .listen(SERVER_PORT, () => {
    console.log(`Server listening on port ${SERVER_PORT}`);
  });

Agora, vamos criar a nossa primeira rota, que será capaz de receber um comando slash /hello de um usuário do workspace, e deve mandar uma mensagem "Olá, mundo!" para um canal de texto do workspace, visível para todos.

Dentro das pastas routes, controllers e services, vamos criar um arquivo chamado slack.js:

Em services/slack.js, estará nossa instância da WebAPI do Slack, e usaremos os métodos dela. Você precisará setar aqui aquele Bot User OAuth Access Token que citamos na etapa anterior.

Cuidado: essa informação é sensível, e caso seu código seja open-source, não faça um commit publicamente contendo este token, ou seu workspace estará vulnerável a utilizações indesejadas de terceiros. Você pode fazer uma configuração de variáveis de ambiente no seu projeto para protegê-lo.

// src/services/slack.js
const { WebClient } = require("@slack/web-api");

const BOT_USER_TOKEN = "YOUR-TOKEN-HERE";
const web = new WebClient(BOT_USER_TOKEN);

class SlackService {
  postTextMessage(messageArguments) {
    web.chat.postMessage(messageArguments);
  }
}

module.exports = new SlackService();

Com isso, temos um método genérico no serviço de Slack para enviar mensagens para algum canal ou mensagem direta, recebendo as opções pelo parâmetro messageArguments.

Agora, no controlador, vamos chamar esse método que acabamos de definir para que seja enviada uma mensagem com texto "Olá, mundo!" para o canal #general (como a configuração do meu workspace está em português, o nome fica #geral):

// src/controllers/slack.js
const slackService = require("../services/slack");

class SlackController {
  hello(req, res) {
    slackService.postTextMessage({
      channel: "geral", // Canal de sua preferência
      text: "Olá, mundo!",
    });

    res.status(200).json({ message: "Mensagem enviada com sucesso!" });
  }
}

module.exports = new SlackController();

No arquivo de configuração das rotas routes/slack.js, vamos expor esse endpoint para requisições POST (o Slack enviará requisições POST nos comandos cadastrados no seu app).

// src/routes/slack.js
const express = require("express");
const { hello } = require("../controllers/slack");

const routes = express.Router();

routes.post("/hello", hello);

module.exports = routes;

Agora, para fazer nossa aplicação funcionar, devemos criar um index.js dentro da pasta routes, chamando a rota que acabamos de criar.

const express = require("express");
const slackRoutes = require("./slack");

const routes = express.Router();

routes.use("/slack", slackRoutes);

module.exports = routes;

Ao rodar o servidor com npm run dev (iniciando em modo de desenvolvimento com reload automático a cada mudança que fizer no código, caso tenha optado por utilizar o nodemon) ou npm start, a aplicação deve imprimir a seguinte mensagem no terminal:

Server listening on port 5500

Etapa 4: Expondo seu servidor com ngrok

Como o Slack não permite URL's locais, você pode expor sua URL de desenvolvimento local para não precisar hospedar sua aplicação apenas para testar. Crie uma conta no site do ngrok e faça o download do seu .zip.

Uma vez que o ngrok estiver instalado e configurado seguindo os passos listados na sua página, certifique-se de que seu servidor também está rodando em uma aba de seu terminal, inicie outra sessão no terminal e rode o seguinte comando:

ngrok http <PORT> --region=eu

Substituindo <PORT> pela porta utilizada pelo seu servidor, nesse caso, a porta 5500, como foi definido no arquivo index.js na pasta raiz do projeto. Copie a URL que será mostrada na tela do terminal, deve ser algo como https://s0m3th1ng.ngrok.io, que aparecerá em alguma das linhas que serão mostradas após rodar o comando (recomendo escolher a opção com https). Essa URL será o prefixo de todas as outras URL's que serão utilizadas ao decorrer deste tutorial, e para fins didáticos vou chamá-la de :path:.

Etapa 5: Conectando o Slack App com a API

De volta à página de informações básicas de seu App, acesse a opção Slash Commands no menu lateral. Lá, você deve clicar na opção Create New Command. Defina o comando como /hello, a Request URL deve ser :path:/slack/hello, que é o endpoint de nossa API que acabamos de criar, e caso queira, coloque uma descrição do comando e algumas dicas de uso.

Após clicar em Save, o seu novo comando personalizado estará disponível para uso no seu workspace!

Conclusão

Este foi um pequeno exemplo de como podemos criar um Slack App e conectá-lo com uma API interna para criar comandos customizados. Você pode expandir seus horizontes e criar modais e componentes interativos para facilitar a experiência ao chamar os comandos, por exemplo. Leia mais aqui sobre interatividade com comandos slash. E com Slack Apps, você pode fazer também muito mais!

Espero que tenham gostado desse tutorial, e que tenha sido útil de alguma forma 😄.

Contribuindo para projetos open source com GitHub

Lucas de Medeiros — Sat, 03 Aug 2019 22:04:45 +0000

Criado em 2008 e bem aperfeiçoado desde então, o GitHub não apenas é, atualmente, o mais conhecido serviço web que oferece diversas funcionalidades aplicadas ao Git para hospedagem e versionamento de código-fonte, como também é um grande impulsionador da iniciativa open source e do trabalho em equipe. Cada vez mais, a plataforma tem adquirido uma cara de rede social, visando engajar mais pessoas em relação a contribuição em projetos de código aberto, participação em suas respectivas comunidades, além de dar mais visibilidade a tais projetos. Isso foi possível devido a inúmeras funcionalidades adotadas e implementadas pelo GitHub a fim de atingir esses objetivos, e algumas delas serão introduzidas nesse post.

Screenshot da página inicial do GitHub atualmente.

Comunidade open source

Antes de prosseguir no post, é preciso deixar claro um conceito para comunidade open source. Uma comunidade é formada por Users, Contributors e Mantainers. O grupo de usuários (users) é composto por pessoas que vão utilizar um sistema que está sendo desenvolvido em código aberto, e são ativas na comunidade reportando possíveis bugs no desenvolvimento e dando sugestões de melhoria e de novas features. Além disso, dependendo da licença utilizada pelo projeto, usuários podem fazer modificações livremente, por exemplo, alterar partes do sistema para uso pessoal, utilização como componente em outro projeto e até comercializá-lo. Para saber o que pode e o que não pode fazer, é sempre bom checar o arquivo LICENSE do repositório e verificar as permissões.

O que diferencia um usuário de um contribuidor (contributor) é a efetividade para a organização que encabeça o projeto. O contribuidor levanta discussões mais profundas e úteis para a organização, altera diretamente o código e faz requisições de anexação do seu conteúdo ao original. Os motivos que levam alguém a contribuir com uma organização podem ser diversos: o desejo de melhorar aplicações que ele mesmo utiliza, identificação com a organização, aplicação prática de conhecimentos acerca de uma tecnologia, ganhar visibilidade com contribuições úteis e reais, entre outros. Esse é o espírito do open source.

Vale ressaltar dois pontos: primeiro, o contribuidor não está vinculado à organização. Isso significa que alguém pode aparecer repentinamente para contribuir e, da mesma forma, pode parar a qualquer momento. Segundo, é muito comum que a organização estabeleça regras para contribuição e é importantíssimo que o contribuidor esteja por dentro de todas elas antes de começar. Por isso, ele deve ler bem o que há nos arquivos README.md, CONTRIBUTING.md e CODE_OF_CONDUCT.md, caso existam.

Por fim, temos os mantenedores (maintainers). Estes são os administradores responsáveis por manter o projeto "vivo" e atualizado, pois eles são membros efetivos da organização, e têm privilégios de administrador no repositório do GitHub. Eles devem estar por dentro das discussões que envolvem o projeto, fazer correções de bugs, implementar features, revisar requisições de contribuidores e são os responsáveis por manter o projeto organizado: disposição dos arquivos e diretórios no repositório, alocação de tasks, categorização dos tópicos das discussões, entre outras obrigações.

Agora, com o conceito de comunidades open source mais claro, podemos começar a falar sobre as maneiras que o GitHub encontrou para impulsioná-las e como você pode utilizar a plataforma para fazer parte de uma.

Stars e forks

Ao acessar um repositório público no GitHub, você pode dar uma star, feature similar às "curtidas" das redes sociais mais famosas, e também pode fazer um fork, que consiste na criação de uma cópia independente deste repositório, que contém todo o seu conteúdo, para a sua conta de usuário no GitHub. Na tela inicial, são mostradas as stars e forks que as pessoas que você segue dão em repositórios públicos, uma funcionalidade que tem por objetivo a ampliação do alcance dos projetos open source.

Pull Requests (PR's) e Issues

A partir de um fork, quando terminar de fazer as alterações que julgar necessárias, você pode submeter uma requisição de anexação do seu conteúdo modificado ao conteúdo original do repositório escolhido. Essa requisição é a pull request, a forma mais característica de contribuição a um projeto na plataforma, que será revisada por um maintainer. Observe abaixo o processo para abrir uma nova PR:

Também é importante ter em mente que uma contribuição para um projeto open source vai além de modificações diretas no código-fonte. Um feedback, alerta de bugs no software que está sendo desenvolvido, discussões a respeito de um novo passo que pode ser tomado em prol do projeto, troca de ideias e sugestões podem impactar profundamente no futuro do projeto e até da organização. Por isso, é extremamente importante que uma organização fique sempre atenta ao que sua comunidade tem a dizer.

Tendo em vista esse contexto, o GitHub disponibiliza as issues, um espaço que pode ser utilizado tanto por usuários comuns quanto por maintainers, para a finalidade de todos os pontos citados e também para priorização e organização das tarefas a serem desenvolvidas. Observe abaixo o processo para abrir uma nova issue:

Descobrindo repositórios e contribuindo

É muito comum que não se saiba muito bem por onde começar a contribuir no início da "aventura" pelo mundo open source. Para minimizar essa dificuldade, você pode visualizar a seção discover repositories, que traz recomendações muito interessantes de projetos, baseadas em outros repositórios que você deu star, em pessoas que você segue, em tecnologias recentes que você trabalhou e também em popularidade do projeto, os trendings.

Depois de localizar um projeto com o qual se identificou, você pode explorar o arquivo README.md a fim de obter informações a respeito do que se trata o projeto, com quais tecnologias ele trabalha, como rodar na sua máquina, link da página principal, entre outras. É importante ter em mente que a disponibilidade dessas informações nesse arquivo depende bastante da organização que criou o projeto, e como ela organiza suas atividades.

Depois de se informar sobre esse projeto e decidir que quer contribuir para ele, um ótimo ponto de partida é olhar as issues abertas e verificar as suas labels, que consistem em uma forma de categorização e priorização de issues e PR's para ajudar na organização do trabalho. A fim de te deixar mais confortável para começar a contribuir, é interessante que a procura inicial seja por labels de good first issue, easy e help wanted, por exemplo. Vale ressaltar também que essa categorização de issues e PR's por labels também depende de como a organização "se organiza".

Screenshot da página de issues do Tamburetei com suas labels.

Você pode contribuir com novas ideias nas discussões a respeito de alguma das issues ou fazer uma PR que a resolva. Posteriormente, quando estiver mais à vontade na organização, você pode abrir novas issues ou tentar resolver algumas mais complexas.

Explorando o GitHub

Outra forma de ter acesso a novidades de projetos open source é acessando o Explore, uma página do GitHub que além de mostrar projetos recomendados, como mostrado no tópico anterior, também possibilita uma conexão entre as comunidades desses projetos. Você pode explorar conteúdos de curadores, buscar projetos por tópicos e labels, ter acesso a informações de posts, artigos, eventos e meetups relacionados com as tecnologias recomendadas para você, entre outras informações.

Essas são algumas das principais maneiras que o GitHub encontrou para dar visibilidade a projetos de código aberto e fomentar a colaboração dos desenvolvedores para eles. Você pode se aprofundar mais a respeito do funcionamento do Git e do GitHub e obter informações mais técnicas neste outro post, e começar também a apoiar o open source agora mesmo!

Muito obrigado pela leitura! Fique atento: em breve, teremos novos artigos de contribuidores do OpenDevUFCG aqui no dev.to. Acompanhe o OpenDevUFCG no Twitter, no Instagram e, claro, no GitHub.