Deploy de React en VPS. Los 5 errores que me volvieron loco - Episodio 34

🔥 Si crees que hacer npm run dev es suficiente para que tu frontend se vea en producción, prepárate para aprender algunas lecciones dolorosas (pero necesarias).

 Los 5 errores a la hora de hacer un deploy de React en VPS. 🗓 Diario de un SaaS

Nunca he montado un frontend y para todo siempre hay una primera vez..

Pero montar un Frontend en React en el VPS y esperar que funcione a la primera es de ser muy optimista.

Así que para que no tengas que pasar por lo mismo que yo...

Aquí tienes  los 5 errores que me hicieron sudar, maldecir y aprender de verdad qué significa "subir a producción".

❌ Error 1: "La página no carga pero el servidor dice que todo está OK"

La terminal te dice "Server running on port 5173" y tú estás tan feliz.

Pero abres el navegador y ves... nada.

Pantalla blanca.

Qué pasaba: El puerto 5173, por donde corre el servidor de desarrollo de Vite, estaba bloqueado en el firewall del VPS.

Todo funcionaba internamente, pero el tráfico externo no entraba.

Solución: Abrir el puerto manualmente:

sudo firewall-cmd --add-port=5173/tcp --permanent
sudo firewall-cmd --reload

Y verificar con curl desde fuera que realmente responde.

❌ Error 2: Puertos ocupados y procesos duplicados

Cuando estás probando cosas rápido, abres varios terminales, matas un proceso, pero otro queda en background...

Y terminas con 5 procesos sirviendo React en puertos distintos.

Qué pasaba: vite, serve, npm run preview... todos abiertos al mismo tiempo.

Algunas respuestas llegaban, otras no, y el sistema estaba completamente inestable.

Solución:

• Localizar procesos activos con:

sudo lsof -i :5173

• Matar lo que no debería estar corriendo:

sudo kill -9 <PID>

• Crear un alias o script para levantar solo el proceso correcto según el entorno.

❌ Error 3: React no se renderiza porque el div#root no existe

Este fue doloroso.

Todo parecía estar bien, pero no se renderizaba nada.

Qué pasaba: En producción, a veces se pierde el div id="root" en el index.html, o el HTML está corrupto por error de deploy.

Solución: Verificar manualmente que el index.html tenga el elemento correcto:

<div id="root"></div>

Y que el main.jsx o main.tsx monte la app en ese mismo id.

❌ Error 4: Problemas con rutas en producción y base en vite.config.js

Todo funcionaba en local. Pero cuando cargaba una ruta distinta a /, boom: 404.

Qué pasaba: El server (NGINX o Apache) no sabía manejar las rutas del frontend SPA.

Solución:

• Asegurar que el vite.config.js tiene:

base: '/'

• Configurar NGINX para redirigir correctamente:

location / {
    try_files $uri /index.html;
}

❌ Error 5: Archivos .js y .css cargando mal porque serve no maneja rutas correctamente

La app cargaba, pero sin estilo, sin interacción... como si le hubieran quitado el alma.

Qué pasaba: Usaba serve para levantar la carpeta dist, pero no sirve bien en todos los entornos porque no gestiona bien las rutas de archivos.

Solución: Pasarse a NGINX y servir dist/ como archivos estáticos, con fallback a index.html.

🔄 Conceptos Relacionados que aprendí (a golpes)

🔸 Firewall del VPS

No basta con que algo esté “corriendo”.

Si el puerto está bloqueado, nadie lo verá desde fuera.

Así que usar bien firewalld es clave.

🔸 Server vs Build

El servidor de desarrollo (vite dev) no es para producción.

Para producción se necesita npm run build y servir el resultado con un servidor estático como NGINX.

🔸 Base paths y rutas

En SPAs, las rutas internas son gestionadas por React, pero el servidor debe estar preparado para reenviar cualquier ruta al index.html.

Si no, errores garantizados.

🔸 Proceso de build

El build de Vite genera archivos con hashes en el nombre (app.4f1c.js).

Si no se sirven correctamente o si el base está mal, esos archivos no se encuentran y la app rompe.

💡 Lecciones Aprendidas

🔹 Leer los logs es la mitad del trabajo

Los errores estaban ahí todo el tiempo. Solo había que prestar atención.

Por lo que un 404, un warning, son pistas.

Nunca los ignores.

🔹Al montar el frotend en servidor hay que tener en cuenta siempre cositas.

En local no tienes firewalls, rutas externas, ni servidores con permisos restringidos.

Cada entorno es un mundo.

🔹 Probar todo como si fueras un usuario externo

No basta con levantar el server y mirarlo en el navegador.

Hay que hacer curl desde fuera, probar rutas, recargar con F5, abrir en incógnito, probar desde el móvil...

🧠 Reflexión Final

Cada error me enseñó algo nuevo sobre servidores, sobre producción, y sobre no dar nada por hecho.

Es como preparar una cena para amigos.

Todo está listo, huele bien, luces bajas…

Hasta que te das cuenta de que no enchufaste el horno.

O que compraste todo menos el pan.

Son detalles, sí.

Pero te arruinan la velada.

Ahora tengo un checklist con estos errores que revisaré cada vez antes de desplegar.

Porque si algo puede salir mal... saldrá.

Pero al menos ya sé por dónde empezar a mirar.

🎯 A por la siguiente aventura

💬 ¿Tú también has sufrido alguno de estos errores de deploy?

¿Cuál fue el más absurdo?

Cuéntamelo en los comentarios y hagamos catarsis juntos.

Si te duele, ¡ríete! 😅

 

Si quieres conocer otros artículos parecidos a Deploy de React en VPS. Los 5 errores que me volvieron loco - Episodio 34 puedes visitar la categoría Proyecto-IA.