WooCommerce ou Medusa: qual usar na sua loja virtual?

Se você cria loja virtual, provavelmente está acostumado com o WooCommerce. Neste vídeo eu comparo o WooCommerce com o Medusa, explico em que momento usar cada um e instalo o Medusa do zero na máquina, com o storefront em Next.js e o plugin de Claude Code para ajudar no desenvolvimento.

A primeira dúvida que costuma aparecer é: com inteligência artificial no meio, ainda vale a pena usar WooCommerce? Vale sim, e depende do projeto. Em alguns casos o WooCommerce continua sendo a melhor escolha. Em outros, o Medusa atende bem melhor. A ideia aqui não é dizer que um é melhor que o outro, é saber escolher a ferramenta certa para cada tipo de loja.

O que é o WooCommerce?

O WooCommerce é um plugin de loja virtual que você instala dentro do WordPress. Ele transforma o site WordPress em uma loja completa, com produtos, carrinho e checkout. É open source, muito usado, e continua sendo uma solução sólida para a maioria das lojas.

Com IA, dá para tirar ainda mais proveito dele. Você consegue criar um tema personalizado do zero, em HTML, CSS, JavaScript e PHP, seguindo boas práticas e usando o Context7 para consultar a documentação na hora. O resultado é uma loja que carrega mais rápido, porque usa só o que precisa, sem Elementor e sem soluções prontas carregando funcionalidades desnecessárias no plano de fundo.

O que é o Medusa?

O Medusa é uma plataforma de e-commerce open source, também headless por natureza. A grande diferença para o WooCommerce é que o Medusa já nasce separando o back-end do front-end: ele é só o back-end. Não vem com uma camada visual pronta para o cliente final.

Isso significa que, para montar a loja, você usa o Medusa no back-end e uma solução separada no front-end, normalmente o Next.js. Por ser open source, você tem o código todo e pode customizar o que quiser.

Ele é mais robusto e mais completo que o WooCommerce, com um nível de personalização maior. Em compensação, exige mais estrutura para rodar.

WooCommerce ou Medusa: qual usar?

A escolha depende do tipo de loja. Este é o resumo:

Situação	Recomendação
Loja simples, sem muita personalização, fácil de manter	WooCommerce
Loja que precisa de front-end moderno mas mantém o painel do WooCommerce	WooCommerce headless (back-end no WordPress, front-end em Next.js)
Loja robusta, com produtos personalizáveis, muitos itens e alta escala	Medusa

O WooCommerce ganha na simplicidade: instalação e manutenção mais fáceis, painel já conhecido pelo cliente. O Medusa ganha quando a loja é maior, tem produtos muito personalizáveis e precisa de mais processamento.

E o WooCommerce headless?

Existe um caminho do meio. Se o cliente já usa o WooCommerce e está acostumado com o painel para cadastrar produtos, mas você quer uma vitrine diferente e mais rápida, dá para usar o WooCommerce só como back-end e montar o front-end em Next.js, consumindo a API do WordPress. É o mesmo conceito de headless que mostrei no vídeo anterior sobre WordPress.

O que preciso ter instalado para rodar o Medusa?

O Medusa é um servidor Node.js com um painel de administração, mais o storefront opcional em Next.js. Antes de instalar, confira os pré-requisitos:

• Node.js. Versão 20 ou superior. Se você for usar o storefront Next.js, use a versão 24 LTS ou inferior.
• PostgreSQL. O Medusa só funciona com PostgreSQL. Ele não aceita MySQL, então mesmo que você já tenha MySQL na máquina (como quem usa WooCommerce costuma ter), vai precisar instalar o PostgreSQL.
• Git CLI. Necessário para o processo de criação do projeto.

Confira sua versão do Node com:

node -v

Instalando o PostgreSQL

Baixe o instalador do PostgreSQL no site oficial e siga o assistente, avançando as etapas. Ele vai pedir uma senha para o banco de dados: defina e guarde, porque você vai usar na hora de conectar o Medusa. A porta pode ficar no padrão 5432.

No Windows, depois de instalar, dá para confirmar que o serviço está rodando pelo PowerShell:

Get-Service -Name postgresql*

Como criar o projeto Medusa?

Com Node, PostgreSQL e Git prontos, crie uma pasta para o projeto e rode o comando de criação. Dá para usar npm ou yarn:

mkdir medusa
cd medusa
npx create-medusa-app@latest my-medusa-store

Durante a instalação, o assistente faz três perguntas importantes:

1. Quer instalar o storefront em Next.js? Responda que sim. Essa é a base do front-end (o Medusa sozinho é só o back-end). Ela vem como um esqueleto pronto para você começar a mexer.
2. Quer instalar o plugin do Medusa para o Claude Code? Responda que sim também. Ele adiciona toda a documentação do Medusa dentro do Claude Code, o que deixa a IA muito mais precisa ao mexer nessa tecnologia.
3. Dados do PostgreSQL. Ele pede o usuário e o nome do banco. Informe o que você configurou na instalação. O Medusa então conecta e cria o banco automaticamente.

Se a instalação parar com erro de dependências, rode npm install na pasta do projeto e tente de novo. Aconteceu comigo na gravação, e na segunda tentativa funcionou.

Ao final, o painel abre no navegador e pede para criar uma conta de administrador. Depois do login, você cai no painel do Medusa, com pedidos, produtos (já vêm alguns cadastrados de exemplo), coleções, categorias, inventário, clientes, promoções, campanhas, preços e configurações.

Como subir o back-end e o front-end?

O projeto criado tem uma pasta apps com o back-end e o front-end separados. Você sobe cada um em um terminal.

Back-end:

cd apps/backend
npm run dev

Front-end (storefront):

cd apps/storefront
npm run dev

E se der erro de porta em uso?

É comum o storefront reclamar que a porta já está sendo usada por outra aplicação que você tem aberta. Para resolver, mude a porta no package.json do storefront, trocando o valor no script de dev. Se a nova porta também estiver ocupada, tente outra até subir (na gravação eu passei por 8001 e fechei em 8081).

Como usar o Claude Code para desenvolver a loja?

Dentro do projeto gerado, na pasta my-medusa-store, existe um CLAUDE.md que aponta para um AGENTS.md com a estrutura de diretórios e a documentação. É por isso que o Claude Code precisa ser executado dentro dessa pasta: é lá que ele encontra o contexto do projeto.

Rodando o Claude Code ali, você dá comandos tanto para o back-end quanto para o front-end. O projeto ainda traz orientações de plugins que você pode instalar no Claude Code para melhorar as boas práticas, tanto do lado do servidor quanto do storefront. Com isso, dá para pedir para a IA adicionar telas, opções e melhorias na loja com a documentação sempre à mão.

Onde hospedar?

Para colocar no ar, dá para usar a Hostinger, que instala aplicações Node de forma simples. O Medusa também tem uma oferta própria de hospedagem, o Medusa Cloud, mas para desenvolver na máquina e depois subir num servidor comum, você não precisa dele.

Conclusão

O Medusa é uma alternativa ao WooCommerce para quando a loja precisa de algo mais robusto: um framework em Node para construir uma loja virtual profissional do zero, com mais personalização e mais capacidade de processamento. O WooCommerce continua ótimo para lojas mais simples e para quem quer manter o painel do WordPress. Saber escolher entre os dois é o que faz a diferença no projeto.