Construindo um Cliente de API Desktop com Electron e React (e as armadilhas do caminho)
11/12/2025
Sou desenvolvedor há mais de 16 anos e, embora meu dia a dia envolva stacks robustas como Java e Angular, decidi explorar o desenvolvimento desktop moderno usando tecnologias web. O objetivo era simples: criar o ApiTester, um cliente HTTP leve (alternativa ao Postman, que se tornou pesado e cheio de funcionalidades que não uso) para testar endpoints REST de forma rápida.
O projeto combina Electron, React, TypeScript e Vite. Parece a combinação perfeita no papel, mas colocar isso para rodar em produção — especialmente cross-platform — tem suas nuances.
A Stack
Não queria usar boilerplate antigo. Escolhi ferramentas que prezam pela performance:
- Vite: O tempo de inicialização do servidor de desenvolvimento é instantâneo. Comparado ao Webpack, a diferença é brutal.
- React + TypeScript: Tipagem estática é inegociável para mim. Como estou lidando com Requisições e Respostas HTTP complexas, interfaces bem definidas evitam a maioria dos bugs de runtime.
- Electron Builder: O padrão de mercado para empacotamento.
- Lucide React & React18-JSON-View: Para manter a UI limpa e a visualização dos payloads legível.
O Problema da Arquitetura (ARM vs x64)
Desenvolver em um ambiente e distribuir para outro sempre gera atrito. Meu ambiente de desenvolvimento é um Mac com Apple Silicon (arquitetura ARM64).
Ao rodar o primeiro build para Windows, o script padrão gerou um executável que, ao ser aberto em um PC Windows comum, exibia o erro: "Este aplicativo não pode ser executado em seu PC".
O motivo? O electron-builder, por padrão, infere a arquitetura da máquina de build. Ele gerou um binário win-arm64. A maioria dos desktops Windows no mundo corporativo ainda é x64 (Intel/AMD).
A solução não é mágica, é configuração explícita. Tive que alterar o package.json para forçar o target correto e o instalador NSIS:
JSON
"win": {
"icon": "icon.ico",
"target": [
{
"target": "nsis",
"arch": ["x64"]
}
]
}
Sem isso, você está essencialmente entregando um software incompatível para 90% dos usuários de Windows.
O Desafio do CORS e IPC
Outro ponto técnico relevante: em uma aplicação Electron, o frontend (React) não deve fazer chamadas HTTP diretas para APIs externas da mesma forma que um site faz, ou você esbarrará em bloqueios de CORS.
A abordagem correta, que estou implementando, utiliza o IPC (Inter-Process Communication). O React envia um sinal, e o Main Process (que roda em Node.js e não tem as restrições de sandbox do navegador) executa a chamada via Axios e devolve os dados.
O Código
O projeto é Open Source. Se você quer ver como configurei o Vite com Electron ou precisa de uma base para criar suas próprias ferramentas de desktop, o código está disponível no GitHub.
Nada de overengineering, apenas o necessário para funcionar.
