DEV Community: Diego Chueri

A IA está sabotando sua evolução? Velocidade de Entrega vs Profundidade de Aprendizado

Diego Chueri — Fri, 21 Nov 2025 09:43:18 +0000

Você entregou a feature em tempo recorde. O código está organizado, tipado e passou nos testes. O PR foi aprovado. Você se sente invencível por ter finalizado sua sprint sem grandes esforços.

Mas seja sincero com você mesmo por um segundo: se o Cursor, Copilot ou outra IA qualquer que você tenha utilizado durante o desenvolvimento tivesse ficado offline hoje, você teria conseguido escrever aquela solução de manipulação de streams complexa? Ou aquela regex de validação? Ou a configuração do Dockerfile?

Estamos vivendo a "Era de Ouro" da produtividade no desenvolvimento. Ferramentas de IA não são apenas assistentes, elas são catalisadores de força. Elas nos permitem pular a parte chata, o boilerplate, a sintaxe que esquecemos. Mas existe um efeito colateral silencioso acontecendo, afetando desde estagiários até desenvolvedores experientes: a terceirização do "Productive Struggle" (Esforço Produtivo).

A neurociência e a pedagogia concordam em um ponto: aprendizado profundo requer atrito. Requer aquele momento de frustração, de olhar para a documentação, de tentar e errar, de construir o modelo mental do problema na sua cabeça.

Quando a IA nos dá a resposta "ideal" instantaneamente, ganhamos velocidade, mas perdemos o aprendizado, a prática. Estamos construindo softwares cada vez mais complexos e robustos, mas será que estamos nos tornando desenvolvedores melhores? Ou estamos caminhando para um futuro de "Seniores de Vitrine", que sabem orquestrar prompts, mas travam quando precisam debugar o que a máquina escreveu?

Neste artigo, não vou pedir para você largar a IA, isso seria loucura. Mas vamos conversar sobre como usá-la sem atrofiar seu pensamento crítico e sua evolução técnica.

A Ciência do Aprendizado: Por que o "difícil" é necessário

Quando você usa o GPS para ir a um lugar novo, você chega lá rápido, mas reparou que não faz ideia de como voltar sem ele? Por outro lado, quando você se perde, pede referências pelo caminho, usa um mapa, erra uma rua e finalmente chega... você nunca mais esquece o caminho.

Na psicologia cognitiva, isso tem nome: "Dificuldades Desejáveis" (Desirable Difficulties).

O pesquisador Robert Bjork demonstrou que introduzir certas dificuldades no processo de aprendizado como o esforço de tentar lembrar algo ou resolver um problema sem ajuda imediata é fundamental para a retenção a longo prazo. O aprendizado real não acontece quando lemos a resposta certa, ele acontece no esforço cognitivo de chegar até ela.

Esse é o conceito de "Productive Struggle".

Quando delegamos todo o "trabalho sujo" de pensar na sintaxe, na estrutura e na lógica para a IA, estamos removendo o atrito. Estamos transformando o desenvolvimento de software em uma atividade passiva (como seguir o GPS) em vez de ativa (como navegar pelo terreno).

O resultado? O código vai para produção, mas o conhecimento não é absorvido.

A Armadilha da Velocidade vs. Profundidade

Isso nos leva a um problema moderno: a Ilusão de Competência.

Antigamente, um desenvolvedor travado em um problema passava horas lendo documentação, entendendo o ciclo de vida do React ou a estrutura de memória do Rust. Hoje, o Copilot resolve isso em segundos.

Isso cria dois tipos de riscos, não só para iniciantes, mas também para desenvolvedores experientes:

O Platô da "Caixa Preta": Você sabe que funciona, mas não sabe como funciona. Caso se depare com uma leaky abstraction ou com um bug obscuro, você não tem o mínimo modelo mental necessário para corrigir, porque não construiu a base.
A Perda do Julgamento Crítico: Quando a IA sugere um código elegante, nosso viés é aceitar. Esquecemos de fazer as perguntas de arquitetura: Isso escala? Isso adiciona uma dependência desnecessária? Isso é seguro?

Estamos trocando profundidade de entendimento por velocidade de implementação. E em um mercado que cada vez mais valoriza a capacidade de resolver problemas complexos (já que os simples a IA resolve), essa é uma troca perigosa para a sua carreira.

Estratégias para manter o controle

1 - Para o Desenvolvedor (Autodefesa Contra a Atrofia)

Se não podemos parar de usar a IA, temos que mudar a forma como usamos. A meta é garantir que o processo de pensamento permaneça humano.

A Regra do "AI Sandwich":
- Fatia 1 (Você): Tente resolver o problema por 15 a 30 minutos. Sinta o struggle. Entenda a dor, o erro, a documentação.
- O Recheio (IA): Só então, use a IA.
- Fatia 2 (Você): Não aceite o código. Use-o como referência. Sua tarefa agora é criticar, refatorar e explicar o código da IA, linha por linha, como se fosse um PR de um estagiário.
- A Lição: Você usou a IA para validar e acelerar sua ideia, não para gerar ou evitar seu pensamento.
Evite a Abstração Prematura: Use a IA para gerar boilerplates, configurações, testes básicos. Nunca para criar a lógica do core da sua aplicação ou as decisões de arquitetura. É aqui que o seu julgamento de trade-offs é insubstituível.
A Testemunha do Erro: Quando a IA gera um código que falha, não peça para ela corrigir. Tente debugar e entender o porquê ela errou primeiro. Seu cérebro aprende muito mais ao consertar o erro de um modelo do que ao receber a correção final.

2 - Para o Líder Técnico (Cultura de Questionamento)

A responsabilidade de manter o padrão de engenharia agora recai sobre quem revisa o código.

O Code Review Socrático (O "Porquê" em vez do "O Quê"):
- Pare de comentar: "Use map em vez de forEach." (Isso é sintaxe, a IA resolve).
- Comece a perguntar: "Quais são os trade-offs de performance e manutenção ao usar essa biblioteca, em comparação com a solução nativa? Por que você descartou o padrão Y?"
- O foco deve ser na decisão arquitetural, forçando o desenvolvedor a articular o processo de pensamento, mesmo que a IA tenha escrito o código.
O Desafio Intencional (Voltar ao Básico): Ocasionalmente, atribua tarefas que exijam o conhecimento fundamental e proíba (ou desincentive fortemente) o uso de LLMs. Exemplo: "Implemente um cache LRU do zero sem usar bibliotecas de terceiros." Isso garante que o músculo mental não atrofie.
Valorização da Dúvida: Crie uma cultura onde perguntar sobre trade-offs e incertezas seja valorizado. Apenas uma LLM não pode te dar um aumento de salário, a sua capacidade de avaliar riscos e comunicar decisões difíceis sim.

O Futuro da Maestria: Decisão Humana, Execução Assistida

Chegamos ao ponto crucial: A IA não está roubando nosso trabalho, ela está nos forçando a elevar o nível dele.

Nossas ferramentas nos tornaram mais rápidos, mas não podemos deixar que elas nos tornem rasos. O valor do desenvolvedor Sênior nunca esteve em digitar código mais rápido, mas sim na capacidade de tomar decisões difíceis, de balancear trade-offs (como abordamos em meus artigos anteriores) e de entender o custo oculto das abstrações.

Se a IA assume o "O Quê" (o código a ser escrito), nós devemos dominar o "O Porquê" (a decisão de arquitetura). Lembre-se: o esforço de hoje é o conhecimento fundamental de amanhã. O "Productive Struggle" não é uma punição, é o processo de criação de valor no seu cérebro.

O desenvolvedor de sucesso na era da IA será aquele que trata a ferramenta com respeito, mas com ceticismo, exigindo que o atrito cognitivo aconteça antes de apertar o Tab ou aceitar o PR.

A Maestria é construída no processo, não no resultado final.

Is AI Sabotaging Your Career Growth? Delivery Speed vs. Learning Depth

Diego Chueri — Fri, 21 Nov 2025 09:42:58 +0000

Portuguese Version

You shipped the feature in record time. The code is organized, well-typed, and passed the tests. The PR was approved. You feel invincible for having finished your sprint without much effort.

But be honest with yourself for a second: if Cursor, Copilot, or any other AI tool you used during development had gone offline today, would you have been able to write that complex stream manipulation solution? Or that validation regex? Or the Dockerfile configuration?

We are living in the "Golden Age" of development productivity. AI tools are not just assistants; they are force multipliers. They allow us to skip the boring part, the boilerplate, the syntax we've forgotten. But a silent side effect is happening, affecting everyone from interns to seasoned developers: the outsourcing of "Productive Struggle."

Neuroscience and pedagogy agree on one point: deep learning requires friction. It requires that moment of frustration, of looking at the documentation, of trial and error, of building the mental model of the problem in your head.

When AI gives us the "ideal" answer instantly, we gain speed, but we lose the learning, the practice. We are building increasingly complex and robust software, but are we becoming better developers? Or are we heading for a future of "Showroom Seniors"—developers who know how to orchestrate prompts but freeze when they need to debug what the machine wrote?

In this article, I'm not going to ask you to quit AI; that would be crazy. But let's talk about how to use it without atrophying your critical thinking and technical evolution.

The Science of Learning: Why the "Hard" is Necessary

Remember when you use GPS to go somewhere new? You get there fast, but you realize you have no idea how to get back without it. Conversely, when you get lost, ask for directions along the way, use a map, take a wrong turn, and finally arrive... you never forget the route.

In cognitive psychology, this has a name: "Desirable Difficulties."

Researcher Robert Bjork demonstrated that introducing certain difficulties into the learning process—such as the effort of trying to recall something or solve a problem without immediate help—is fundamental for long-term retention. Real learning doesn't happen when we read the right answer; it happens in the cognitive effort of getting to it.

This is the concept of "Productive Struggle."

When we delegate all the "dirty work" of thinking about syntax, structure, and logic to AI, we are removing the friction. We are turning software development into a passive activity (like following GPS) instead of an active one (like navigating the terrain).

The result? The code goes to production, but the knowledge is not absorbed.

The Trap of Speed vs. Depth

This leads us to a modern problem: the "Illusion of Competence."

Back in the day, a developer stuck on a problem would spend hours reading documentation, understanding the React lifecycle, or the memory structure of Rust. Today, Copilot solves that in seconds.

This creates two types of risks, not just for beginners, but also for experienced developers:

The "Black Box" Plateau: You know that it works, but you don't know how it works. Should you encounter a leaky abstraction or an obscure bug, you lack the minimum mental model required to fix it because you never built the foundation.
The Loss of Critical Judgment: When the AI suggests elegant code, our bias is to accept it. We forget to ask the architectural questions: Does this scale? Does this add an unnecessary dependency? Is this secure?

We are trading depth of understanding for speed of implementation. And in a market that increasingly values the ability to solve complex problems (since AI solves the simple ones), this is a dangerous trade-off for your career.

Strategies for Maintaining Control

1 - For the Developer (Self-Defense Against Atrophy)

If we can't stop using AI, we have to change how we use it. The goal is to ensure the thought process remains human.

The "AI Sandwich" Rule:
- Slice 1 (You): Try to solve the problem for 15 to 30 minutes. Feel the struggle. Understand the pain, the error, the documentation.
- The Filling (AI): Only then, use the AI.
- Slice 2 (You): Do not accept the code. Use it as a reference. Your task now is to critique, refactor, and explain the AI's code, line by line, as if it were an intern's PR.
- The Lesson: You used the AI to validate and accelerate your idea, not to generate or bypass your thought process.
Avoid Premature Abstraction: Use AI to generate boilerplate, configurations, or basic tests. Never for creating the core application logic or architectural decisions. This is where your trade-off judgment is irreplaceable.
The Error Witness: When the AI generates code that fails, don't ask it to fix it. Try to debug and understand why it failed first. Your brain learns much more by fixing a model's error than by receiving the final correction.

2 - For the Technical Leader (A Culture of Questioning)

The responsibility for maintaining the engineering standard now falls on those who review the code.

