Cómo publicar React con Vite y evitar el 404 al recargar

Una web React que ves en localhost todavía depende de tu ordenador. Si Vite genera archivos estáticos y tu aplicación no necesita un servidor propio, puedes construir esos archivos y publicarlos desde Git. No necesitas mantener abierto el servidor de desarrollo.

Este recorrido utiliza un ejemplo original React y Vite con licencia MIT. La demo publicada tiene dos rutas: la portada y /about. Incluye una imagen propia, CSS y una variable pública de construcción. No implementa login, pagos, API ni base de datos.

Si has creado una web Astro con contenido Markdown, consulta la publicación estática desde Git, con rutas y canonical comprobados en una demo real.

Si la interfaz React se carga pero sus peticiones a la API fallan al publicarla, sigue el diagnóstico de frontend y API en producción.

Comprueba qué has creado con la IA

Busca package.json y revisa sus scripts. En este ejemplo, build ejecuta Vite y genera dist. React no determina por sí solo el tipo de alojamiento: una interfaz que llama a Supabase, una API o un servidor necesita también esos servicios y sus credenciales correctamente configuradas.

No cambies una aplicación con backend a «estática» eliminando dependencias. Consulta qué alojamiento necesita una web creada con IA si no sabes qué parte ejecuta el navegador y qué parte necesita servidor. Esta receta tampoco demuestra soporte de renderizado en servidor de Next.js.

Prepara un repositorio reproducible

Haz un fork o copia el ejemplo en tu cuenta GitHub, conservando la licencia. Incluye package.json, package-lock.json, index.html, src, public y la configuración de Vite. El lockfile permite que npm ci instale las versiones registradas; no equivale a actualizar dependencias automáticamente.

El ejemplo requiere Node 22.19.0 o posterior. Construye primero en tu equipo:

npm ci
npm run build

Comprueba que aparece dist/index.html y que los archivos de CSS y JavaScript están en dist/assets. npm run dev y npm run preview sirven para trabajar y comprobar localmente; no son el proceso de producción de esta publicación estática.

Configura Projects para este ejemplo

Conecta tu proveedor Git y selecciona el repositorio siguiendo la documentación de Projects. Revisa los permisos antes de autorizarlos. Para el ejemplo probado:

Estos valores corresponden a este repositorio. Un monorepo, otro script o una salida personalizada necesita su propia configuración. No publiques node_modules ni tu carpeta personal.

Evita el 404 al entrar directamente en una ruta

Al navegar desde la portada, React puede cambiar la URL a /about sin pedir otro HTML. Al recargar, el navegador sí solicita /about al alojamiento. Si allí no existe ese archivo y no hay fallback, obtendrás 404 aunque el enlace funcionara antes.

En Hostbrid, este ejemplo activa el fallback con el archivo public/.hostbrid-spa. Vite lo copia a la raíz de dist. El alojamiento sirve index.html para las rutas de navegador del sitio que incluye ese marcador y tiene un índice. Los sitios sin marcador mantienen su comportamiento habitual. El marcador no se entrega por HTTP y los assets ausentes siguen devolviendo 404.

Comprueba que tu exportación conserva los archivos que empiezan por punto. No basta con crearlo en una carpeta que el build no copie. Una ruta desconocida puede devolver el HTML con estado 200 y mostrar el «Página no encontrada» de React: eso no convierte esa URL en una página válida para SEO. Define las rutas reales y revisa tu estrategia de renderizado e indexación antes de publicar muchas URLs.

Pantalla en blanco: distingue la ruta del archivo que falla

Abre las herramientas del navegador, entra en Network, recarga y selecciona la petición que falla. Comprueba URL, estado, tipo de contenido y respuesta. Una portada con estado 200 no demuestra que el JavaScript se haya cargado.

• Documento /about con 404: revisa el marcador y el fallback descritos arriba.
• JavaScript o CSS con 404: compara la URL solicitada con los archivos del build. Publica dist completo y comprueba que el HTML y los assets pertenecen a la misma construcción.
• JavaScript con 200 pero respuesta HTML: el servidor está devolviendo una página, posiblemente el índice o un error, donde el navegador espera código. No arregles esto enviando todas las peticiones a index.html; los assets ausentes deben seguir dando 404.
• Archivos cargados, pero pantalla vacía: revisa la consola. Un error de la aplicación, una API externa o una variable ausente requiere un diagnóstico distinto del fallback.

Nuestro ejemplo se publica en la raíz de su subdominio. Si preparas una instalación bajo /demo/ en otro servidor, la opción base de Vite ajusta las rutas de assets al construir; el prefijo del router se configura por separado. base: './' no es una solución universal para recargas en rutas profundas. Esta guía no demuestra que Projects admita publicar bajo cualquier prefijo.

También puedes usar nuestro diagnóstico estático original, con licencia MIT. Con Node 22.23.3, descarga la versión probada y ejecuta:

