Erro ao instalar dependências no VTEX IO: expect incompatível com Node.js

Durante a criação de um novo app no VTEX IO, ao rodar npm install ou yarn, me deparei com o seguinte erro:

error: react3.x builder failed to install dependencies through yarn
yarn errors:
expect@30.0.3: The engine "node" is incompatible with this module. Expected version "^18.14.0 || ^20.0.0 || ^22.0.0 || >=24.0.0". Got "16.20.2"
Found incompatible module. vtex.builder-hub@0.309.0

Esse erro ocorre porque, ao instalar as dependências do app, o ambiente VTEX (que roda com Node.js 16.20.2) tenta baixar uma versão do expect, jest e pretty-format que requerem uma versão mais recente do Node (v18+). Isso quebra a instalação, especialmente ao usar o builder react3.x.

✅ Solução

Para resolver isso, você pode forçar versões compatíveis das dependências que exigem Node mais novo. Basta instalar manualmente versões antigas e fixá-las no package.json com a chave resolutions.

1. Instale as versões compatíveis:

yarn add --dev jest@26.6.3 expect@26.6.2 pretty-format@26.6.2

2. Adicione no react/package.json a seção abaixo:

"resolutions": {
  "jest": "26.6.3",
  "expect": "26.6.2",
  "pretty-format": "26.6.2"
}

Isso força o Yarn a resolver e instalar essas versões, evitando o erro causado pela incompatibilidade com o Node 16.

Por que essas versões?

• jest@26.6.3 e seus pacotes auxiliares ainda são compatíveis com Node 16.
• A VTEX IO ainda roda seus builders em Node.js 16, então versões mais recentes (v30+) quebram a instalação.

Se você estiver usando VTEX IO e enfrentando problemas ao instalar dependências, sempre confira a compatibilidade de versões com o Node usado pela plataforma (atualmente 16.x).