Cómo hospedar una app React

Una app React hecha con Vite no se ejecuta en el servidor: se convierte en una carpeta de archivos (un index.html, JavaScript, CSS e imágenes) y el navegador ejecuta React. Hospedarla es publicar esa carpeta en un lugar que la sirva por HTTPS. Se hace en pocos minutos, pero dos detalles hacen tropezar a mucha gente: las rutas que dan 404 al recargar y las variables de entorno que "desaparecen" o se filtran.

Los ejemplos usan Vite, una de las herramientas de build que la documentación de React recomienda a quien arma su propio proyecto. Create React App quedó obsoleto para apps nuevas en febrero de 2025.

¿Qué necesitas antes de empezar?#

• Una versión reciente de Node.js que cumpla el mínimo indicado en la documentación de Vite.
• Un proyecto React con Vite. Para crear uno desde cero:

npm create vite@latest mi-app -- --template react
cd mi-app
npm install
npm run dev

El -- antes de --template es necesario en npm 7 o superior. Usa --template react-ts para TypeScript. npm run dev abre el servidor de desarrollo, que sirve solo para programar y no va a producción.

¿Cómo generar el build de producción?#

npm run build
npm run preview

build ejecuta vite build y escribe todo en dist/, minificado. preview sirve dist/ en http://localhost:4173 para que revises el resultado. La documentación de Vite advierte que preview no es un servidor de producción.

La carpeta dist/ es lo que publicas. Tu código fuente, node_modules y los archivos .env se quedan fuera. Si el sitio va a vivir en una subruta (ejemplo.com/app/), define base: '/app/' en vite.config.js. En un dominio propio o subdominio, el valor por defecto '/' es correcto.

¿Por qué las rutas dan 404 al recargar la página?#

Con React Router en modo navegador, la URL /acerca solo existe dentro del JavaScript:

import { createBrowserRouter, RouterProvider } from "react-router";

const router = createBrowserRouter([
  { path: "/", element: <Home /> },
  { path: "/acerca", element: <Acerca /> },
]);

export default function App() {
  return <RouterProvider router={router} />;
}

Hacer clic en un enlace funciona porque el navegador no le pide nada al servidor. Al recargar /acerca, en cambio, el navegador pide esa ruta al servidor, que busca un archivo acerca, no lo encuentra y responde 404. El servidor debe devolver index.html para toda ruta que no sea un archivo y dejar que React Router decida la pantalla.

Cada servidor lo hace distinto. En Firebase Hosting, por ejemplo, es una regla rewrites en firebase.json que apunta ** a /index.html. En Nginx, es try_files $uri /index.html;. Si tu servidor no tiene esa regla, las rutas profundas fallan. Lo mismo vale para una SPA generada con el modo framework de React Router y ssr: false en react-router.config.ts.

Para páginas que necesitan SEO y contenido desde la primera carga, una SPA pura es limitada: mira SSR, SSG y sitio estático y cómo hospedar una app Next.js.

¿Cómo usar variables de entorno en React?#

Vite solo expone al código las variables con prefijo VITE_, leídas con import.meta.env. En un archivo .env.production:

VITE_API_URL=https://api.ejemplo.com

const res = await fetch(`${import.meta.env.VITE_API_URL}/productos`);

El valor se graba en el JavaScript durante el build. Cambiar la variable después exige un nuevo build, y cualquier visitante puede leer el valor en el código de la página. Por eso la documentación de Vite dice que las variables VITE_* no deben guardar datos sensibles como claves de API. Los secretos van en un backend (mira cómo hospedar una API) y el front-end llama a ese backend. Para el concepto general, lee qué son las variables de entorno.

¿Cómo publicar la carpeta dist?#

Los pasos exactos dependen de dónde hospedes, pero el principio es el mismo: enviar el contenido de dist/ (no la carpeta en sí) a un servidor estático, con index.html en la raíz. Revisa antes de publicar:

1. npm run build terminó sin errores.
2. npm run preview abre la app y la navegación entre rutas funciona.
3. El fallback a index.html está configurado en el servidor.
4. Ningún .env ni secreto terminó en dist/, porque todo lo que hay ahí es público.

Tras el deploy, abre una ruta profunda directamente en la barra de direcciones (por ejemplo, /acerca) y recarga. Si carga, el fallback está bien. Para ver el ciclo completo, mira qué es un deploy y cómo hospedar un sitio web.

¿Cómo poner un dominio propio?#

Cuando la app responde en la dirección del proveedor, apunta tu dominio con los registros DNS que el proveedor indique (normalmente un CNAME para subdominios como www). El HTTPS suele emitirse solo cuando el DNS se propaga. El paso a paso está en cómo apuntar un dominio a tu app y cómo usar un dominio personalizado.

¿Cuáles son los errores comunes?#

• Pantalla en blanco en producción: el base de Vite no corresponde a la dirección del sitio y los archivos de /assets dan 404. Revisa la consola del navegador y la pestaña Red.
• 404 al recargar: falta el fallback a index.html, como se explicó arriba.
• import.meta.env.VITE_X es undefined: la variable no tiene el prefijo VITE_ o se definió después del build.
• Sitio viejo después de publicar: el navegador o la CDN guardó index.html en caché. Los archivos de assets/ llevan un hash en el nombre, así que solo index.html debe tener caché corta. Mira qué es Cache-Control.

Cómo hacerlo en Square Cloud#

Una app React con Vite corre en el runtime de sitios estáticos de Square Cloud. Ejecutas npm run build y subes el contenido de dist/ en un ZIP desde el panel; la CLI, GitHub y la extensión de VS Code son las otras formas de hacer el deploy.

Para el fallback de rutas, renombra dist/index.html a vite.html antes de comprimir: el runtime estático responde con vite.html a toda ruta que no sea un archivo, así que recargar /acerca funciona. Los pasos están en el tutorial de React de la documentación.

El archivo de configuración squarecloud.app es opcional: el panel lo genera en el deploy con el archivo principal y la memoria, o puedes escribirlo tú en la raíz del proyecto. Los sitios necesitan al menos 512 MB de RAM.

Toda aplicación web recibe un subdominio *.squareweb.app con HTTPS, en cualquier plan. El dominio propio está disponible desde Standard: creas en tu registrador los registros DNS que muestra el panel y el TLS es automático. El dominio sigue registrado a tu nombre. Los planes se cobran en reales y Hobby empieza en R$12,49 al mes. Para más detalles, mira dominios y hospedaje de sitios.