Desplegar app React: de npm run build a internet paso a paso

Para desplegar una app React (publicarla en internet), primero generas la versión final con npm run build, que crea una carpeta dist con archivos estáticos, y luego subes esa carpeta a un hosting como Netlify, Vercel o Cloudflare Pages, o conectas tu repositorio para que el hosting haga el build por ti. Las tres cosas que más fallan son las variables de entorno, las rutas que dan 404 y la ruta base. Aquí va todo en orden.

Esta guía es para apps React con Vite, que es lo que generan Lovable, Bolt, v0 y la mayoría de herramientas actuales. Si tu proyecto es Next.js, el despliegue es distinto (Vercel lo resuelve casi solo).

Paso 1: genera el build con npm run build (Vite)

En la carpeta de tu proyecto:

npm install
npm run build

• npm install descarga las librerías del proyecto (la carpeta node_modules).
• npm run build ejecuta vite build: compila tu código React, lo optimiza y lo deja en dist/.

Para probar el resultado como quedaría en internet:

npm run preview

Abre la dirección que te muestra (por defecto http://localhost:4173). Si aquí falla, en el hosting también fallará. Si quieres entender a fondo este paso, lee qué hace npm run build.

Si npm run build falla

Lee el error desde la primera línea roja. Lo más común:

• Errores de TypeScript que en modo desarrollo no frenaban la app.
• Importaciones con mayúsculas distintas (./Components/Header vs ./components/Header): en Windows y Mac funciona, en Linux (los servidores) no.
• Librerías faltantes en package.json.

Paso 2: configura las variables de entorno

Vite solo expone al código las variables que empiezan con VITE_:

# .env (local, no se sube a GitHub)
VITE_SUPABASE_URL=https://xxxx.supabase.co
VITE_SUPABASE_PUBLISHABLE_KEY=tu-llave-publica

const url = import.meta.env.VITE_SUPABASE_URL;

Puntos clave:

• Las variables se incrustan al momento del build. Si las cambias en el hosting, hay que volver a desplegar.
• Tu archivo .env no se sube al hosting. Tienes que capturar las mismas variables en el panel del servicio.
• Nada secreto con prefijo VITE_: termina en el navegador. Más en variables de entorno en Vite y React.

Paso 3: elige dónde desplegar tu app React

Hosting	Build command	Carpeta de salida	Guía
Netlify	npm run build	dist	Subir a Netlify
Vercel	npm run build	dist	Subir a Vercel
Cloudflare Pages	npm run build	dist	Panel de Cloudflare → Workers & Pages
Firebase Hosting	npm run build (local)	dist	firebase deploy
GitHub Pages	Local o GitHub Actions	dist	Ajusta base en Vite

Si no sabes cuál, compara límites y uso comercial en desplegar app web gratis.

Paso 4: arregla las rutas (el 404 al recargar)

En una app React con React Router, /contacto no es un archivo real: lo resuelve tu JavaScript desde index.html. Si el hosting no lo sabe, al recargar da 404. La solución depende del servicio:

Netlify — archivo public/_redirects:

/*    /index.html   200

Vercel — archivo vercel.json en la raíz:

{ "rewrites": [{ "source": "/(.*)", "destination": "/index.html" }] }

Firebase — en firebase.json, dentro de hosting:

"rewrites": [{ "source": "**", "destination": "/index.html" }]

Cloudflare Pages trata los proyectos sin 404.html como app de una sola página y redirige solo, según su documentación; si agregaste un 404.html, revisa ese comportamiento.

Paso 5: la ruta base (si no publicas en la raíz)

Si tu app vive en una subcarpeta (por ejemplo usuario.github.io/mi-app/), configura Vite:

// vite.config.js
export default defineConfig({ base: "/mi-app/" });

Sin esto, la página carga en blanco porque busca los archivos en /assets/ en vez de /mi-app/assets/.

Errores comunes al desplegar una app React

• Pantalla en blanco: abre la consola del navegador (F12). Casi siempre es una variable de entorno vacía o la ruta base mal.
• Subir la carpeta equivocada: se sube dist, no src ni el proyecto completo.
• Subir node_modules a GitHub: debe estar en .gitignore.
• API apuntando a localhost: en internet, localhost es la computadora del visitante.
• CORS: tu API rechaza peticiones del dominio nuevo; agrégalo a la lista de orígenes permitidos.
• Login que redirige a localhost: actualiza las URLs de redirección en Supabase o en tu proveedor de login.

Despliegue manual o automático desde GitHub

Hay dos formas de llevar tu app al hosting:

• Manual: haces npm run build en tu computadora y subes la carpeta dist (arrastrándola al panel o con la herramienta de línea de comandos del servicio). Sirve para una primera prueba, pero cada cambio exige repetir el proceso y es fácil subir una versión vieja.
• Automático: conectas el repositorio de GitHub al hosting. Cada git push a la rama principal dispara un build en los servidores del hosting y publica el resultado. Además, Netlify, Vercel y Cloudflare Pages generan una URL de vista previa por cada rama o pull request, para revisar cambios antes de que lleguen al sitio real.

Para cualquier proyecto que vayas a seguir modificando, el automático es el recomendable. Si tu app viene de Lovable, el primer paso es conectar Lovable a GitHub.

Cómo comprobar que el despliegue salió bien

No basta con que el hosting diga “Deployed”. Revisa:

1. La página de inicio y una ruta interna, recargando con F5 en la ruta interna (así detectas el 404 del paso 4).
2. La consola del navegador (F12 → Console): no debe haber errores rojos.
3. La pestaña Network: las llamadas a tu API o a Supabase deben responder con códigos 200, no 401 ni 404.
4. El login y un formulario, de principio a fin.
5. El candado de HTTPS en la barra de direcciones.

Cuándo un hosting estático no alcanza

Un hosting como los de la tabla sirve archivos; no ejecuta un servidor tuyo todo el tiempo. Si tu app necesita guardar llaves secretas, procesar pagos o conectarse a una base de datos con credenciales privadas, esa parte va en funciones del hosting (Netlify Functions, Vercel Functions, Cloudflare Workers), en Supabase Edge Functions o en un servidor aparte. Poner esa lógica en el código React es exponerla a cualquier visitante.

Cuándo pedir ayuda

Si tu app compila y solo falta subirla, con esta guía lo haces en una tarde. Si el build truena con errores que no entiendes, la app depende de un backend, o la hiciste con IA y no sabes qué partes son seguras para publicar, conviene una revisión. En Black Engine lo revisamos por WhatsApp y te ayudamos a desplegarla bien.