Errores de CORS en React: Cómo usar un proxy para resolverlo

Qué es el error de CORS y por qué ocurre en React

Cuando desarrollamos aplicaciones modernas utilizando librerías de interfaz como React, es común tropezar con un mensaje rojo en la consola del navegador informando sobre un bloqueo de CORS. En la práctica, CORS significa Intercambio de Recursos de Origen Cruzado (Cross-Origin Resource Sharing). Es un mecanismo de seguridad implementado por los navegadores modernos para evitar que sitios maliciosos lean datos sensibles de otros dominios sin autorización previa.

Esto sucede porque tu aplicación de React suele ejecutarse en un puerto local específico, como el 3000, mientras que tu API de backend se ejecuta en otro puerto o dominio, como el 5000. Para el navegador, diferentes puertos significan diferentes origenes, lo que activa la alarma de seguridad. Para comprender mejor cómo funciona el tráfico HTTP en estos escenarios, vale la pena revisar conceptos fundamentales sobre cómo depurar cabeceras CORS en APIs Express con cURL directamente desde la terminal.

Muchos desarrolladores principiantes intentan resolver este problema alterando el código del frontend o instalando extensiones en el navegador que desactivan la seguridad. Sin embargo, estas soluciones son temporales y no funcionan cuando el sistema pasa al entorno de producción. El mejor enfoque durante el desarrollo es engañar al navegador creando un puente seguro conocido como proxy.

Cómo funciona un servidor proxy para sortear el CORS

En la ingeniería de software, un proxy actúa como intermediario entre el cliente (tu navegador) y el servidor final (tu API). Cuando configuramos un proxy en el entorno de desarrollo de React, el navegador comienza a enviar solicitudes al propio servidor de desarrollo del frontend, que a su vez reenvía la petición a la API real.

Como el navegador solo está hablando con el servidor de desarrollo local en el mismo puerto, no ve ninguna diferencia de origen y no bloquea la comunicación. En la práctica, esto significa que el CORS deja de existir durante las pruebas locales, ya que la barrera del navegador se elude de forma totalmente transparente y segura.

Esta estrategia es sumamente útil cuando no tienes acceso inmediato al código del backend para liberar dominios. En entornos de infraestructura más robustos, se aplican técnicas similares en servidores web, tal como explicamos en nuestra guía sobre cómo depurar y resolver cabeceras CORS en Nginx de forma definitiva.

Guía paso a paso para configurar el proxy en Vite

La mayoría de los proyectos actuales de React utilizan Vite como herramienta de construcción y servidor de desarrollo debido a su impresionante velocidad. Para configurar un proxy en Vite y evitar dolores de cabeza con bloqueos de origen, sigue el procedimiento a continuación.

1. Abre el archivo de configuración principal de tu proyecto, llamado vite.config.js en la raíz de la carpeta.
2. Localiza el objeto de configuración del servidor (server) y añade la propiedad proxy según el ejemplo siguiente.
3. Guarda el archivo y reinicia tu servidor de desarrollo ejecutando el comando de inicio en la terminal.

Consulta a continuación un ejemplo práctico de cómo estructurar esta configuración dentro de tu archivo JavaScript:

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

Cómo configurar el proxy en proyectos heredados con Webpack

Si tu aplicación de React más antigua utiliza Webpack (a menudo generada por el antiguo Create React App), la configuración del proxy se realiza de manera ligeramente diferente, pero con el mismo objetivo práctico de enmascarar el origen de las solicitudes.

En este escenario, no necesitas modificar archivos complejos de configuración de Webpack si estás usando Create React App. Simplemente abre el archivo package.json en la raíz de tu proyecto y añade una propiedad simple que apunte a la dirección de tu API de backend.

Esta línea le indica al servidor integrado que redirija todas las llamadas desconocidas al servidor externo. Sin embargo, ten en cuenta que esta comodidad solo funciona en modo de desarrollo local y se ignorará cuando generes el paquete final para producción.

Identificando y resolviendo solicitudes de sondeo previo (Preflight)

Uno de los mayores enigmas para quienes comienzan a lidiar con CORS es la famosa solicitud OPTIONS, también conocida como preflight. Cada vez que tu código realiza una solicitud compleja, como enviar datos en formato JSON usando el método POST, el navegador envía primero una petición de tipo OPTIONS para preguntar al servidor si acepta ese tipo de comunicación.

Si tu servidor backend responde con un error o no acepta el método OPTIONS, el navegador bloquea inmediatamente la solicitud principal de envío de datos. Para inspeccionar estos mensajes ocultos y entender exactamente qué está fallando en la capa de red, puedes utilizar herramientas de monitoreo avanzadas, como las técnicas descritas en el artículo sobre cómo inspeccionar conexiones y mensajes en el navegador para rastrear el flujo de datos.

Por lo tanto, al depurar un error persistente, abre siempre la pestaña de Red (Network) de las herramientas de desarrollador de tu navegador, filtra por peticiones de tipo Fetch/XHR y haz clic en la solicitud que apareció en rojo para analizar las cabeceras de respuesta enviadas por el servidor.

Conclusión y buenas prácticas para el entorno de producción

El uso de servidores proxy durante el desarrollo frontend con React es una excelente herramienta para mantener el flujo de trabajo ágil, sin que el equipo pierda horas ajustando configuraciones de servidores remotos solo para probar una interfaz local.

Sin embargo, nunca está de más recordar que el proxy de desarrollo solo soluciona tu problema en tu máquina. Cuando la aplicación se publique en un servidor de producción, la comunicación ocurrirá directamente entre el dominio real del usuario y la API, haciendo obligatorio configurar correctamente las cabeceras CORS en el servidor backend.