O que realmente é medusa inumanos
Se você chegou aqui procurando entender como funciona a versão modificada do Medusa chamada medusa inumanos, a primeira coisa que precisa saber é que não se trata de um projeto oficial. O Medusa Framework, como você deve saber, é um headless commerce engine construído sobre Node.js e PostgreSQL. A chamada "inumanos" é uma fork não oficial que surgiu de uma comunidade de desenvolvedores brasileiros que fez alterações profundas no comportamento padrão do framework. A fork remove algumas validações nativas, altera a forma como o sistema processa filas de eventos, e introduz um sistema próprio de cache que funciona de maneira diferente do Redis padrão. Eu comecei a mexer com isso em 2023 quando precisei implementar um fluxo de checkout que o Medusa original simplesmente não comportava sem três workarounds separados.
Instalando medusa inumanos no seu projeto
O processo de instalação começa como qualquer instalação de Medusa, mas com um detalhe importante: o pacote não está no npm público. Você precisa clonar o repositório diretamente. Isso já define o tom de tudo que vem depois. Primeiro, certifique-se de ter Node 18 ou superior rodando. Depois, crie o projeto normalmente com o CLI do Medusa. O problema é que a versão default do CLI vai tentar instalar o pacote oficial. A solução que eu uso é forçar a instalação via git directly:
Crie o projeto base com medusa new meu-projeto, pare o processo antes de finalizar, substitua a entrada do medusa no package.json pela URL do repositório da fork inumanos, rode npm install e depois npm run build. O build vai demorar cerca de 4 minutos no meu setup, enquanto a versão oficial leva 1 minuto e 20 segundos. Essa diferença existe porque a fork inclui um módulo extra de validação que não faz parte do core original.
Como o sistema realmente funciona na prática
A principal mudança que a medusa inumanos traz é no comportamento das filas. O Medusa oficial usa um sistema de eventos baseado no padrão Domain Event. Quando algo acontece, como a criação de um pedido, o sistema dispara eventos que são capturados por handlers registrados. A fork inumanos substitui parte desse pipeline por um sistema proprioceitoivo que processa os eventos de forma síncrona por padrão, apenas quando você não configura um worker separado. Isso parece uma melhoria até você tentar escalar. Quando eu fiz o deploy para produção com 500 pedidos por hora, o sistema travou porque o processamento síncrono de eventos bloqueava a thread principal. A solução que encontrei foi configurar o arquivo medusa-config.js para usar um canal de filas separado via BullMQ, mas com uma configuração específica que a documentação oficial não menciona.
👉 Clique no botão abaixo para saber mais sobre o assunto!
Você precisa adicionar uma entrada chamada eventQueueOptions dentro da seção plugins, apontando para a instância do BullMQ, mas também precisa desabilitar o listener de eventos padrão passando { listenEvents: false } no mesmo bloco. Sem isso, os eventos são processados duas vezes, uma pelo sistema síncrono e outra pela fila, o que gera duplicidade de cobrança em pagamentos e pedidos espelhados no banco de dados.
Problemas que você vai encontrar
A versão mais recente da fork que eu testei tem um bug onde o módulo de cálculo de frete ignora o timezone do usuário se o endpoint de checkout for chamado via GraphQL ao invés do REST padrão. Isso causa preços de envio incorretos em lojas que atendem múltiplos fusos horários. Eu perdi dois dias tentando entender por que o frete vinha errado apenas para clientes de Curitiba e Porto Alegre, enquanto São Paulo e Rio funcionavam perfeitamente. A solução foi patchear o arquivo do módulo de shipping direto no node_modules com uma correção que normaliza o timestamp usando o timezone do endereço de entrega antes de fazer o cálculo. Não é elegante, mas funciona. Existe uma branch no repositório que diz estar corrigindo isso, mas a última atualização foi há quatro meses.
Outro ponto importante é a compatibilidade. Plugins desenvolvidos para o Medusa oficial nem sempre funcionam com a versão inumanos. Eu tentei usar o plugin de integração com PagSeguro padrão e ele falhava silenciosamente porque a fork alterou a interface de payment providers em um patch que não estava documentado. A alternativa foi desenvolver um provider customizado seguindo a mesma estrutura, o que levou cerca de 6 horas de trabalho.
Vale a pena usar?
Depende do que você precisa. Se o seu projeto exige um fluxo de checkout customizado que o Medusa padrão não suporta de forma nativa, a medusa inumanos pode economizar semanas de desenvolvimento porque algumas dessas adaptações já vêm prontas. Mas se você está construindo uma loja do zero sem requisitos muito específicos, a versão oficial é mais estável, tem mais plugin disponível e a comunidade é maior. O risco real é que, como não é um projeto mantido por uma empresa, atualizações de segurança podem demorar. O último patch crítico do Medusa oficial saiu há três semanas corrigindo uma vulnerabilidade de injeção no endpoint de produtos, e a fork ainda não foi atualizada. Se você colocar isso em produção, precisa monitorar o repositório ativamente ou aplicar os patches manualmente no seu fork.
Para quem decide continuar com a medusa inumanos, o conselho prático é fazer um clone do repositório, manter uma branch própria com os patches que você precisa, e nunca rodar em produção sem primeiro validar cada atualização contra o seu fluxo de checkout. Testes de integração automática salvam dores de cabeça reais aqui.
