CORS no React travou sua API? Como usar proxy para resolver

O que é o erro de CORS e por que ele acontece no React

Quando desenvolvemos aplicações modernas utilizando bibliotecas de interface como o React, é comum esbarrarmos em uma mensagem vermelha no console do navegador informando sobre um bloqueio de CORS. Na prática, CORS significa Compartilhamento de Recursos entre Origens Diferentes (Cross-Origin Resource Sharing). Trata-se de um mecanismo de segurança implementado pelos navegadores modernos para impedir que sites maliciosos leiam dados sensíveis de outros domínios sem autorização prévia.

Isso acontece porque o seu aplicativo React roda geralmente em uma porta local específica, como a 3000, enquanto a sua API de backend está rodando em outra porta ou domínio, como a 5000. Para o navegador, portas diferentes significam origens diferentes, o que aciona o alarme de segurança. Para entender melhor como o tráfego HTTP funciona nesses cenários, vale a pena revisar conceitos fundamentais sobre como depurar cabeçalhos CORS em APIs Express com o cURL diretamente pelo terminal.

Muitos desenvolvedores iniciantes tentam resolver esse problema alterando o código do frontend ou instalando extensões no navegador que desativam a segurança. No entanto, essas soluções são paliativas e não funcionam quando o sistema vai para o ambiente de produção. A melhor abordagem durante a fase de desenvolvimento é enganar o navegador criando uma ponte segura conhecida como proxy.

Como funciona um servidor proxy para contornar o CORS

Na engenharia de software, um proxy atua como um intermediário entre o cliente (o seu navegador) e o servidor final (a sua API). Quando configuramos um proxy no ambiente de desenvolvimento do React, o navegador passa a enviar as requisições para o próprio servidor de desenvolvimento do frontend, que por sua vez repassa o pedido para a API real.

Como o navegador está conversando apenas com o servidor de desenvolvimento local na mesma porta, ele não enxerga nenhuma diferença de origem e não bloqueia a comunicação. Na prática, isso significa que o CORS deixa de existir durante os testes locais, pois a barreira do navegador é contornada de forma totalmente transparente e segura.

Essa estratégia é extremamente útil quando você não tem acesso imediato ao código do backend para liberar os domínios. Em ambientes de infraestrutura mais robustos, técnicas semelhantes são aplicadas em servidores web, conforme explicamos no guia sobre como depurar e resolver cabeçalhos CORS no Nginx de maneira definitiva.

Passo a passo para configurar o proxy no Vite

A maioria dos projetos React atuais utiliza o Vite como ferramenta de construção e servidor de desenvolvimento devido à sua velocidade impressionante. Para configurar um proxy no Vite e evitar qualquer dor de cabeça com bloqueios de origem, siga o procedimento abaixo.

1. Abra o arquivo de configuração principal do seu projeto, chamado vite.config.js na raiz da pasta.
2. Localize o objeto de configuração do servidor (server) e adicione a propriedade proxy conforme o exemplo abaixo.
3. Salve o arquivo e reinicie o seu servidor de desenvolvimento executando o comando de inicialização no terminal.

Veja abaixo um exemplo prático de como estruturar essa configuração dentro do seu arquivo JavaScript:

import { defineConfig } from 'vite';import react from '@vitejs/plugin-react';export default defineConfig({  plugins: [react()],  server: {    proxy: {      '/api': {        target: 'https://api.exemplo.com',        changeOrigin: true,        rewrite: (path) => path.replace(/^
/, '')      }    }  }});

Como configurar o proxy em projetos legados com Webpack

Se a sua aplicação React mais antiga utiliza o Webpack (muitas vezes gerada pelo antigo Create React App), a configuração do proxy é feita de uma maneira ligeiramente diferente, mas com o mesmo objetivo prático de mascarar a origem das requisições.

Nesse cenário, você não precisa mexer em arquivos de configuração complexos do Webpack se estiver usando o Create React App. Basta abrir o arquivo package.json na raiz do seu projeto e adicionar uma propriedade simples apontando para o endereço da sua API de backend.

Essa linha avisa o servidor embutido para redirecionar todas as chamadas desconhecidas para o servidor externo. Contudo, lembre-se de que essa facilidade funciona apenas no modo de desenvolvimento local e será ignorada quando você gerar o pacote final para publicação.

Identificando e resolvendo requisições de pré-voo (Preflight)

Um dos maiores enigmas para quem está começando a lidar com CORS é a famosa requisição OPTIONS, também conhecida como pré-voo. Sempre que o seu código faz uma requisição complexa — como enviar dados no formato JSON usando o método POST —, o navegador envia primeiro um pedido do tipo OPTIONS para perguntar ao servidor se ele aceita aquele tipo de comunicação.

Se o seu servidor backend responder com um erro ou não aceitar o método OPTIONS, o navegador bloqueia imediatamente a requisição principal de envio de dados. Para inspecionar essas mensagens ocultas e entender exatamente o que está falhando na camada de rede, você pode utilizar ferramentas avançadas de monitoramento, como as técnicas descritas no artigo sobre como inspecionar conexões e mensagens no navegador para rastrear o fluxo de dados.

Portanto, ao depurar um erro persistente, abra sempre a aba de Rede (Network) das ferramentas de desenvolvedor do seu navegador, filtre pelas requisições do tipo Fetch/XHR e clique no pedido que apareceu em vermelho para analisar os cabeçalhos de resposta enviados pelo servidor.

Conclusão e boas práticas para o ambiente de produção

O uso de servidores proxy durante o desenvolvimento frontend com React é uma mão na roda para manter o fluxo de trabalho ágil, sem que a equipe precise perder horas ajustando configurações de servidores remotos apenas para testar uma interface local.

No entanto, nunca é demais lembrar que o proxy de desenvolvimento resolve apenas o seu problema na sua máquina. Quando a aplicação for publicada em um servidor de produção, a comunicação ocorrerá diretamente entre o domínio real do usuário e a API, tornando obrigatório o ajuste correto dos cabeçalhos CORS no servidor backend.