git clone https://github.com/ocentelles/hostbrid-static-diagnostics.git
cd hostbrid-static-diagnostics
git checkout 203e71e33e9864f8048dccee3d886fa3c87dcb1c
node --version
node diagnose.mjs https://hostbrid-react-demo.hostbrid.dev/

Sustituye la URL de la demo por la de tu web pública. No requiere instalar dependencias. Comprueba el HTML y las referencias directas a JavaScript y CSS del mismo origen; no ejecuta React ni verifica imágenes, APIs o rutas internas. Devuelve JSON y un código de salida distinto de cero si detecta fallos o no puede completar una comprobación. La demo del comando pasó tres peticiones GET; la herramienta tiene 28 pruebas HTTP locales. Un resultado correcto no sustituye las pruebas en el navegador.

También publicamos el ejemplo original de rutas y assets: seis casos locales, incluyendo bases incorrectas, prefijo del router y HTML servido como JavaScript. Su README explica cómo reproducirlos con Node y Chrome; el ensayo no añade capacidades comerciales a Projects.

Configura variables sin publicar secretos

El ejemplo usa VITE_CONTACT_LABEL, una etiqueta incorporada al JavaScript al construir. Las variables VITE_* son públicas: no pongas contraseñas, claves privadas ni tokens de administración. Cambiar la variable requiere otro build; no modifica los archivos que ya están publicados.

Comprueba por qué sigue apareciendo el valor anterior

En nuestro ensayo original de variables de Vite, construimos una etiqueta con el valor A y servimos esos mismos archivos desde un proceso con el valor B. El navegador siguió mostrando A, también después de recargar, y el hash del JavaScript no cambió. Al reconstruir con B cambiaron tanto la etiqueta como el hash. Sin la variable, apareció el texto alternativo previsto.

Si ves el valor antiguo, comprueba qué variable recibió el proceso de construcción y qué build estás publicando. Cambiar únicamente el entorno del servidor que entrega los archivos estáticos no reescribe el bundle. Este ensayo local verifica una configuración estática de Vite; no demuestra la propagación de variables del panel de Hostbrid ni el comportamiento de SSR o de una configuración de entorno cargada en tiempo de ejecución.

Puedes reproducir las tres construcciones con Node 22.23.3 y Chrome en macOS siguiendo el README del repositorio. Utiliza valores de ejemplo públicos: la comprobación de un marcador sin prefijo en este ensayo no constituye una auditoría de secretos de tu proyecto.

Si el navegador sigue llamando a localhost

En Network, recarga la web publicada y abre la petición que falla. Si su URL contiene http://localhost:3000/api/contact, el navegador del visitante está intentando contactar con su propio equipo. Publicar los archivos de React no publica automáticamente ese servidor.

Localiza dónde se construye esa URL: código, configuración o una variable pública del build. Sustitúyela por el endpoint HTTPS del backend que realmente hayas publicado. Si usas una variable VITE_, vuelve a construir y publicar; cambiar una variable después no modifica el JavaScript ya generado. No pongas credenciales privadas en esa variable.

Una referencia relativa /api/contact evita fijar el hostname, pero solicita esa ruta al mismo origen donde se sirve la web. Úsala solo si allí existe el backend o un proxy configurado. Un 404 o una respuesta con el HTML de la portada indica que aún debes revisar esa ruta; no demuestra un envío correcto.

No reemplaces todas las apariciones de 0.0.0.0: puede ser la dirección correcta donde escucha un servidor. La URL que solicita el navegador necesita el destino público. Después, recarga y verifica URL, respuesta y acción esperada. Corregir el hostname no verifica por sí solo CORS, login ni recepción de formularios.

Verifica después de publicar

Abre la URL HTTPS desde otro dispositivo. Visita la portada, escribe /about directamente y recarga. Comprueba la imagen, los estilos y el contenido de la segunda ruta. Solicitar un JavaScript inexistente debe producir 404, no HTML con estado 200.

Prueba del 8 de octubre de 2026: publicamos el commit db329ae mediante el proceso de construcción de Projects. La portada y /about devuelven 200; CSS y JavaScript se sirven con sus tipos correctos. Chrome ejecutó React en /about y mostró la etiqueta pública del build. Los assets ausentes y el marcador devolvieron 404. La configuración de rutas se probó en las dos réplicas de alojamiento, incluyendo sitios que no activan el fallback.

La prueba utiliza un proyecto propio de Hostbrid: verifica construcción y publicación, pero no el alta de un cliente, su autorización OAuth ni las actualizaciones automáticas por push. Consulta Projects y los planes vigentes para elegir capacidad. Si tu web necesita un backend, decide y prueba también dónde se ejecutará antes de ofrecerla a tus usuarios.

Consulta también la documentación de construcción de Vite y sus variables de entorno públicas.

Si tu repositorio contiene dos aplicaciones y un paquete compartido, revisa el diagnóstico de npm workspaces antes de recortar una carpeta: la raíz de instalación y la salida publicada cumplen funciones distintas.