The Socratic Code Review (The "Why" instead of the "What"):
- Stop commenting: "Use map instead of forEach." (That's syntax, the AI solves it).
- Start asking: "What are the performance and maintenance trade-offs of using this library, compared to the native solution? Why did you discard pattern Y?"
- The focus must be on the architectural decision, forcing the developer to articulate the thought process, even if the AI wrote the code.
The Intentional Challenge (Back to Basics): Occasionally, assign tasks that require foundational knowledge and prohibit (or strongly discourage) the use of LLMs. Example: "Implement an LRU cache from scratch without using third-party libraries." This ensures the mental muscle doesn't atrophy.
Valuing Doubt: Create a culture where asking about trade-offs and uncertainties is valued. An LLM alone cannot give you a raise; your ability to evaluate risks and communicate difficult decisions can.

The Future of Mastery: Human Decision, Assisted Execution

We have reached the crucial point: AI is not stealing our jobs; it is forcing us to elevate the level of our work.

Our tools have made us faster, but we cannot let them make us shallow. The value of the Senior developer has never been in typing code faster, but rather in the ability to make difficult decisions, balance trade-offs (as discussed in my previous articles), and understand the hidden cost of abstractions.

If AI assumes the "What" (the code to be written), we must master the "Why" (the architectural decision). Remember: today's effort is tomorrow's fundamental knowledge. "Productive Struggle" is not a punishment; it is the process of creating value in your brain.

The successful developer in the AI era will be the one who treats the tool with respect, but with skepticism, demanding that cognitive friction happens before hitting Tab or accepting the PR.

Mastery is built in the process, not the final result.

Your "Best Practice" is Someone Else's Tradeoff

Diego Chueri — Mon, 10 Nov 2025 15:21:07 +0000

Versão em Português

Let's be honest. How many hours have you spent Googling the "best way" to do something?

"What's the best database for an e-commerce site?"
"Should I use Microservices or a Monolith?"
"What's the 'best practice' for managing state in React?"

The software development ecosystem seems somewhat obsessed with the idea of "Best Practices." They are sold as golden rules, infallible paths to clean, scalable, and easy-to-maintain software. In code reviews, in blog articles, in conferences... we are surrounded by "the best way" to build software.

But what if this search is, in fact, a trap?

Here's the problem: when we apply these "rules" blindly, the result is often the opposite of what we expected. You implement microservices for a simple application and suddenly, you're spending 80% of your time managing a complex deployment infrastructure instead of delivering value to the user.

Recently, I wrote about "The Cost of Perfection" (overengineering). In it, I explored how our tendency to build "fortresses" trying to cover every possible future scenario often leads to complex, expensive, and hard-to-maintain systems.

What I realized is that overengineering is often a symptom. But what is the root cause? While reading the book "Software Architecture: The Hard Parts", I was able to understand at least part of why this happens.

The book's central insight is both brutal and liberating: true, efficient software architecture isn't JUST about following rules or best practices. It's about understanding, analyzing, and managing tradeoffs.

In this article, I want to share the main insights I took from this book, focusing on why we should stop looking for the "silver bullet" and start developing the most important skill of an architect: analyzing tradeoffs.

Breaking the Myth: Why "Best Practices" Can Be Dangerous

The biggest problem with the term "best practice" is that most of the time I see it being used, I also see it ignoring one of the most important words in software engineering (if not the most important): context.

A solution is never good or bad in a vacuum. It's good or bad for a specific problem, for a specific team, at a specific time.

What is a "best practice" for Netflix, with its tens of thousands of microservices and an elite engineering culture, is almost certainly a terrible practice for a 5-person startup trying to validate a product idea (MVP) in the next 3 months.

Let's take the most classic example from the last decade: Microservices.

If you listen to the conferences and read the most popular blogs, the "best practice" seems to be decomposing everything. The promise is tempting:

Independent scalability!
Autonomous teams!
Deploy without fear!

But that's only one side of the coin. What "Software Architecture: The Hard Parts" emphasizes is that this choice is not an improvement, it's a tradeoff.

By choosing microservices, you are trading the development simplicity of a Monolith for massive operational and infrastructural complexity.

The Microservices Tradeoff:

You GAIN: Granular scalability, independent deployment, fault isolation (maybe, in the best-case scenario with this architecture being well-implemented).

You PAY WITH: Network complexity (latency!), data consistency (sagas, anyone?), difficulty in observability (what called what?), and the need for a much more mature DevOps culture.

The "best practice" of microservices is only "good" if the problem you have (e.g., difficulty scaling a specific part of your system) is greater than the new set of problems you will gain (e.g., managing a complex distributed architecture).

For 90% of applications at the beginning, the "cost" of microservices far outweighs the "gain."

This is the danger: a "best practice" is just the solution someone found for a specific tradeoff. Copying the solution without understanding the original tradeoff is a recipe for disaster (or, at the very least, for a lot of overengineering, as we mentioned before).

Architecture as Tradeoff Analysis

If our job is no longer to blindly apply "best practices," what is our function as developers and architects?

The book makes this very clear: our job is to analyze tradeoffs. It redefines software architecture in a powerful way. It ceases to be the search for a "perfect" or "correct" final state and becomes the continuous process of making hard decisions in a sea of ambiguities.

The most important part to understand is this: a tradeoff is not a choice between a "good" and a "bad" option. That would be easy. A tradeoff is almost always a choice between two (or more) options that are bad in different ways, or good in different ways.

A tradeoff is choosing between:

Option A: Fast to develop, but hard to scale.

Option B: Slow to develop, but easy to scale.

Which one is "right"? It depends. Do you need to launch fast (startup MVP) or do you need to support millions of users (established company)?

The book argues that the "hard parts" of architecture (like decomposing systems or managing distributed data) are hard precisely because there is no easy answer. All that exists are concessions.

The role of the architect or senior developer, therefore, changes drastically:

From: "Knowing what the best solution is (e.g., Kubernetes)."
To: "Knowing what the right questions to ask are (e.g., 'What are the operational costs of adopting Kubernetes now vs. the cost of migrating to it later?')."

The book teaches us that the architect is not the one with the magic answer. They are the one who deeply understands the business requirements and can map which architectural attributes (performance, maintainability, scalability, cost, etc.) are most important for that context and which can be sacrificed.

Three Practical Examples of Tradeoffs

Alright, the theory of "analyzing tradeoffs" is great. But what does it look like in day-to-day life? Let's analyze some classic software engineering dilemmas through the lens of the book.

1. The Data Dilemma: Consistency vs. Availability

The question "SQL or NoSQL?" is perhaps the most misunderstood "best practice" of the last decade. At this moment, you are not facing a simple database choice; you are primarily facing a choice of consistency model.

The "Best Practice" (The Myth): "NoSQL scales better!" or "SQL is ACID and reliable!"
The Tradeoff Analysis: The real question is: What is more expensive for your business? Being temporarily inconsistent or being temporarily unavailable?

The Tradeoff (CAP Theorem):

Choosing Strong Consistency (e.g., a traditional SQL database): You GAIN the guarantee that data is 100% correct and up-to-date across the entire system. A bank transaction always reflects the real balance.

The Cost (Tradeoff): You PAY with availability. In a distributed system, if the network fails between two nodes, the database must block the operation (become unavailable) to ensure consistency is not violated.

Choosing Availability (e.g., NoSQL with Eventual Consistency): You GAIN a system that always responds. A "like" on Instagram or an item added to a shopping cart works even if part of the system is slow.

The Cost (Tradeoff): You PAY with consistency. The system might take a few milliseconds (or seconds) for all nodes to agree. Your "like" might not appear to someone else immediately. You might sell a shopping cart item that just went out of stock (and you'll have to deal with that later).

The Architect's Job: It's not to know if "SQL is better." It's to ask: "For this feature (e.g., shopping cart vs. payment), what is more critical: availability (the customer being able to use it) or consistency (the data being 100% correct right now)?"

2. The Communication Dilemma: Synchronous vs. Asynchronous

How should your services (or microservices) talk to each other?

The "Best Practice" (The Myth): "Decouple everything! Use a Message Broker (Kafka/RabbitMQ) for everything!"
The Tradeoff Analysis: Asynchronous communication is powerful, but it is incredibly complex.

The Tradeoff (Coupling):

Choosing Synchronous (e.g., a direct REST API call): You GAIN simplicity and immediacy. You call the ServiceB.DoThing() API and you know immediately if it worked or failed. The code is linear and easy to debug.

The Cost (Tradeoff): You PAY with temporal coupling. If ServiceB is slow or down, your ServiceA blocks along with it, waiting for a response. A failure cascades.

Choosing Asynchronous (e.g., publishing a ThingDone event): You GAIN resilience. ServiceA just "shouts" the event and moves on. If ServiceB is down, it's not affected. ServiceB will process the event when it comes back up.

The Cost (Tradeoff): You PAY with massive complexity. How do you monitor if the event was processed? How do you handle retries? What about the order of events? You've traded development simplicity for operational resilience.

The Architect's Job: "For this workflow, what is more important: resilience (asynchronous) or simplicity of development and debugging (synchronous)?"

3. The Code Dilemma: Performance vs. Maintainability

How should you write that new module?

The "Best Practice" (The Myth): "Clean Code! SOLID, DRY, KISS! Create all the right abstractions!"
The Tradeoff Analysis: Every layer of abstraction that aids maintainability ("Clean Code") has a performance cost.

The Tradeoff (Abstraction):

Choosing Maintainability (Clean Code): You GAIN code that is easy to test, easy to change, and easy to understand (new devs thank you). You use Repositories, Use Cases, Dependency Injection, etc.

The Cost (Tradeoff): You PAY with performance (even if it's small) and "boilerplate." Each layer of abstraction adds overhead (more function calls, more memory allocation, more indirection).

Choosing Performance ("quick and dirty"): You GAIN raw speed. You write a "raw," optimized SQL query that does 5 joins directly in your handler, skips the ORM, and returns the data in 10ms.

The Cost (Tradeoff): You PAY with maintainability. This code is fragile, hard to test, and a nightmare to change. If the database schema changes, good luck.

The Architect's Job: "Is this a critical part of the system (hot path), like a game's rendering loop, where every nanosecond counts? Or is it a 'settings' CRUD screen that's used once a month, where the speed of modification is more important than the speed of execution?"

How to Start Thinking in Tradeoffs

From now on, "it depends" is your new favorite answer. But how can we turn this philosophy into a practical tool? How do you build this "tradeoff analysis" muscle?

Here are a few practical actions you can start applying today:

1. Change Your Vocabulary (and Your Questions)

The first step is the simplest and the most powerful. Stop asking "What's the best?" and start asking "What are the costs?".

Stop asking: "What's the best database for this project?"

Start asking: "What are the tradeoffs of using PostgreSQL vs. MongoDB for this specific use case? What are we optimizing for? Query speed, infrastructure cost, or schema flexibility?"

Stop saying: "We should use microservices because it's 'best practice'."

Start saying: "If we use microservices, we will gain X, but we will pay with complexity Y. Does this gain justify this cost... right now?"

2. Identify the Business "Drivers"

You can't weigh a tradeoff if you don't know what's most important on the scale. Architecture must always serve the business goals.

Before any major technical decision, ask your team, PM, or leader: "What is the most important 'driver' for this feature?"

Is it Speed of Delivery (Time-to-Market)? (Then maybe the "simpler" and faster solution to implement, even if it's "ugly," is the best one now.)
Is it Extreme Performance? (Maybe that "Clean Code" with 5 layers of abstraction is a luxury we can't afford here.)
Is it Operational Cost? (Will using that managed AWS service be more expensive or cheaper than maintaining a Kubernetes cluster ourselves?)
Is it Maintainability? (Is our team junior and in need of code that's easy to understand, even if it's slower?)

Only after you know what you're optimizing for can you fairly analyze the tradeoff.

3. Use (and Learn to Like) ADRs: Architecture Decision Records

This is the most practical takeaway you can have. "Software Architecture: The Hard Parts" strongly advocates for documenting your decisions.

An ADR (Architecture Decision Record) is a simple, short Markdown document where your team records an important architectural decision. The basic format is:

Title: "Choice of Communication between Service A and B"
Context: "We need Service A to notify Service B when an order is paid."
Decision: "We have chosen to use Synchronous Communication (REST API) for now."
Consequences (The Tradeoff): "We gain simplicity in implementation and debugging. We accept the risk that if B fails, A will fail with it (temporal coupling). This is acceptable today because..."
Options Considered (and why they were discarded): "We considered RabbitMQ, but the infrastructure cost and monitoring complexity were deemed too high for the current project phase."

An ADR is the perfect antidote to the question every dev asks 6 months after something was built: "Why the hell did we do it this way?" It forces you to articulate and remember the whys behind the tradeoffs you analyzed at the time of the decision.

Conclusion: The Most Important Skill

For a long time, I measured my seniority by the number of "best practices" I knew. I thought the best architect was the guy who had the blueprint for the "right way" to build everything.

After gaining more experience, collecting some project scars (like the one I mentioned in my article on overengineering), my perspective changed completely. And the book "Software Architecture: The Hard Parts" was definitely one of the lenses that made me see the whys behind some of the challenges I faced (at least a part of them).

True seniority isn't about having all the answers. It's about understanding that there are no easy answers, only hard tradeoffs.

Software engineering is not an exact science like mathematics; it is a discipline of managing complexity and concessions. The "Myth of the Best Practice" gives us a false sense of security, while "Tradeoff Analysis" gives us the real tool to navigate real-world complexity.

So, the next time you find yourself in a debate about which technology is "better," stop and change the question: "What are the tradeoffs we are making here?"

Thank you for reading and for your attention thus far. I would love to hear from you. Our community is built on real-world experiences.

What was the most difficult (or painful) tradeoff you've had to make on a project recently?

Leave your story in the comments!

A sua "Boa Prática" é o Tradeoff de Alguém

Diego Chueri — Mon, 10 Nov 2025 15:00:00 +0000

English Version

Vamos ser honestos. Quantas horas você já passou pesquisando no Google a "melhor forma" de fazer alguma coisa?

"Qual o melhor banco de dados para um e-commerce?"
"Devo utilizar Microsserviços ou Monolito?"
"Qual seria a 'melhor prática' para gerenciar estados no React?"

O ecossistema do desenvolvimento de software se mostra de certa forma obcecado pela ideia de "Boas Práticas". Elas são vendidas como regras de ouro, caminhos infalíveis para um software limpo, escalável e fácil de manter. Em code reviews, em artigos de blog, em conferências... estamos cercados pela "melhor forma" de construir software.

Mas e se essa busca for, na verdade, uma armadilha?

Aqui está o problema: quando aplicamos essas "regras" cegamente, muitas vezes o resultado é o oposto do esperado. Você implementa microsserviços para uma aplicação simples e, de repente, gasta 80% do tempo gerenciando uma infraestrutura de deploy complexa em vez de entregar valor para o usuário.

Recentemente, escrevi sobre "O Custo da Perfeição" (overengineering). Nele, explorei como nossa tendência de construir "fortalezas" tentando cobrir todos os cenários futuros possíveis muitas vezes leva a sistemas complexos, caros e difíceis de manter.

O que eu percebi é que o overengineering é, frequentemente, um sintoma. Mas qual é a causa raiz? Durante a leitura do livro "Arquitetura de Software: As partes difíceis" pude entender pelo menos parte do porquê disso.

O insight central do livro é ao mesmo tempo brutal e libertador: a verdadeira arquitetura de software eficiente não é sobre APENAS seguir regras ou boas práticas. É sobre entender, analisar e gerenciar tradeoffs (trocas e concessões).

Neste artigo, quero compartilhar os principais insights que tirei desse livro, focando em por que devemos parar de procurar a "bala de prata" e começar a desenvolver a habilidade mais importante de um arquiteto: analisar tradeoffs.

Quebrando o Mito: Por que "Boas Práticas" Podem ser Perigosas

O maior problema com o termo "boa prática" é que na maioria das vezes que vejo ele sendo utilizado vejo também ignorarem uma das palavras mais importantes da engenharia de software (se não a mais importante): contexto.

Uma solução nunca é boa ou ruim no vácuo. Ela é boa ou ruim para um problema específico, para uma equipe específica, em um momento específico.

O que é uma "boa prática" para a Netflix, com suas dezenas de milhares de microsserviços e uma cultura de engenharia de elite, é quase certamente uma péssima prática para uma startup de 5 pessoas tentando validar uma ideia de produto (MVP) nos próximos 3 meses.

Vamos pegar o exemplo mais clássico da última década: Microsserviços.

Se você ouvir as conferências e ler os blogs mais populares, a "boa prática" parece ser decompor tudo. A promessa é tentadora:

Escalabilidade independente!
Times autônomos!
Deploy sem medo!

Mas isso é apenas um lado da moeda. O que o livro "Arquitetura de Software: As partes difíceis" enfatiza é que essa escolha não é uma melhoria, é um tradeoff.

Ao escolher microsserviços, você está trocando a simplicidade de desenvolvimento de um Monolito por uma complexidade operacional e de infraestrutura massiva.

O Tradeoff dos Microsserviços:

Você GANHA: Escalabilidade granular, deploy independente, isolamento de falhas (talvez, na melhor das hipóteses com essa arquitetura sendo bem implementada).

Você PAGA COM: Complexidade de rede (latência!), consistência de dados (sagas, anyone?), dificuldade de observabilidade (o que chamou o quê?), e a necessidade de um DevOps muito mais maduro.

A "boa prática" dos microsserviços só é "boa" se o problema que você tem (ex: dificuldade de escalar uma parte específica do seu sistema) for maior do que o novo conjunto de problemas que você vai ganhar (ex: gerenciar uma arquitetura distribuída complexa).

Para 90% das aplicações no início, o "custo" dos microsserviços supera em muito o "ganho".

Esse é o perigo: uma "boa prática" é apenas a solução que alguém encontrou para um tradeoff específico. Copiar a solução sem entender o tradeoff original é a receita para o desastre (ou, no mínimo, para muito overengineering, como falamos antes).

A Arquitetura como Análise de Tradeoffs

Se o nosso trabalho não é mais aplicar "boas práticas" cegamente, qual é a nossa função como desenvolvedores e arquitetos?

O livro deixa isso muito claro: nosso trabalho é analisar tradeoffs. Ele redefine a arquitetura de software de uma forma poderosa. Ela deixa de ser a busca por um estado final "perfeito" ou "correto" e passa a ser o processo contínuo de tomar decisões difíceis em um mar de ambiguidades.

A parte mais importante de entender é esta: um tradeoff não é uma escolha entre uma opção "boa" e uma "ruim". Isso seria fácil. Um tradeoff é quase sempre uma escolha entre duas (ou mais) opções ruins de formas diferentes, ou boas de formas diferentes.

Um tradeoff é escolher entre:

Opção A: Rápida de desenvolver, mas difícil de escalar.

Opção B: Lenta de desenvolver, mas fácil de escalar.

Qual é a "certa"? Depende. Você precisa lançar rápido (startup em MVP) ou você precisa aguentar milhões de usuários (empresa estabelecida)?

O livro argumenta que as "partes difíceis" da arquitetura (como decompor sistemas ou gerenciar dados distribuídos) são difíceis precisamente porque não existe uma resposta fácil. Tudo o que existe são concessões.

O papel do arquiteto ou do desenvolvedor sênior, portanto, muda drasticamente:

De: "Saber qual é a melhor solução (ex: Kubernetes)."
Para: "Saber quais são as perguntas certas a se fazer (ex: 'Quais são os custos operacionais de adotar Kubernetes agora vs. o custo de migrar para ele depois?')."

O livro nos ensina que o arquiteto não é aquele que tem a resposta mágica. É aquele que entende profundamente os requisitos de negócio e consegue mapear quais atributos de arquitetura (performance, manutenibilidade, escalabilidade, custo, etc.) são mais importantes para aquele contexto e quais podem ser sacrificados.

Três Exemplos Práticos de Tradeoffs

Tudo bem, a teoria de "analisar tradeoffs" é ótima. Mas como ela se parece no dia a dia? Vamos analisar alguns dilemas clássicos da engenharia de software sob a ótica do livro.

1. O Dilema dos Dados: Consistência vs. Disponibilidade

A pergunta "SQL ou NoSQL?" talvez seja a "boa prática" mais mal interpretada da última década. Nesse momento você não está diante de uma simples escolha de banco de dados; você está principalmente diante da escolha de um modelo de consistência.

A "Boa Prática" (O Mito): "NoSQL escala melhor!" ou "SQL é ACID e confiável!"
A Análise de Tradeoff: A verdadeira questão é: O que é mais caro para o seu negócio? Estar temporariamente inconsistente ou estar temporariamente indisponível?

O Tradeoff (Teorema CAP):

Escolhendo Consistência Forte (ex: um banco SQL tradicional): Você GANHA a garantia de que os dados estão 100% corretos e atualizados em todo o sistema. Uma transação bancária sempre reflete o saldo real.

O Custo (Tradeoff): Você PAGA com disponibilidade. Em um sistema distribuído, se a rede falhar entre dois nós, o banco precisa travar a operação (ficar indisponível) para garantir que a consistência não seja violada.

Escolhendo Disponibilidade (ex: NoSQL com Consistência Eventual): Você GANHA um sistema que sempre responde. Um "like" no Instagram ou um item adicionado ao carrinho de compras funciona mesmo que parte do sistema esteja lenta.

O Custo (Tradeoff): Você PAGA com consistência. O sistema pode levar alguns milissegundos (ou segundos) para que todos os nós concordem. O seu "like" pode não
aparecer para outra pessoa imediatamente. Você pode vender um item do carrinho que acabou de ficar sem estoque (e terá que lidar com isso depois).

O Trabalho do Arquiteto: Não é saber se "SQL é melhor". É perguntar: "Para esta funcionalidade (ex: carrinho de compras vs. pagamento), o que é mais crítico: a disponibilidade (o cliente conseguir usar) ou a consistência (o dado estar 100% correto agora)?"

2. O Dilema da Comunicação: Síncrona vs. Assíncrona

Como os seus serviços (ou microsserviços) devem conversar?

A "Boa Prática" (O Mito): "Desacople tudo! Use um Message Broker (Kafka/RabbitMQ) para tudo!"
A Análise de Tradeoff: A comunicação assíncrona é poderosa, mas é incrivelmente complexa.

O Tradeoff (Acoplamento):

Escolhendo Síncrona (ex: uma chamada de API REST direta): Você GANHA simplicidade e imediatismo. Você chama a API ServicoB.FazerCoisa() e sabe imediatamente se funcionou ou falhou. O código é linear e fácil de debugar.

O Custo (Tradeoff): Você PAGA com acoplamento temporal. Se o ServicoB estiver lento ou cair, o seu ServicoA trava junto, esperando uma resposta. Uma falha se espalha em cascata.

Escolhendo Assíncrona (ex: publicando um evento CoisaFeita): Você GANHA resiliência. O ServicoA apenas "grita" o evento e segue a vida. Se o ServicoB estiver caído, ele não é afetado. O ServicoB processa o evento quando voltar.

O Custo (Tradeoff): Você PAGA com complexidade massiva. Como você monitora se o evento foi processado? Como lida com re-tentativas? E a ordem dos eventos? Você trocou a simplicidade de desenvolvimento por resiliência operacional.

O Trabalho do Arquiteto: "Para este fluxo de trabalho, o que é mais importante: a resiliência (assíncrono) ou a simplicidade de desenvolvimento e debug (síncrono)?"

3. O Dilema do Código: Desempenho vs. Manutenibilidade

Como você deve escrever aquele novo módulo?

A "Boa Prática" (O Mito): "Clean Code! SOLID, DRY, KISS! Crie todas as abstrações corretas!"
A Análise de Tradeoff: Cada camada de abstração que facilita a manutenção (o "Clean Code") tem um custo de desempenho.

O Tradeoff (Abstração):

Escolhendo Manutenibilidade (Clean Code): Você GANHA um código fácil de testar, fácil de mudar e fácil de entender (novos devs agradecem). Você usa Repositórios, Casos de Uso, Injeção de Dependência, etc.

O Custo (Tradeoff): Você PAGA com desempenho (mesmo que pequeno) e "boilerplate". Cada camada de abstração adiciona overhead (mais chamadas de função, mais alocação de memória, mais indireção).

Escolhendo Desempenho (”quick and dirty”): Você GANHA velocidade bruta. Você escreve uma query SQL "crua" e otimizada que faz 5 joins direto no seu handler, pula o ORM e retorna os dados em 10ms.

O Custo (Tradeoff): Você PAGA com manutenibilidade. Esse código é frágil, difícil de testar e um pesadelo para alterar. Se o schema do banco mudar, boa sorte.

O Trabalho do Arquiteto:
"Esta é uma parte crítica do sistema (hot path), como um loop de renderização de um jogo, onde cada nanossegundo conta? Ou é uma tela de CRUD de ‘configurações’ que é usada uma vez por mês e onde a velocidade de modificação é mais importante que a de execução?"

Como Começar a Pensar em Tradeoffs

A partir de agora, "depende" é sua nova resposta favorita. Mas como podemos transformar essa filosofia em uma ferramenta prática? Como se constrói esse "músculo" de análise de tradeoffs?

Aqui estão algumas ações práticas que você pode começar a aplicar hoje:

1. Mude o seu Vocabulário (e suas Perguntas)

O primeiro passo é o mais simples e o mais poderoso. Pare de perguntar "Qual é o melhor?" e comece a perguntar "Quais são os custos?".

Pare de perguntar: "Qual é o melhor banco de dados para esse projeto?"

Comece a perguntar: "Quais são os tradeoffs de usar PostgreSQL vs. MongoDB para este caso de uso específico? O que estamos otimizando? Velocidade de consulta, custo de infra, ou flexibilidade de esquema?"

Pare de dizer: "Deveríamos usar microsserviços porque é a 'boa prática'."

Comece a dizer: "Se usarmos microsserviços, ganharemos X, mas pagaremos com a complexidade Y. Esse ganho justifica esse custo... agora?"

2. Identifique os "Drivers" do Negócio

Você não pode pesar um tradeoff se não souber o que é mais importante na balança. A arquitetura sempre deve servir aos objetivos do negócio.

Antes de qualquer decisão técnica grande, pergunte ao seu time, PM ou líder:
"Qual é o requisito mais importante para esta funcionalidade?"

É Velocidade de Entrega (Time-to-Market)? (Então talvez a solução mais "simples" e rápida de implementar, mesmo que "feia", seja a melhor agora.)
É Desempenho Extremo? (Talvez aquele "Clean Code" com 5 camadas de abstração seja um luxo que não podemos pagar aqui.)
É Custo Operacional? (Usar aquele serviço gerenciado da AWS vai ser mais caro ou mais barato do que manter um cluster Kubernetes nós mesmos?)
É Manutenibilidade? (Nosso time é júnior e precisa de um código fácil de entender, mesmo que seja mais lento?)

Só depois de saber o que você está otimizando, você pode analisar o tradeoff de forma justa.

3. Use (e aprenda a gostar dos) ADRs: Architecture Decision Records

Este é o takeaway mais prático que você pode ter. "Arquitetura de Software: As partes difíceis" defende veementemente a documentação das suas decisões.

Um ADR (Architecture Decision Record) é um documento de Markdown simples e curto onde seu time registra uma decisão de arquitetura importante. O formato básico é:

Título: "Escolha de Comunicação entre Serviço A e B"
Contexto: "Precisamos que A notifique B quando um pedido for pago."
Decisão: "Escolhemos usar Comunicação Síncrona (API REST) por enquanto."
Consequências (O Tradeoff): "Ganhamos simplicidade de implementação e debug. Aceitamos o risco de que, se B falhar, A falhará junto (acoplamento temporal). Isso é aceitável hoje porque..."
Opções Consideradas (e por que foram descartadas): "Consideramos RabbitMQ, mas o custo de infra e complexidade de monitoramento foi considerado muito alto para a fase atual do projeto."

Um ADR é o antídoto perfeito para a pergunta que todo dev faz 6 meses depois de que algo foi desenvolvido: "Por que diabos nós fizemos isso desse jeito?" Ele força você a articular e lembrar dos porquês dos tradeoffs que você analisou no momento da decisão.

Conclusão: A Habilidade Mais Importante

Por muito tempo, eu interpretava a minha senioridade pela quantidade de "boas práticas" que eu conhecia. Eu achava que o melhor arquiteto era o cara que mais tinha o blueprint da "forma certa" de construir tudo.

Depois de adquirir mais experiência, colecionar algumas cicatrizes de projetos, como a que mencionei no meu artigo sobre overengineering, minha perspectiva mudou completamente. E com certeza o livro “Arquitetura de Software: As partes difíceis” foi uma das lentes que me fez enxergar os porquês de alguns desafios que encontrei (pelo menos uma parcela deles).

A verdadeira senioridade não é sobre ter todas as respostas. É sobre entender que não existem respostas fáceis, apenas tradeoffs difíceis.

A engenharia de software não é uma ciência exata como a matemática; ela é uma disciplina de gerenciamento de complexidade e concessões. O "Mito da Boa Prática" nos dá uma falsa sensação de segurança, enquanto a "Análise de Tradeoffs" nos dá a verdadeira ferramenta para navegar na complexidade do mundo real.

Portanto, da próxima vez que você se encontrar em um debate sobre qual tecnologia é "melhor", pare e mude a pergunta: "Quais são os tradeoffs que estamos fazendo aqui?"

Obrigado pela sua leitura e atenção até aqui. Eu adoraria saber de você, a nossa comunidade é feita de experiências do mundo real.

Qual foi o tradeoff mais difícil (ou doloroso) que você teve que fazer recentemente em um projeto?

Deixe sua história nos comentários!

Shopify POS Extensions: Connecting the Backend Securely

Diego Chueri — Fri, 24 Oct 2025 15:09:03 +0000

Versão em Português

Building a Shopify POS UI Extension is a great way to add custom features to your Shopify POS. You use the Shopify CLI, generate your extension, customize the React component, and everything seems to work fine... until you need to make that one fetch call to your backend.

At this point, the following questions might come up:

How can my backend know this request is legitimate?
How does it know which shop this call is coming from without exposing that data in the request?
How can we prevent someone malicious from pretending to be our extension and sending fake data?

If you've ever faced this, you know the answer is JWT authentication. Shopify solves this elegantly using Session Tokens.

The official documentation shows the way, but it can be a bit abstract.

In this article, I'll show you the practical, straightforward guide on how we implemented this end-to-end authentication: from the fetch in the POS Extension to the verification middleware in our Node.js backend, using the official library.

Let's dive in!

The General Flow

Before diving into the code, here’s a summary of the authentication flow in 3 steps:

Frontend (POS Extension): Our extension uses the Session API (useApi) to request a unique JWT from Shopify at the time of the request.
The Request: The frontend sends this JWT in the Authorization: Bearer <token> header to our backend.
Backend (Your Server): Our middleware intercepts the call, uses the @shopify/shopify-api library to verify if the token is valid, and if so, identifies the shop and allows the request to continue.

Frontend - Getting the Token

Important: The token retrieval method may vary depending on the Shopify API version used. In this article, we are using version 2025-07.

Shopify makes this step very simple. Inside your extension (which likely uses React), you can use the useApi hook from the @shopify/ui-extensions-react/point-of-sale package.

// extensions/pos-ui-your-extension/src/YourComponent.jsx

import React, {useState, useEffect} from 'react';
import {
  reactExtension,
  useApi,
  Screen,
  Text,
} from '@shopify/ui-extensions-react/point-of-sale';

const SmartGridModal = () => {
  const {currentSession, getSessionToken} =
    useApi<'pos.home.modal.render'>().session;

  const {shopId, userId, locationId, staffMemberId} = currentSession;
  const [sessionToken, setSessionToken] = useState<string>();

  useEffect(() => {
    getSessionToken().then((newToken) => {
        setSessionToken(newToken);
    });
  }, [])

    return (
    <Screen name="ScreenOne" title="Screen One Title">
      <Text>
        shopId: {shopId}, userId: {userId}, locationId: {locationId}, staffId:
        {staffMemberId}
      </Text>
      <Text>sessionToken: {sessionToken}</Text>
    </Screen>
  );
};

export default reactExtension('pos.home.modal.render', () => (
  <SmartGridModal />
));

Note: In cases where the call is triggered by an action (e.g., clicking a "Submit" button triggers a fetch to the backend with a body to be processed), I personally prefer to trigger getSessionToken inside the handler that will make the call. This ensures that the sessionToken is valid at the time of sending.
const onClickHandle = () => {
   getSessionToken().then((newToken) => {
     const headers = { Authorization: `Bearer ${newToken}` };
     fetch("[https://myapi.com](https://myapi.com)", { headers }).then((res) => console.log(res));
   });
};

Backend - Verifying the Token

This is the crucial part. The backend will receive the token from the POS Extension and needs to do two things:

Authenticate: Is it a valid token and was it really issued by Shopify?
Authorize: Does this shop (which the token claims to represent) exist in our database?

We'll use the official Shopify library to do the heavy lifting.

API Configuration (Your shopifyApi.js)

First, we need to ensure our backend knows our API keys. You probably have a configuration file similar to this one (let's call it config/shopifyApi.js) that initializes the Shopify library:

import "@shopify/shopify-api/adapters/node";
import { shopifyApi, ApiVersion } from "@shopify/shopify-api";
import * as dotenv from "dotenv";
dotenv.config();

// We initialize the 'shopify' object, which will be used as the main Shopify instance throughout the API
const shopify = shopifyApi({
  apiKey: process.env.SHOPIFY_API_KEY,
  apiSecretKey: process.env.SHOPIFY_API_SECRET,
  hostName: process.env.HOST,
  scopes: process.env.SCOPES,
  apiVersion: "2025-07", // Use your version
});

If you're not familiar with @shopify/shopify-api, access the complete documentation here.

Creating the Middleware

Now we will finally create the authentication and authorization middleware for the routes that will be used by the POS Extension. It will run before the protected routes.

// src/middlewares/auth.js

import { StoreRepository } from "../repositories/StoreRepository.js";
import { shopify } from "../config/shopifyApi.js"; // The config from Step 2a

export default async (req, res, next) => {
  try {
    // 1. Get the token from the request header
    const token = req.headers["authorization"].split(" ")[1];
    if (!token) {
      throw new Error("Unauthorized");
    }

    // 2. THE MAGIC: Decode and Verify the Token
    // The `decodeSessionToken` does everything:
    // - Fetches Shopify's keys
    // - Verifies the token's signature
    // - Checks if it has expired
    // - If everything is OK, returns the payload (the data)
    const payload = await shopify.session.decodeSessionToken(token);

    // 3. Get the shop's URL (e.g., "[https://my-store.myshopify.com](https://my-store.myshopify.com)")
    const shopId = payload.dest;

    // 4. Authorization: Check if this shop exists in OUR database
    const store = await Store.findOne({ shopId });
    if (!store) {
      // The token is valid, but the shop is not installed in our app
      throw new Error("Store not found");
    }

    // 5. Done! We attach the store to the request
    // Now, all subsequent routes will have access to `req.store`
    req.store = store;

    return next(); // Continues the flow to the route
  } catch (error) {
    // If `decodeSessionToken` fails or the store is not found,
    // we return 401 Unauthorized.
    return res.status(401).json({ message: "Unauthorized" });
  }
};

To summarize what happens in the code above:

shopify.session.decodeSessionToken(token) performs authentication (proves the user is who they claim to be, i.e., Shopify).
Store.findOne() performs authorization (proves the user has permission to access the resource, in the example's case, checks if the shop is registered in the system).

Applying the Middleware to Routes

With the middleware ready, just add it to the routes that need protection.

// src/routes.js

import shopifyAuthMiddleware from "./middleware/shopifyAuth.js";

// ... other application routes

// This route is public, no token needed
routes.get("/api/public/health-check", (req, res) => {
  res.json({ status: "ok" });
});

// This route is PROTECTED by our middleware
routes.get(
  "/api/private/my-data",
  shopifyAuthMiddleware, // <-- The middleware goes here!
  async (req, res) => {
    // If the code reached here, the token is valid and req.store exists!
    const store = req.store;

    res.json({
      message: `Hello, shop ${store.name}!`,
    });
  }
);

Conclusion

It's done! With this architecture, we have closed the end-to-end authentication loop.

Let's recap what we did:

On the Frontend (POS Extension): We used the getSessionToken hook to get a valid session token (JWT) for each API call.
On the Backend (Middleware): We used the shopify.session.decodeSessionToken method to validate the token's signature against Shopify's public keys.
In the Route: We checked if the token's shop exists in our database (Store.findOne) before allowing access.

Now, your backend has a robust and secure way to ensure that every request coming from your POS Extension is legitimate and authenticated. No more "invalid token" or mysterious calls!

So, how do you do it?

This was the way we found to implement authentication following Shopify's best practices.

How does your team handle extension authentication? Do you use a different approach? Did you encounter any problems along the way?

Leave your comment below! Let's share experiences.

Shopify POS Extensions: Conectando o Backend com Segurança

Diego Chueri — Fri, 24 Oct 2025 15:04:26 +0000

English Version

Construir uma Shopify POS UI Extension é uma ótima maneira de adicionar funcionalidades personalizadas ao seu Shopify POS. Você usa o Shopify CLI, gera sua extensão, personaliza o componente React e tudo parece funcionar bem... até você precisar fazer aquela chamada fetch para o seu backend.

Nesse momento podem surgir as seguintes perguntas:

Como meu backend pode saber que essa requisição é legítima?
Como ele sabe de qual loja (shop) essa chamada está vindo sem expor esse dado na requisição?
Como impedir que alguém mal-intencionado finja ser a nossa extensão e envie dados falsos?

Se você já se deparou com isso, você sabe que a resposta é autenticação JWT. A Shopify resolve isso de forma elegante usando Session Tokens.

A documentação oficial mostra o caminho, mas pode ser um pouco abstrata.

Neste artigo, vou mostrar o guia prático e direto de como nós implementamos essa autenticação de ponta a ponta: do fetch na POS Extension até o middleware de verificação no nosso backend Node.js, utilizando a biblioteca oficial.

Vamos lá!

O Fluxo Geral

Antes de mergulhar no código, aqui está o resumo do fluxo de autenticação em 5 etapas:

Frontend (POS Extension): Nossa extensão usa o Session API (useApi) para pedir um JWT exclusivo para a Shopify no momento da requisição.
A Requisição: O frontend envia esse JWT no cabeçalho Authorization: Bearer <token> para o nosso backend.
Backend (Seu Servidor): Nosso middleware intercepta a chamada, usa a biblioteca @shopify/shopify-api para verificar se o token é válido e, se for, identifica a loja e permite que a requisição continue.

Frontend - Pegando o token

Importante: A forma de resgate do token pode variar conforme a versão da API Shopify utlizada. Neste artigo estamos utilizando a versão 2025-07.

A Shopify torna essa etapa bem simples. Dentro da sua extensão (que provavelmente utiliza React), você pode usar o hook useApi do pacote @shopify/ui-extensions-react/point-of-sale.

// extensions/pos-ui-sua-extensao/src/SeuComponente.jsx

import React, {useState} from 'react';
import {
  reactExtension,
  useApi,
  Screen,
  Text,
} from '@shopify/ui-extensions-react/point-of-sale';

const SmartGridModal = () => {
  const {currentSession, getSessionToken} =
    useApi<'pos.home.modal.render'>().session;

  const {shopId, userId, locationId, staffMemberId} = currentSession;
  const [sessionToken, setSessionToken] = useState<string>();

  useEffect(() => {
    getSessionToken().then((newToken) => {
        setSessionToken(newToken);
    });
  }, [])

    return (
    <Screen name="ScreenOne" title="Screen One Title">
      <Text>
        shopId: {shopId}, userId: {userId}, locationId: {locationId}, staffId:
        {staffMemberId}
      </Text>
      <Text>sessionToken: {sessionToken}</Text>
    </Screen>
  );
};

export default reactExtension('pos.home.modal.render', () => (
  <SmartGridModal />
));

Obs: Nos casos onde a chamada é provocada por uma ação (ex.: ao clicar no botão Enviar, é realizada uma fetch para o backend com um body que será processado) eu particularmente dou preferência para acionar o getSessionToken dentro do handle que realizará a chamada. Isso garante que o sessionToken estará valido no momento do envio.
const onClickHandle = () => {
  getSessionToken().then((newToken) => {
    const headers = { Authorization: `Bearer ${newToken}` };
    fetch("https://myapi.com", { headers }).then((res) => console.log(res));
  });
};

Backend - Verificando o Token

Essa é a parte crucial. O backend vai receber o token da POS Extension e precisa fazer duas coisas:

Autenticar: É um token válido e foi realmente emitido pela Shopify?
Autorizar: Essa loja (que o token diz representar) existe no nosso banco de dados?

Vamos usar a biblioteca oficial da Shopify para fazer o trabalho pesado.

Configuração da API (Seu shopifyApi.js)

Primeiro, precisamos garantir que o nosso backend conheça nossas chaves de API. Você provavelmente tem um arquivo de configuração parecido com esse (vamos chamar de config/shopifyApi.js) que inicializa a biblioteca da Shopify:

import "@shopify/shopify-api/adapters/node";
import { shopifyApi, ApiVersion } from "@shopify/shopify-api";
import * as dotenv from "dotenv";
dotenv.config();

// Inicializamos o objeto 'shopify' que será utilizado como instância principal da Shopify em toda a api
const shopify = shopifyApi({
  apiKey: process.env.SHOPIFY_API_KEY,
  apiSecretKey: process.env.SHOPIFY_API_SECRET,
  hostName: process.env.HOST,
  scopes: process.env.SCOPES,
  apiVersion: "2025-07", // Use sua versão
});

Caso você não esteja familiarizado com a @shopify/shopify-api, acesse aqui a documentação completa.

Criando o Middleware

Agora finalmente iremos criar o middleware de autenticação e autorização para as rotas que serão utilizadas pelo POS Extension. Ele será executado antes das rotas protegidas.

// src/middlewares/auth.js

import { StoreRepository } from "../repositories/StoreRepository.js";
import { shopify } from "../config/shopifyApi.js"; // A config da Etapa 2a

export default async (req, res, next) => {
  try {
    // 1. Pegue o token do header da requisição
    const token = req.headers["authorization"].split(" ")[1];
    if (!token) {
      throw new Error("Unauthorized");
    }

    // 2. A MÁGICA: Decodifica e Verifica o Token
    // O `decodeSessionToken` faz tudo:
    // - Pega as chaves da Shopify
    // - Verifica a assinatura do token
    // - Verifica se não expirou
    // - Se tudo estiver OK, retorna o payload (os dados)
    const payload = await shopify.session.decodeSessionToken(token);

    // 3. Pega a URL da loja (ex: "https://minha-loja.myshopify.com")
    const shopId = payload.dest;

    // 4. Autorização: Verifica se essa loja existe no NOSSO banco
    const store = await Store.findOne({ shopId });
    if (!store) {
      // O token é válido, mas a loja não está instalada no nosso app
      throw new Error("Store not found");
    }

    // 5. Feito! Anexamos a loja na requisição
    // Agora, todas as rotas seguintes terão acesso a `req.store`
    req.store = store;

    return next(); // Continua o fluxo para a rota
  } catch (error) {
    // Se `decodeSessionToken` falhar ou a loja não for encontrada,
    // retornamos 401 Unauthorized.
    return res.status(401).json({ message: "Unauthorized" });
  }
};

Resumindo o que ocorre no código acima:

shopify.session.decodeSessionToken(token) realiza a autenticação (prova que o usuário é quem diz ser, ou seja, a Shopify).
Store.findOne() realiza a autorização (prova que o usuário tem permissão para acessar o recurso, no caso do exemplo, verifica se a loja está cadastrada no sistema).

Aplicando o Middleware nas rotas

Com o middleware pronto, basta adicionar nas rotas que precisam de proteção.

// src/routes.js

import shopifyAuthMiddleware from "./middleware/shopifyAuth.js";

// ... demais rotas da aplicação

// Esta rota é pública, não precisa de token
routes.get("/api/public/health-check", (req, res) => {
  res.json({ status: "ok" });
});

// Esta rota é PROTEGIDA pelo nosso middleware
routes.get(
  "/api/private/meus-dados",
  shopifyAuthMiddleware, // <-- O middleware entra aqui!
  async (req, res) => {
    // Se o código chegou aqui, o token é válido e req.store existe!
    const store = req.store;

    res.json({
      message: `Olá, loja ${store.name}!`,
    });
  }
);

Conclusão

Está feito! Com essa arquitetura fechamos o ciclo de autenticação de ponta a ponta.

Vamos recapitular o que fizemos:

No Frontend (POS Extension): Usamos o hook getSessionToken para pegar um session token (JWT) válido a cada chamada de API.
No Backend (Middleware): Usamos o método shopify.session.decodeSessionToken para validar a assinatura do token contra as chaves públicas da Shopify.
Na Rota: Verificamos se a loja do token existe em nosso banco de dados (Store.findOne) antes de permitir o acesso.

Agora, seu backend tem uma forma robusta e segura de garantir que cada requisição vinda da sua POS Extension é legítima e autenticada. Chega de "token inválido" ou chamadas misteriosas!

E aí, como você faz?

Essa foi a maneira que encontramos para implementar a autenticação seguindo as melhores práticas da Shopify.

Como sua equipe lida com a autenticação de extensões? Você usa uma abordagem diferente? Encontrou algum problema no caminho?

Deixe seu comentário abaixo! Vamos trocar experiências.

O Custo da “Perfeição”

Diego Chueri — Thu, 10 Apr 2025 00:25:40 +0000

English Version

Cada atividade desenvolvida em uma empresa de tecnologia possui suas peculiaridades e desafios. Sem dúvidas, o overengineering é um dos medos comuns a praticamente todas as áreas do desenvolvimento de software.

Na constante corrida do mercado da tecnologia, as empresas sofrem uma “pressão natural” para adotarem novas soluções. Pensar demais antes de implementar uma arquitetura mais robusta ou uma nova ferramenta inovadora que ofereça performance superior e custos significativamente menores pode ser decisivo para alcançar destaque ou para gerar um atraso em relação aos concorrentes. Contudo, muitas vezes esquecemos que o excesso de recursos pode ser tão prejudicial quanto a sua ausência.

Gostaria de trazer uma reflexão sobre o quão custoso ou mortífero para um produto pode ser a busca pela perfeição. Acho que a maioria dos desenvolvedores vai se identificar com o ciclo abaixo:

Ideia genial surge:

"Nossa, isso resolveria um problema real! Ninguém fez isso ainda??"
Pesquisa de mercado/concorrência:

"Hm, já tem algo parecido... mas acho que dá pra fazer melhor."
Escolha da stack e arquitetura:

"Ok, vou usar a stack mais moderna que conheço, com clean architecture, DDD, CQRS, event sourcing, monorepo com turborepo, microserviços com gRPC, e claro, full TypeScript."
Estruturação exagerada:

"Antes de escrever qualquer feature, vou montar os folders certinhos, configs, pipelines, testes, linter, husky, commitizen, docker-compose, etc."
Cansaço/ansiedade/overload:

"Putz... só de pensar em seguir isso tudo já dá preguiça. E ainda tenho aquele outro trabalho/freela/prazo..."
Abandono silencioso:

“Um dia eu volto...”

O repositório fica lá, com um README inacabado e três commits.

E se pensarmos no impacto desse ciclo para uma empresa? No exemplo acima vemos o cenário onde o desenvolvedor decide ser dono do seu próprio negócio e por em prática uma ideia autoral, mas a única diferença entre essa realidade para uma em que esse mesmo desenvolvedor trabalha para uma empresa é o último passo, onde na maioria das vezes o projeto não é abandonado, muito pelo contrário, ele cresce.

Por que o excesso pode ser pior que a falta?

“A diferença entre o remédio e o veneno é a dose.”

Essa frase, atribuída ao médico Paracelso, transcende a medicina e se aplica perfeitamente ao desenvolvimento de software. O sistema que você desenvolveu pode apresentar deficiências ou patologias; porém, iniciar a aplicação de todos os “remédios” disponíveis, sem compreender a real necessidade ou o porquê de cada solução, pode agravar ainda mais os problemas.

Para ilustrar, veja os pontos negativos de cada extremo:

Falta:

Dificuldade de manutenção: A falta de organização e padronização na base de código pode transformar a busca pela causa de um bug em um verdadeiro martírio, mesmo para o próprio desenvolvedor que criou a funcionalidade.
Falta de escalabilidade;
Baixo nível de confiabilidade;
Desempenho ineficiente;
Queda no ritmo das entregas.

Excesso:

Dificuldade de manutenção: Complexidades desnecessárias podem tornar o código confuso e difícil de atualizar.
Necessidade de um nível técnico elevado por parte do time;
A soma dos problemas citados na falta, potencializados pela complexidade adicional.

Causas e “Miragens Técnicas”

As causas para a falta e o excesso de engenharia podem seguir caminhos opostos. Enquanto a carência de engenharia costuma estar relacionada ao débito técnico ou ao raciocínio imediatista, o excesso muitas vezes surge da busca incessante pela perfeição, combinada com um conhecimento superficial de diversas ferramentas e um raciocínio hiperprudente.

Um programador com uma “maleta recheada de ferramentas” não necessariamente sabe o momento ideal para usar cada uma delas. No mundo atual, onde a informação circula rapidamente, é comum conhecer diversas soluções por meio de vídeos curtos ou cursos rápidos. Contudo, compreender superficialmente um conceito (explicado em um vídeo de poucos minutos) não equivale a dominar sua aplicação em projetos reais.

Devemos ter cuidado para não confundir “conhecer” com “dominar”. Especialmente quando estamos aprendendo um novo framework, é importante evitar as “miragens técnicas” que podem nos levar a acreditar que entendemos o suficiente para aplicar soluções complexas sem uma análise profunda.

Especulações e Suas Ramificações

Durante pesquisas sobre o tema, notei que muitos artigos e vídeos (irei disponibilizar alguns links no final) destacam a “especulação” como um fator comum. Essa especulação gera diversas ramificações, como:

Escopo mal definido: Quanto mais vaga a definição dos requisitos, mais amplo tende a ser o código desenvolvido para “proteger” contra incertezas.
Cobertura excessiva: Desenvolvedores, na tentativa de cobrir todos os cenários, podem acabar expandindo tarefas simples para problemas maiores, especialmente quando não há desafios empolgantes ou prazos curtos.

Além disso, o tédio pode levar à superengenharia. Existem dois perfis profissionais comuns no desenvolvimento de software:

O profissional que executa suas tarefas de forma pontual, recorrendo a hábitos que, em momentos de ociosidade, se refletem em comportamentos pouco produtivos;
Aquele que está sempre em busca de aprender e aplicar novas tecnologias.

Embora o segundo perfil seja geralmente mais produtivo, se não for desafiado com tarefas estimulantes, pode transformar uma solução simples em um problema complexo na tentativa de experimentar novidades.

(Overengineering can kill your product)

Outro exemplo clássico é a otimização prematura. Preparar um sistema para absorver um alto tráfego com uma infraestrutura excessivamente complicada, antes mesmo de ter usuários, é uma armadilha. Arquiteturas mirabolantes e complexas podem não ser necessárias se seus pontos fortes não se encaixarem no contexto atual. Uma solução boa e escalável é aquela que traça uma trilha clara para o crescimento e facilita as próximas decisões, sem tentar abarcar todos os cenários possíveis.

Explorando as Consequências

Toda decisão envolve trade-offs. A complexidade crescente aumenta a curva de adaptação dos novos membros da equipe, elevando os custos. Em alguns casos, esse custo pode ser compensado no longo prazo, mas, frequentemente, a complexidade excessiva gera dependência dos desenvolvedores mais experientes e dificulta o trabalho dos menos experientes, acumulando débito técnico. Essa situação se reflete na dificuldade para debugar, na manutenção onerosa e no aumento dos custos com infraestrutura.

Fugindo um pouco da esfera do desenvolvimento de código e entrando na parte de gerenciamento de processos, no Scrum, por exemplo, apenas o ato de granularizar melhor as atividades já tem um impacto direto na regra INVEST (Independente, Negociável, Valioso, Estimável, Pequeno, Testável). Isso facilita significativamente o refinamento e permite estimativas mais precisas e realistas. Vamos a um exemplo simples:

-- Card 1 --

Nome: Desenvolver uma tela de login

Descrição:
[ ] O usuário deverá conseguir realizar o login e recuperar a senha.

-- Card 2 --

Nome: Desenvolver uma tela de login

Descrição:
[ ] Deve possuir um campo de E-mail, com validação de formato e feedback visual;
[ ] Deve possuir um campo de Senha, com validação de tamanho (mínimo de 6 caracteres) e feedback visual;
[ ] Deve haver um link “Recuperar senha”, que redireciona o usuário para uma outra página (essa página será desenvolvida posteriormente).

Ao se deparar com o Card 1, surgem imediatamente uma série de dúvidas e possibilidades na mente do desenvolvedor: o login será feito com e-mail ou username? As validações serão feitas apenas no backend ou também no frontend? Quais as regras exatas de validação? Quanto tempo levaria para desenvolver a página de recuperação de senha? Enviaremos o link por e-mail ou SMS? Talvez seja melhor criar algo mais flexível desde já para facilitar futuras alterações...

Esse cenário tende a resultar em estimativas infladas, maior esforço para entrega, risco elevado de fuga do escopo, maior probabilidade de adicionar funcionalidades desnecessárias e, claro, overengineering. A sensação é semelhante àquelas cenas clássicas de desenhos animados, onde a sombra na parede parece ser de um monstro assustador, mas ao acender a luz, percebemos que era apenas um bichinho de pelúcia.

Esse efeito psicológico impacta diretamente a pró-atividade da equipe e aumenta os níveis de estresse, comprometendo (e muito) a adesão aos valores do Scrum: foco, coragem, comprometimento, respeito e abertura.

Como Evitar o Overengineering?

O principal caminho para evitar o overengineering é questionar o porquê de cada decisão, mantendo o foco na resolução de problemas reais. Algumas diretrizes que ajudam nesse processo são:

Keep It Simple, Stupid (KISS): Busque sempre a solução mais simples que atenda aos requisitos do problema. Isso garante um código mais legível, com menor necessidade de um alto nível técnico para manutenção e entendimento.
You Ain’t Gonna Need It (YAGNI): Se não há uma demanda concreta para determinada funcionalidade, não a implemente. Soluções para problemas imaginários geram código desnecessário e desperdício de tempo. Estudos, como o realizado pela Pennsylvania State University, mostram que aproximadamente 91% dos problemas especulados não se concretizam.

Existem algumas formas mais específicas de se evitar, dependendo do seu papel no ciclo de desenvolvimento. No caso de uma liderança, converse com sua equipe e esteja aberto a novas perspectivas. Se, ao apresentar uma solução, você se vê explicando demasiadamente seus fundamentos, talvez seja um sinal de que a solução está sendo mais complexa do que o necessário. Foque na otimização das partes com maior impacto no produto, aquele 1% do código que pode potencialmente otimizar 90% dos resultados, em vez de investir esforços em áreas de menor relevância.

Nas funções de gerência, buscar ser o mais específico possível ao repassar as demandas tende a criar “guard rails” para o time de desenvolvimento, evitando que o desenvolvedor tenha que pensar demasiadamente sobre os possíveis problemas/cenários que a essa nova solução envolve.

Conclusão

Este texto não foi criado para justificar divergências de opinião sobre arquiteturas ou ferramentas em projetos colaborativos, mas para enfatizar a importância de compreender os impactos de cada decisão. O equilíbrio é crucial para um desenvolvimento saudável. Busque conhecimento, experiências, teste e treine; porém, sempre lembrando de que um bom marinheiro não usa sua experiência para enfrentar mais tempestades, mas sim para evitá-las.

Compartilhe suas experiências, revise seus projetos com essa perspectiva e mantenha o foco na criação de valor real através de soluções simples e eficazes.

Links e Referências

The Cost of Perfection

Diego Chueri — Thu, 10 Apr 2025 00:24:14 +0000

Versão em Português

Each activity developed in a tech company has its own peculiarities and challenges. Without a doubt, overengineering is one of the common fears across practically every area of software development.

In the constant race of the tech market, companies face a “natural pressure” to adopt new solutions. Overthinking before implementing a more robust architecture or an innovative new tool — one that offers superior performance and significantly lower costs — can be decisive in achieving a competitive edge or falling behind the competition. However, we often forget that an excess of features can be just as harmful as their absence.

I'd like to reflect on how costly — or even deadly — the pursuit of perfection can be for a product. I think most developers will relate to the cycle below:

Brilliant idea pops up:

“Wow, this would solve a real problem! No one’s done this yet??”
Market/competitor research:

“Hmm, there's something similar… but I think I can do it better.”
Stack and architecture selection:

“Okay, I’ll use the most modern stack I know, with clean architecture, DDD, CQRS, event sourcing, monorepo with turborepo, microservices with gRPC, and of course, full TypeScript.”
Overstructuring:

“Before writing any feature, I’ll set up all the folders just right, configs, pipelines, tests, linter, husky, commitizen, docker-compose, etc.”
Fatigue/anxiety/overload:

“Ugh… just thinking about doing all of this is exhausting. And I still have that other job/freelance/deadline…”
Silent abandonment:

“One day I’ll come back…”

The repo stays there, with an unfinished README and three commits.

Now imagine the impact of this cycle on a company. In the example above, the developer decides to become their own boss and put an original idea into practice — but the only difference between this and a scenario where the same developer works for a company is the last step. In that case, the project usually isn’t abandoned — on the contrary, it grows.

Why Can Too Much Be Worse Than Too Little?

“The difference between a remedy and a poison is the dose.”

This quote, attributed to the physician Paracelsus, goes far beyond medicine and perfectly applies to software development. The system you’re building might have deficiencies or pathologies; however, applying every possible “remedy” without understanding the real needs or rationale behind each solution might worsen the situation.

To illustrate, here are the downsides of each extreme:

Too Little:

Maintenance difficulties: Lack of organization and standardization in the codebase can turn debugging into a nightmare — even for the developer who wrote it.
Lack of scalability;
Low reliability;
Inefficient performance;
Slower delivery pace.

Too Much:

Maintenance difficulties: Unnecessary complexities can make the code confusing and hard to update.
Need for a highly skilled team;
A combination of the problems mentioned in the “Too Little” section, amplified by additional complexity.

Causes and “Technical Mirages”

The causes of under- and overengineering may go in opposite directions. While a lack of engineering is often linked to technical debt or short-term thinking, excess usually stems from a relentless pursuit of perfection, mixed with a shallow understanding of various tools and an overly cautious mindset.

A developer with a “toolbox full of tools” doesn’t necessarily know the right time to use each one. In today’s fast-paced information world, it’s common to learn about many solutions through short videos or quick courses. However, having a superficial understanding of a concept — as explained in a five-minute video — is not the same as mastering its real-world application.

We must be careful not to confuse “knowing” with “mastering.” Especially when learning a new framework, it’s important to avoid “technical mirages” that trick us into thinking we understand enough to apply complex solutions without deep analysis.

Speculations and Their Branches

While researching this topic, I noticed that many articles and videos (I'll link some at the end) highlight “speculation” as a common factor. Speculation leads to several consequences, such as:

Poorly defined scope: The vaguer the requirements, the broader the code tends to be, in an attempt to “protect” against uncertainties.
Excessive coverage: Developers, trying to cover all scenarios, may end up turning simple tasks into bigger problems — especially when there are no exciting challenges or tight deadlines.

Moreover, boredom can lead to overengineering. There are two common developer profiles:

The one who completes tasks on time, but whose idle habits lead to unproductive behavior;
The one who is always looking to learn and apply new technologies.

While the second profile is generally more productive, if not challenged with stimulating tasks, they may turn a simple solution into a complex one just to try out something new.

(Overengineering can kill your product)

Another classic example is premature optimization. Preparing a system for high traffic with an overly complex infrastructure — before having any users — is a trap. Fancy and complex architectures may be unnecessary if their strengths don’t match the current context. A good, scalable solution is one that paves a clear path for growth and simplifies future decisions without trying to cover every possible scenario.

Exploring the Consequences

Every decision involves trade-offs. Growing complexity increases the onboarding curve for new team members, raising costs. In some cases, this may pay off in the long run. But often, excessive complexity creates dependency on senior developers and makes work harder for junior ones, increasing technical debt. This shows up in harder debugging, expensive maintenance, and rising infrastructure costs.

Stepping a bit outside the coding side and into process management, in Scrum, simply breaking down tasks more effectively has a direct impact on the INVEST rule (Independent, Negotiable, Valuable, Estimable, Small, Testable). This significantly improves refinement and allows for more precise, realistic estimations. Here’s a simple example:

-- Card 1 --

Name: Develop a login screen

Description:
[ ] The user should be able to log in and recover their password.

-- Card 2 --

Name: Develop a login screen

Description:
[ ] Must include an Email field with format validation and visual feedback;
[ ] Must include a Password field with length validation (minimum 6 characters) and visual feedback;
[ ] Must include a “Recover password” link that redirects the user to another page (this page will be developed later).

When faced with Card 1, developers immediately think of many questions and scenarios: will the login use email or username? Will validation happen only on the backend or also on the frontend? What are the exact validation rules? How long would it take to develop the password recovery page? Will the link be sent via email or SMS? Maybe it’s better to make something flexible now to allow future changes...

This scenario often leads to inflated estimates, more effort required for delivery, a high risk of scope creep, a greater chance of adding unnecessary features, and, of course, overengineering. The feeling is similar to those classic cartoon scenes, where a shadow on the wall looks like a scary monster — but when the light comes on, it turns out to be just a stuffed toy.

This psychological effect directly impacts the team’s proactiveness and raises stress levels, seriously undermining adherence to the Scrum values: focus, courage, commitment, respect, and openness.

How to Avoid Overengineering?

The key to avoiding overengineering is questioning the “why” behind each decision and staying focused on solving real problems. Some guidelines that help in this process are:

Keep It Simple, Stupid (KISS): Always aim for the simplest solution that meets the requirements. This ensures more readable code and reduces the need for high technical knowledge for maintenance and understanding.
You Ain’t Gonna Need It (YAGNI): If there’s no concrete demand for a feature, don’t implement it. Solutions for imaginary problems generate unnecessary code and wasted time. Studies — such as the one from Pennsylvania State University — show that about 91% of speculated problems never materialize.

There are more specific ways to avoid overengineering depending on your role in the development cycle. For those in leadership, talk to your team and stay open to new perspectives. If you find yourself explaining your solution at length to justify it, that might be a sign that it’s more complex than necessary. Focus on optimizing the areas that have the greatest impact on the product — that 1% of code that could potentially improve 90% of results — instead of investing effort in less relevant areas.

In management roles, being as specific as possible when passing along requirements tends to create “guard rails” for the dev team, preventing developers from having to overthink all the possible problems/scenarios a new solution might involve.

Conclusion

This text wasn’t written to justify differences of opinion regarding architectures or tools in collaborative projects, but to emphasize the importance of understanding the impact of each decision. Balance is essential for healthy development. Seek knowledge, gain experience, test and train — but always remember that a good sailor doesn’t use their experience to sail through more storms, but to avoid them.

Share your experiences, review your projects with this perspective in mind, and stay focused on delivering real value through simple, effective solutions.

Links and References

[React + Jest] Introducing to Components Tests

Diego Chueri — Sat, 10 Dec 2022 13:40:25 +0000

Versão em português

Introduction

Different from the Backend where the unit tests aim to evaluate the behavior of a certain method, the unit tests for the Frontend must focus on "simulating" the possible actions of the users and how a certain component reacts to a certain action.

Why write tests?

Although it may seem complicated at first, automated tests can save you headaches in the future. They are the most effective way to verify that your code does what you want it to do, can prevent a bug that has already been fixed from occurring again, and more others benefit your application.

Technologies

To write our tests, we will use the following stack:

React 18.2.0;
Jest 28.1.2; e
Testing Library 13.4.0.

Component to be tested

To write a good test you must know the code and the behavior you expect, so let's analyze our LoginForm before starting the tests.

Introducing the Code

As an example, a simple component of a login form will be used:

import { useState } from "react";

const db = {
  email: "diego@test.com",
  password: "123456",
};

export const LoginForm = () => {
  const [email, setEmail] = useState<string>();
  const [password, setPassword] = useState<string>();
  const [logged, setLogged] = useState<Boolean>(false);
  const [error, setError] = useState<Boolean>(false);

  const login = (email: string, password: string) => {
    if (email !== db.email || password !== db.password) {
      setError(true);
      setLogged(false);
    } else {
      setError(false);
      setLogged(true);
    }
  };

  const handleSubmit = (e: React.SyntheticEvent) => {
    e.preventDefault();
    login(email!, password!);
  };

  return (
    <form onSubmit={handleSubmit}>
      <label>
        Email
        <input
          name="email"
          type="text"
          onChange={(e) => setEmail(e.target.value)}
        />
      </label>
      <label>
        Password
        <input
          name="password"
          type="password"
          onChange={(e) => setPassword(e.target.value)}
        />
      </label>
      <button type="submit">Log in</button>
      {logged ? (
        <p>Wellcome!</p>
      ) : error ? (
        <p>Email or password invalid</p>
      ) : null}
    </form>
  );
};

Resulting in the following interface:

Understand how LoginForm works

Was used the db constant as a mock of a user on the database:

const db = {
  email: "diego@test.com",
  password: "123456",
};

Next is our LoginForm. Basically, it stores the input value of each form field in state through onChange. When clicking on the Log In button, the handleSubmit is activated, which, through the login method, verifies whether the e-mail and password passed by the user coincide with the user's password in the bank (in our case, in the mock).

If the email and password are valid, a welcome message (Welcome!) is displayed:

And if any of the two fields have any invalid data, it is displayed to the user (Invalid email or password):

Starting the tests

Let's create the test file for our component in the same folder where it is inserted. For good practices, I usually name the test file with the same name as the component, followed by the .spec.tsx extension (if you are not using typescript like me, the extension would be .spec.jsx).

Starting, let's use the describe method, where we'll pass a string as the first parameter, which is usually the name of the tested component. The second parameter is a callback function that will receive our tests:

describe("LoginForm", () => {})

Tests are written inside the it or test functions, the two are functionally identical, and I prefer to use it just for semantics, improving readability. The function also receives two parameters, where the first is a description of what should happen during the test and the second is another callback, but this time with the test code.

describe("LoginForm", () => {                // LoginForm...
    it("should render the login form", () => { // ...deve renderizar o formulário de login
        //code for test here
  });
})

At this point, we can start testing the rendering of the elements.

Rendering UI

The render() method will render the component. It takes the component as a parameter and returns a RenderResult that has several utility methods and properties.

import { render } from "@testing-library/react";
import { LoginForm } from "../LoginForm";

describe("LoginForm", () => {
  it("should render the login form", () => {
    render(<LoginForm />);
  });
})

Capturing an element on DOM

The screen is used to query the DOM. It has a series of queries that will query the DOM as needed and return the chosen element.

//...imports
import { render, screen } from "@testing-library/react";

describe("LoginForm", () => {
  it("should render the login form", () => {
    render(<LoginForm />);

        const emailField = screen.getByLabelText("Email");
        const passwordField = screen.getByText("Password");
        const loginButton = screen.getByRole("button", { name: "Log in" });
  });
});

Three examples of queries were presented among the many that can be used:

getByLabelText: Recommended by the official documentation to search for form fields (in the example I did not use this query in all options to expand the presentation of the possibilities of use);
getByText: Outside of forms, text content is the main way to find elements. This method is recommended for locating non-interactive elements (such as divs, spans, and paragraphs); and
getByRole: Used to query elements by their accessible name (button, div, p, among others). It is normally used with the option {name: …} object, avoiding unwanted elements.

I suggest reading the documentation with all queries in this link.

Time to test

Render test

Now let's finally test if the elements are being rendered. To test the values, the expect function is used, it uses functions matchers that perform checks between the expected value and the received value.

//...imports
import '@testing-library/jest-dom';

describe("LoginForm", () => {
  it("should render the login form", () => {
    render(<LoginForm />);

        const emailField = screen.getByLabelText("Email");
        const passwordField = screen.getByText("Password");
        const loginButton = screen.getByRole("button", { name: "Log in" });

        expect(emailField).toBeInTheDocument();
    expect(passwordField).toBeInTheDocument();
    expect(loginButton).toBeInTheDocument();
  });
});

PASS  src/components/LoginForm/LoginForm.spec.tsx
  LoginForm
    ✓ should render the login form (82 ms)

Test Suites: 1 passed, 1 total
Tests:       1 passed, 1 total
Snapshots:   0 total
Time:        3.01 s, estimated 4 s

💡 Don't forget to import the @testing-library/jest-dom module to use mathcer toBeInDocument.

See more about Testing Library Custom Matchers.

More tests

Now that we know that the expected elements are being rendered normally, we will check their behavior when interacting with the user, and for that we will use the userEvent.

Successful login test

At this point, remember that it is necessary to imagine the user's actions. Therefore, to perform the login, the user first enters the data in the email and password fields, finally he clicks on the Log In button, receiving the welcome message if the data are correct or, if otherwise, you will receive an error message.

The type method emulates typing by the user, receiving the element into which the text will be inserted as the first parameter and the text itself as the second parameter. It returns a Promise so it is necessary to add the await before the userEvent and the async at the beginning of the test's callback function.

await userEvent.type(emailField, userInput.email);
await userEvent.type(passwordField, userInput.password);

With the form completed, we will use the click method to click on the login button.

await userEvent.click(loginButton);

Now we can perform the comparison between the expected values and the received values:

// expects the element with the text "Welcome!" to be in the document
expect(screen.getByText("Welcome!")).toBeInTheDocument();
// expects that the element with the text "Invalid email or password" is not found, returning null
expect(screen.queryByText("Invalid email or password")).toBeNull();

Note that in the first expect it is expected that an element with the text “Welcome!” is in the document, using the already known getByText method. In the second, queryByText was used instead of getByText, because it is expected that the element is not in the document, and when we use any method started with get and no element is found, an error interrupting the test, since the methods started with query return null , allowing the continuation of the test.

Staying our second test in this way:

//...imports
import userEvent from "@testing-library/user-event";

describe("LoginForm", () => {
  it("should render the login form", () => {
    ...
  });

  it("should show an welcome message if login success", async () => {
    render(<LoginForm />);

    const emailField = screen.getByLabelText("Email");
    const passwordField = screen.getByText("Password");
    const loginButton = screen.getByRole("button", { name: "Log in" });

    const userInput = { email: "diego@test.com", password: "123456" };

    await userEvent.type(emailField, userInput.email);
    await userEvent.type(passwordField, userInput.password);
    await userEvent.click(loginButton);

    expect(screen.getByText("Welcome!")).toBeInTheDocument();
    expect(screen.queryByText("Invalid email or password")).toBeNull();
  });
});

PASS  src/components/LoginForm/LoginForm.spec.tsx
  LoginForm
    ✓ should render the login form (109 ms)
    ✓ should show a welcome message if login success (141 ms)

Test Suites: 1 passed, 1 total
Tests:       2 passed, 2 total
Snapshots:   0 total
Time:        2.6 s, estimated 3 s

Failed login test

The last test we are going to write in this article is in case the email or password entered by the user is invalid. The logic will be the same as in the previous test, only changing the order of the expected messages:

//...imports

describe("LoginForm", () => {
  it("should render the login form", () => {
    ...
  });

  it("should show an welcome message if login success", async () => {
    ...
  });

  it("should show an error message if login failed", async () => {
    render(<LoginForm />);

    const emailField = screen.getByLabelText("Email");
    const passwordField = screen.getByText("Password");
    const loginButton = screen.getByRole("button", { name: "Log in" });

    const userInput = { email: "diego@test.com", password: "worngPassword" };

    await userEvent.type(emailField, userInput.email);
    await userEvent.type(passwordField, userInput.password);
    await userEvent.click(loginButton);

    expect(screen.getByText("Invalid email or password")).toBeInTheDocument();
    expect(screen.queryByText("Welcome!")).toBeNull();
  });
});

PASS  src/components/LoginForm/LoginForm.spec.tsx
  LoginForm
    ✓ should render the login form (89 ms)
    ✓ should show a welcome message if login success (166 ms)
    ✓ should show an error message if login failed (126 ms)

Test Suites: 1 passed, 1 total
Tests:       3 passed, 3 total
Snapshots:   0 total
Time:        2.388 s, estimated 3 s

Conclusion

I sought in this article mainly to open the door to the universe of tests. An idea to exercise what you've learned here is to clone this project's repository and create other tests, such as testing what will happen if the user doesn't fill in any of the fields when there is a required.

With this article, as with any other article you read, try not to restrict yourself only to what has been demonstrated, use the auxiliary links made available during the explanation, explore, exercise, and get to know each functionality better to improve your knowledge.

Project Repository

React Tests - GitHub

Read too

ArchLinux config on WSL2 to developers

[React + Jest] Introduzindo Testes para "Components"

Diego Chueri — Fri, 09 Dec 2022 22:03:49 +0000

English version

Introdução

Diferente do Backend onde os testes unitários visam avaliar o funcionamento de um determinado método, os testes unitários para o Frontend devem focar em "simular" as possíveis ações dos usuários e como determinado componente reage a determinada ação.

Porque escrever testes?

Embora possa parecer complicado no início, testes automatizados podem evitar dor de cabeça no futuro. São a forma mais efetiva de verificar se o seu código realmente faz o que você deseja que ele faça, podem evitar que algum bug que já tenha sido corrigido previamente volte a ocorrer, e diversos outros benefícios para a sua aplicação.

Tecnologias

Para escrever nossos testes iremos utilizar a stack a seguir:

React 18.2.0;
Jest 28.1.2; e
Testing Library 13.4.0.

"Component" a ser testado

Para escrever um bom teste você deve conhecer bem o código e o comportamento que espera, então vamos analisar o nosso LoginForm antes de iniciar os testes:

Apresentando o Código

Como exemplo, será utilizado um component simples de um formulário de login:

import { useState } from "react";

const db = {
  email: "diego@test.com",
  password: "123456",
};

export const LoginForm = () => {
  const [email, setEmail] = useState<string>();
  const [password, setPassword] = useState<string>();
  const [logged, setLogged] = useState<Boolean>(false);
  const [error, setError] = useState<Boolean>(false);

  const login = (email: string, password: string) => {
    if (email !== db.email || password !== db.password) {
      setError(true);
      setLogged(false);
    } else {
      setError(false);
      setLogged(true);
    }
  };

  const handleSubmit = (e: React.SyntheticEvent) => {
    e.preventDefault();
    login(email!, password!);
  };

  return (
    <form onSubmit={handleSubmit}>
      <label>
        Email
        <input
          name="email"
          type="text"
          onChange={(e) => setEmail(e.target.value)}
        />
      </label>
      <label>
        Password
        <input
          name="password"
          type="password"
          onChange={(e) => setPassword(e.target.value)}
        />
      </label>
      <button type="submit">Log in</button>
      {logged ? (
        <p>Wellcome!</p>
      ) : error ? (
        <p>Email or password invalid</p>
      ) : null}
    </form>
  );
};

Resultando na seguinte interface:

Entendendo o funcionamento

Foi utilizado como mock de um usuário no banco de dados a constante db:

const db = {
  email: "diego@test.com",
  password: "123456",
};

Em seguida está o nosso LoginForm. Basicamente ele armazena o valor do input de cada campo do formulário no state por meio do onChange. Ao clicar no botão de Log In é acionado o handleSubmit que por meio do método de login faz a verificação se o e-mail e senha passados pelo usuário coincidem com a senha do usuário no banco (no nosso caso, no mock).

Caso o e-mail e senha sejam válidos, é exibido uma mensagem de boas vindas (Welcome!):

E caso algum dos dois campos possuam algum dado inválido é exibido para o usuário (Invalid email or password):

Iniciando os testes

Vamos criar o arquivo de testes para o nosso component na mesma pasta em que ele está inserido. Por boas práticas, costumo nomear o arquivo de testes com o mesmo nome do component, seguido da extensão .spec.tsx (caso não esteja utilizando typescript como eu a extensão seria .spec.jsx).

Iniciando, vamos utilizar o método describe, onde passaremos como primeiro parâmetro uma string que normalmente é o nome do component testado. O segundo parâmetro é uma função callback que receberá nossos testes:

describe("LoginForm", () => {})

Os testes são escritos dentro das funções it ou test, os dois são funcionalmente idênticos, sendo que prefiro utilizar o it apenas por semântica, melhorando a legibilidade. A função também recebe dois parâmetros, onde o primeiro é a descrição do que deverá acontecer durante o teste e o segundo é mais um callback, mas dessa vez com o código do teste.

describe("LoginForm", () => {                // LoginForm...
    it("should render the login form", () => { // ...deve renderizar o formulário de login
        //code for test here
  });
})

Neste momento podemos começar testando a renderização dos elementos.

Renderizando a UI

O método render() realizará a renderização do componente. Ele recebe como parâmetro o componente e retorna um RenderResult que tem vários métodos e propriedades utilitários.

import { render } from "@testing-library/react";
import { LoginForm } from "../LoginForm";

describe("LoginForm", () => {
  it("should render the login form", () => {
    render(<LoginForm />);
  });
})

Capturando elementos no DOM

O objeto screen é utilizado para fazer consultas no DOM. Ele possui uma série de queries que farão a consulta no DOM conforme a necessidade e retornando o elemento escolhido.

//...imports
import { render, screen } from "@testing-library/react";

describe("LoginForm", () => {
  it("should render the login form", () => {
    render(<LoginForm />);

        const emailField = screen.getByLabelText("Email");
        const passwordField = screen.getByText("Password");
        const loginButton = screen.getByRole("button", { name: "Log in" });
  });
});

Foram apresentados três exemplos de queries dentre as diversas que podem ser utilizadas:

getByLabelText: Recomendado pela documentação oficial para buscar campos de formulários (no exemplo não utilizei esta query em todas as opções para ampliar a apresentação das possibilidades de uso);
getByText: Fora dos formulários, o conteúdo de texto é a principal forma de encontrar elementos. Este método é recomendado para localizar elementos não interativos (como divs, spans e parágrafos).
getByRole: Utilizado para consultar elementos pelo nome acessível dele (button, div, p, entre outros). Normalmente é utilizando com o objeto option {name: …}, evitando elementos indesejados.

Sugiro a leitura documentação com todas as queries neste link.

Hora de testar

Testando a renderização

Vamos agora finalmente testar se os elementos estão sendo renderizados. Para testar os valores é utilizada a função expect, ela utiliza funções matchers que realizam verificações entre o valor esperado e o valor recebido.

//...imports
import '@testing-library/jest-dom';

describe("LoginForm", () => {
  it("should render the login form", () => {
    render(<LoginForm />);

        const emailField = screen.getByLabelText("Email");
        const passwordField = screen.getByText("Password");
        const loginButton = screen.getByRole("button", { name: "Log in" });

        expect(emailField).toBeInTheDocument();
    expect(passwordField).toBeInTheDocument();
    expect(loginButton).toBeInTheDocument();
  });
});

Rodando o teste com os comandos abaixo, poderemos observar o resultado no terminal.

yarn test
ou
npm run test

PASS  src/components/LoginForm/LoginForm.spec.tsx
  LoginForm
    ✓ should render the login form (82 ms)

Test Suites: 1 passed, 1 total
Tests:       1 passed, 1 total
Snapshots:   0 total
Time:        3.01 s, estimated 4 s

💡 Não se esqueça de importar o módulo @testing-library/jest-dom para utilizar o mathcer toBeInDocument.

Veja mais sobre os Testing Library Custom Matchers.

Mais testes

Agora que sabemos que os elementos esperados estão sendo renderizados normalmente, iremos verificar o comportamento deles diante uma interação do usuário, e para isso utilizaremos o userEvent.

Testando o login bem sucedido

Nesse momento relembro que é necessário imaginar as ações que o usuário irá executar. Por tanto, para realizar o login o usuário primeiro insere os dados nos campos de email e password , por último ele clica no botão de Log In recebendo então a mensagem de boas vindas caso os dados estejam corretos ou, caso contrário, receberá uma mensagem de erro.

O método type emula a digitação pelo usuário, recebendo como primeiro parâmetro o elemento no qual será inserido o texto e como segundo parâmetro o texto propriamente dito. Ele retorna uma Promise portanto é necessário adicionar o await antes do userEvent e o async no início da função callback do teste.

await userEvent.type(emailField, userInput.email);
await userEvent.type(passwordField, userInput.password);

Com o formulário preenchido, utilizaremos o método click para realizar o clique no botão de login.

await userEvent.click(loginButton);

Agora podemos realizar a comparação entre os valores esperados e os valores recebidos:

// espera que o elemento com o texto "Welcome!" esteja no documento
expect(screen.getByText("Welcome!")).toBeInTheDocument();
// espera que o elemento com o texto "Invalid email or password" não seja encontrado, retornando null
expect(screen.queryByText("Invalid email or password")).toBeNull();

Observe que no primeiro expect é esperado que um elemento com o texto “Welcome!” esteja no documento, utilizando o já conhecido método getByText. Já no segundo foi utilizado o queryByText no lugar de getByText, isso por conta de que é esperado que o elemento não esteja no documento, e ao utilizarmos qualquer método iniciado com get e não for encontrado nenhum elemento será lançado um erro interrompendo o teste, já os métodos iniciados com query retornam null , possibilitando a continuação do teste.

Fincando dessa forma o nosso segundo teste:

//...imports
import userEvent from "@testing-library/user-event";

describe("LoginForm", () => {
  it("should render the login form", () => {
    ...
  });

    // deve exibir uma mensagem de boas vindas caso tenha sucesso no login
  it("should show an welcome message if login success", async () => {
    render(<LoginForm />);

    const emailField = screen.getByLabelText("Email");
    const passwordField = screen.getByText("Password");
    const loginButton = screen.getByRole("button", { name: "Log in" });

    const userInput = { email: "diego@test.com", password: "123456" };

    await userEvent.type(emailField, userInput.email);
    await userEvent.type(passwordField, userInput.password);
    await userEvent.click(loginButton);

    expect(screen.getByText("Welcome!")).toBeInTheDocument();
    expect(screen.queryByText("Invalid email or password")).toBeNull();
  });
});

PASS  src/components/LoginForm/LoginForm.spec.tsx
  LoginForm
    ✓ should render the login form (109 ms)
    ✓ should show an welcome message if login success (141 ms)

Test Suites: 1 passed, 1 total
Tests:       2 passed, 2 total
Snapshots:   0 total
Time:        2.6 s, estimated 3 s

Testando o login mal sucedido

O último teste que vamos escrever neste artigo é para caso o e-mail ou a senha inseridos pelo usuário sejam inválidos. A lógica será basicamente a mesma do teste anterior alternado somente a ordem das mensagens esperadas:

//...imports

describe("LoginForm", () => {
  it("should render the login form", () => {
    ...
  });

  it("should show an welcome message if login success", async () => {
    ...
  });

   // deve exibir uma mensagem de erro caso o login tenha falhado
  it("should show an error message if login failed", async () => {
    render(<LoginForm />);

    const emailField = screen.getByLabelText("Email");
    const passwordField = screen.getByText("Password");
    const loginButton = screen.getByRole("button", { name: "Log in" });

    const userInput = { email: "diego@test.com", password: "worngPassword" };

    await userEvent.type(emailField, userInput.email);
    await userEvent.type(passwordField, userInput.password);
    await userEvent.click(loginButton);

    expect(screen.getByText("Invalid email or password")).toBeInTheDocument();
    expect(screen.queryByText("Welcome!")).toBeNull();
  });
});

PASS  src/components/LoginForm/LoginForm.spec.tsx
  LoginForm
    ✓ should render the login form (89 ms)
    ✓ should show an welcome message if login success (166 ms)
    ✓ should show an error message if login failed (126 ms)

Test Suites: 1 passed, 1 total
Tests:       3 passed, 3 total
Snapshots:   0 total
Time:        2.388 s, estimated 3 s

Conclusão

Busquei neste artigo principalmente abrir a porta para o universo dos testes. Uma ideia para exercitar o que aprendeu aqui é clonando o repositório deste projeto e criar outros testes, como por exemplo testar o que ocorrerá caso o usuário não preencha algum dos campos quando houver um required.

Com este artigo, assim como com qualquer outro artigo que você ler, busque não se restringir somente ao que foi demonstrado, utilize os links auxiliares disponibilizados ao decorrer da explicação, explore, exercite e conheça melhor cada funcionalidade para aprimorar seu conhecimento.

Repositório do Projeto

React Tests - GitHub

ArchLinux config on WSL2 to developers

Diego Chueri — Mon, 21 Nov 2022 16:27:22 +0000

Versão em português

In the last few days, I needed to format my equipment again and I felt the need to have documentation to speed up this part of configuring my development environment. I use some apps in my day-to-day life that prevent me from using only Linux, for a while I used dual-boot, but the need to restart the PC for some quick code changes made me look for another alternative, in this case, WSL.

The initial idea was just to document to facilitate my configuration process, but as lemonade comes from lemon, I decided to share it with you here. I'm not going to sound deep about the WSL or the reasons for each choice, but I'm open to suggestions and dialogues with anyone interested.

If you don't know what WSL is or are looking for more information about it, follow the link to the official Microsoft documentation (numerous articles can be found by a quick search):

What is the Windows Subsystem for Linux?

Installing WSL

If you have not yet installed WSL on your Windows, enter the following command in Windows PowerShell:

wsl --install

Install WSL | Microsoft Learn

Windows Terminal

I prefer to use Windows Terminal for two main reasons: customization and taking advantage of some Linux commands. Installation is simple and can be done using the link below:

Windows Terminal - Microsoft Store Apps

Install Arch

This version of Arch that I use is very lightweight compared to other options (like Manjaro):

https://github.com/yuk7/ArchWSL

Just extract the files to a preferred folder and run the Arch file, which will start the installation.

Creating a user

Once the installation is complete, it's time to configure a user and make it the default at startup, avoiding using the root user. Just follow the commands below, remembering to replace {username} with the desired name:

echo "%wheel ALL=(ALL) ALL" > /etc/sudoers.d/wheel

useradd -m -G wheel -s /bin/bash {username}

passwd {username}

Now to set the created user as default, close Arch and open your terminal in the folder where the Arch.exe file is and enter the following command:

.\Arch.Exe config --default-user {username}

How to Setup | ArchWSL official documentation

Updating distro packages

Before updating we need to initialize pacman's keyring:

sudo pacman-key --init

And also perform the initial configuration of the keys with the:

sudo pacman-key --populate

sudo pacman -Sy archlinux-keyring

sudo pacman -Syu

pacman/Package signing - ArchWiki

Initialize keyring | ArchWSL official documentation (wsldl-pg.github.io)

Package managers

I will initially install the YARN and NPM managers:

sudo pacman -S yarn npm

As AUR manager I use Yay:

sudo pacman -S --needed git base-devel

Finally, with “Rust” package to use “cargo”:

sudo pacman -S rust

To install Yay it will be necessary to clone the repository, as after installation the files will no longer be used I choose to create a temporary folder to facilitate deletion later:

mkdir tmp

cd tmp

Now just clone the repository and build it with makepkg:

git clone https://aur.archlinux.org/yay.git

cd yay

makepkg -si

Jguer/yay: Yet another Yogurt - An AUR Helper written in Go (github.com)

Z Shell

Install ZSH:

yay -S zsh

Customizing the Terminal

Changing the terminal theme

Windows Terminal Themes has several themes ready for your terminal, just choose the theme of your choice and click on the “Get theme” button, and with that selected theme will be copied to your clipboard. My favorite theme is Dracula.

Just go back to the terminal, use the shortcut Ctrl + , to open the Configurations, and click on Open JSON file in the lower left corner.

After the last theme (themes are inside the "schemes" array), put a , and paste the chosen theme. Save and close the file.

Note: If you "break" the JSON file, while the terminal is open it may work normally, but when restarting it you will find an error similar to this. If this is tolerated, just click “OK”, open the JSON file again, check the syntax and save the file.

Return to the Settings screen, open the Arch profile, under “Additional settings” and click on “Appearance”. Now just change the “Color Scheme” to the desired option. Click “Save” and close the settings.

Customizing ZSH

To change the ZSH theme I use Powerlevel10k:

yay -S --noconfirm zsh-theme-powerlevel10k-git

echo 'source /usr/share/zsh-theme-powerlevel10k/powerlevel10k.zsh-theme' >>~/.zshrc

chsh -s /usr/bin/zsh

Restart the terminal.

Font

After installing Powerlevel10k, when you start the terminal again, a settings screen will appear where some symbols should be displayed:

If you are unable to view the displayed symbols, just install one of the calls Nerd Fonts and change the Arch profile font in “Additional Settings” > “Appearance” > “Font type”.

When you want to access the Powerlevel10k configuration screen again, just type:

p10k configure

Plugins

In my case, I usually use the following plugins:

ZSH Autosuggestions: which does an autocomplete based on my command history;
exa: serves as an alternative to “ls”; and
bat: alternative “cat”.

mkdir .zsh

git clone https://github.com/zsh-users/zsh-autosuggestions ~/.zsh/zsh-autosuggestions

cargo install bat exa

Open the .zshrc file in your preferred editor and add to the end of the file:

code .zshrc

source ~/.zsh/zsh-autosuggestions/zsh-autosuggestions.zsh
alias ls="exa --icons"
alias bat="bat --style-auto"

NVM

For managing node versions I use NVM:

curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.2/install.sh | bash

Docker

It is necessary to have Docker Desktop installed on Windows. With that, just type in the terminal:

yay -S docker

And finally, enable the Arch distro in the Resources of Docker Desktop.

And is this

Throughout the article, I tried to provide some useful links so that each one can perform the best configuration as appropriate. As said at the beginning, feel free to make suggestions, as well as indicate any errors that occurred during the process and also share your preferences with others.

Configurando o ArchLinux com WSL 2 para Devs

Diego Chueri — Mon, 21 Nov 2022 16:24:48 +0000

English version

Nos últimos dias eu precisei formatar novamente meu equipamento e senti a necessidade de ter uma documentação para agilizar essa parte de configuração do meu ambiente de desenvolvimento. Utilizo alguns apps no meu dia a dia que me impedem de utilizar somente o Linux, por um tempo utilizei o dual-boot, porém a necessidade de reiniciar o PC para algumas alterações rápidas em código me fizeram buscar outra alternativa, no caso o WSL.

A ideia inicial era somente documentar para facilitar o meu processo de configuração, mas como do limão surge a limonada, decidi compartilhar com vocês aqui. Não vou me apegar a explicações sobre o que é o WSL ou sobre os motivos de cada escolha, mas fico completamente aberto a sugestões e diálogos com quem possuir interesse.

Se você não sabe o que é o WSL ou busca mais informações a respeito segue o link com a documentação oficial da Microsoft (há também inúmeros artigos que podem ser encontrados por uma pesquisa rápida):

O que é o Subsistema do Windows para Linux

Instalando o WSL

Caso ainda não tenha instalado o WSL no seu Windows insira o seguinte comando no Windows PowerShell:

wsl --install

Instalar o WSL | Microsoft Learn

Windows Terminal

Eu prefiro utilizar o Windows Terminal por dois principais motivos: personalização e aproveitamento de alguns comandos Linux. A instalação é simples e pode ser feita pelo link abaixo:

Windows Terminal - Aplicativos Microsoft Store

Instalando o Arch

Essa versão do Arch que eu utilizo é bem leve se comparado a outras opções (como o Manjaro por exemplo):

https://github.com/yuk7/ArchWSL

Basta extrair os arquivos para uma pasta de preferência e executar o arquivo Arch que será iniciada a instalação.

Configurando um usuário

Feita a instalação é hora de configurar um usuário e torná-lo padrão na inicialização, evitando utilizar o usuário root. Basta seguir os comandos abaixo, lembrando de substituir {username} pelo nome de usuário desejado:

echo "%wheel ALL=(ALL) ALL" > /etc/sudoers.d/wheel

useradd -m -G wheel -s /bin/bash {username}

passwd {username}

Agora para definir o usuário criado como padrão, feche o Arch e abra o seu terminal na pasta onde está o arquivo Arch.exe e insira o comando a seguir:

.\Arch.exe config --default-user {username}

How to Setup | ArchWSL official documentation (wsldl-pg.github.io)

Atualizando os pacotes da distro

Antes de atualizar precisamos inicializar o keyring do pacman:

sudo pacman-key --init

E também realizar a configuração inicial das chaves com:

sudo pacman-key --populate

sudo pacman -Sy archlinux-keyring

sudo pacman -Syu

pacman (Português)/Package signing (Português) - ArchWiki (archlinux.org)

Initialize keyring | ArchWSL official documentation (wsldl-pg.github.io)

Gerenciadores de pacotes

Vou instalar incialmente os gerenciadores YARN e NPM:

sudo pacman -S yarn npm

Como gerenciador de AUR eu utilizo o Yay:

sudo pacman -S --needed git base-devel

Por fim, o pacote “Rust” para utilizar o “cargo”:

sudo pacman -S rust

Para instalar o Yay será necessário clonar o repositório, como após a instalação os arquivos não serão mais utilizados eu opto por criar uma pasta temporária para facilitar a exclusão posteriormente:

mkdir tmp

cd tmp

Agora basta clonar o repositório e fazer o build com o makepkg:

git clone https://aur.archlinux.org/yay.git

cd yay

makepkg -si

Jguer/yay: Yet another Yogurt - An AUR Helper written in Go (github.com)

Z Shell

Instalando o ZSH:

yay -S zsh

Personalizando o Terminal

Alterando o tema do terminal

O Windows Terminal Themes possui diversos temas prontos para o seu terminal, basta escolher o tema de sua preferência e clicar no botão “Get theme”, com isso o tema selecionado será copiado para a sua área de transferência. O meu tema preferido é o Dracula.

Basta agora voltar ao terminal, utilizar o atalho Ctrl + , para abrir as Configurações e clicar em Abrir arquivo JSON no canto inferior esquerdo.

Após o último tema (os temas estão dentro do array "schemes”), coloque uma , e cole o tema escolhido. Salve e feche o arquivo.

Obs.: Caso você “quebre” o arquivo JSON, enquanto o terminal estiver aberto ele pode funcionar normalmente, porém ao reiniciá-lo você encontrará algum erro parecido com este. Caso isso ocorra, apenas clique em “OK”, abra o arquivo JSON novamente, verifique a sintaxe e salve o arquivo.

Volte à tela de Configurações, abra o perfil do Arch, em “Configurações adicionais” clique em “Aparência”. Agora é só alterar o “Esquema de cores” para a opção desejada. Clique em “Salvar” e feche as configurações.

Alterando tema do ZSH

Para alterar o tema do ZSH eu utilizo o Powerlevel10k:

yay -S --noconfirm zsh-theme-powerlevel10k-git

echo 'source /usr/share/zsh-theme-powerlevel10k/powerlevel10k.zsh-theme' >>~/.zshrc

chsh -s /usr/bin/zsh

Reinicie o terminal.

Fonte

Após instalado o Powerlevel10k, quando iniciar o terminal novamente irá aparecer uma tela de configurações onde deverá ser visualizado alguns símbolos:

Caso você não esteja conseguindo visualizar os símbolos apresentados, basta instalar alguma das chamadas Nerd Fonts e alterar a fonte do perfil Arch em “Configurações adicionais” > “Aparência” > “Tipo de fonte”.

Quando quiser acessar novamente a tela de configuração do Powerlevel10k basta digitar:

p10k configure

Plugins

No meu caso, costumo utilizar os seguintes plugins:

ZSH Autosuggestions: que faz um autocomplete com base no meu histórico de comandos;
exa: serve como alternativa ao “ls”; e
bat: alternativa ao “cat”.

mkdir .zsh

git clone https://github.com/zsh-users/zsh-autosuggestions ~/.zsh/zsh-autosuggestions

cargo install bat exa

Abra o arquivo .zshrc no seu editor de preferência e adicione ao final do arquivo:

code .zshrc

source ~/.zsh/zsh-autosuggestions/zsh-autosuggestions.zsh
alias ls="exa --icons"
alias bat="bat --style-auto"

NVM

Para o gerenciamento de versões do node eu utilizo o NVM:

curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.2/install.sh | bash

Docker

É necessário possuir o Docker Desktop instalado no windows. Com isso, apenas digite no terminal:

yay -S docker

E por fim habilite a distro do Arch nas Resources do Docker Desktop.

E é isso

Ao decorrer do artigo, busquei disponibilizar alguns links úteis para que cada um consiga realizar a melhor configuração conforme for o caso. Como dito no início sinta-se livre para dar sugestões, assim como indicar algum erro que ocorreu durante o processo e bem como compartilhar suas preferências com os demais.