Base de Conhecimento

Esta guía explica cómo subir a tu cuenta de hosting una web hecha con React, Vite u otro bundler similar, tratándola como lo que realmente es en producción: archivos estáticos HTML, CSS y JS.

La idea es:

1. Generar el build de producción en tu PC.

2. Subir ese build al hosting usando cPanel → Administrador de archivos.

3. (Opcional pero muy recomendable para SPA) Configurar un .htaccess para que todas las rutas de la app apunten a index.html.

1. ¿Qué es “modo estático” en React / Vite?

Cuando ejecutás:

• npm run build en un proyecto creado con Create React App, se genera una carpeta build/ con una versión optimizada de tu sitio lista para servir en cualquier servidor web estático.

• npm run build en Vite genera una carpeta dist/ con assets estáticos optimizados listos para ser servidos desde un hosting estático.

Eso significa que no necesitás Node corriendo en el servidor para mostrar la web: cPanel (Apache) sirve el HTML/JS/CSS como cualquier sitio tradicional.

2. Requisitos previos

Antes de empezar, asegurate de tener:

1. Proyecto funcionando en tu máquina

   • Podés levantarlo con npm run dev sin errores.

2. Node + npm instalados en tu PC

   • La versión no importa tanto mientras sea compatible con tu proyecto.

3. Acceso al cPanel de tu hosting

   • Usuario y clave del panel.

4. (Opcional) Cliente FTP como FileZilla, si preferís FTP.
   De todos modos, con el Administrador de archivos de cPanel alcanza.

3. Paso 1 – Crear el build de producción en tu PC

Abrí una terminal en la carpeta raíz del proyecto y ejecutá:

Según el stack, se va a generar:

• Create React App: carpeta build/.

• Vite: carpeta dist/.

No subas toda la carpeta del proyecto al servidor: solo necesitamos el resultado del build (build/ o dist/).

4. Paso 2 – Comprimir el build en un ZIP

Para hacer la subida mucho más rápida:

1. Entrá a la carpeta build/ o dist/.

2. Seleccioná todos los archivos y carpetas internos.

3. Creá un archivo ZIP (por ejemplo: sitio-react-build.zip).

La idea es subir un solo ZIP al servidor y extraerlo allá, en lugar de subir cientos o miles de archivos uno por uno.

5. Paso 3 – Entrar a cPanel y abrir el Administrador de archivos

1. Iniciá sesión en cPanel.

2. Andá a File Manager / Administrador de archivos.

3. En el panel izquierdo, ubicá la carpeta:

   • public_html → es la raíz del dominio principal (por ejemplo, tudominio.com).

   • Si estás usando un addon domain o subdominio, fijate en el apartado Dominios de cPanel cuál es su “document root” y entrá a esa carpeta.

Todo lo que pongas dentro del document root es lo que va a ver el navegador al visitar tu dominio.

6. Paso 4 – Subir el ZIP del build y extraerlo

Dentro de la carpeta donde querés que viva tu sitio (por ejemplo public_html):

1. Hacé clic en Upload / Cargar.

2. Seleccioná tu ZIP (sitio-react-build.zip) desde tu PC.

3. Esperá a que el upload llegue al 100%.

4. Volvé al listado de archivos, seleccioná el ZIP y usá la opción Extract / Extraer.

Muy importante

Después de extraer, asegurate de que:

• El archivo index.html esté directamente dentro de la carpeta pública (public_html o la raíz del addon domain).

• Que no haya quedado algo como public_html/build/index.html (salvo que hayas configurado el dominio para apuntar a /build).

Lo habitual es que el contenido del build quede plano, así:

7. Paso 5 – (Opcional pero recomendado) Configurar rutas para SPA con .htaccess

Si tu web tiene rutas tipo:

• /productos

• /contacto

• /tienda/categoria/ropa

y las manejás con React Router o similar, al refrescar esas URLs el servidor no sabe qué archivo devolver y puede mostrar un 404.

La solución típica en Apache (lo que hay detrás de cPanel) es usar un .htaccess que:

• Sirve archivos y carpetas reales normalmente.

• Si la URL no coincide con nada físico, redirige la petición a index.html para que React se encargue.

En la misma carpeta donde está tu index.html (por ejemplo public_html), creá o editá el archivo .htaccess con este contenido:

Con esto:

• Si la URL pide un archivo real (/logo.png, /robots.txt, etc.), se sirve ese archivo.

• Si no existe nada físico (por ejemplo /productos/123), se devuelve index.html y tu app React maneja la ruta.

8. Paso 6 – Probar el sitio

1. Abrí tu dominio en el navegador:
   https://tudominio.com

2. Probá navegar por las diferentes secciones.

3. Refrescá la página (F5) estando en una ruta interna (ej: https://tudominio.com/productos):

   • Si la configuración .htaccess está bien, la SPA se vuelve a cargar.

   • Si ves un error 404 del servidor, hay un problema en la ruta o el .htaccess.

9. Errores frecuentes y cómo resolverlos

9.1. Veo un listado de archivos (“Index of /”)

Posibles causas:

• Falta el archivo index.html en la carpeta pública.

• index.html quedó dentro de una subcarpeta (public_html/build/index.html).

Solución: mover el contenido del build (no la carpeta entera) a la raíz pública.

9.2. En la URL /productos funciona, pero al refrescar tira 404

Causa típica de SPA sin configuración de reescritura.

Solución: asegurate de tener el .htaccess para SPA tal como está en el paso 7.

9.3. Cambié el código pero no veo los cambios

Posibles motivos:

• No volviste a correr npm run build antes de subir.

• El navegador está usando una versión cacheada.

Solución:

1. Volver a ejecutar npm run build.

2. Volver a comprimir y subir el ZIP + extraer.

3. Hacer hard refresh en el navegador (Ctrl+F5 / Cmd+Shift+R) o probar en modo incógnito.

9.4. La app funciona en /, pero falla si la alojo en un subdirectorio

Si tu app vive en https://tudominio.com/app/, algunas herramientas (como Vite) requieren configurar el parámetro base para builds que viven en un subdirectorio.

En ese caso, revisá la documentación de tu bundler (por ejemplo Vite) para ajustar el base antes de hacer el build.

10. Enlaces recomendados

Para quien quiera profundizar, estas son las docs oficiales y artículos relacionados:

• React – Deployment (Create React App)
  https://create-react-app.dev/docs/deployment/

• Vite – Building for Production
  https://vite.dev/guide/build

• Vite – Despliegue de un sitio estático (ES)
  https://es.vite.dev/guide/static-deploy

• Documentación de File Manager de cPanel
  https://docs.cpanel.net/cpanel/files/file-manager/

• Cómo usar File Manager en cPanel (artículo genérico)
  https://www.namecheap.com/support/knowledgebase/article.aspx/9700/29/how-to-use-file-manager-in-cpanel/

• Ejemplo de reglas .htaccess para SPA (React Router)
  https://gist.github.com/alexsasharegan/173878f9d67055bfef63449fa7136042

• Artículo: Configuring client-side routing on Apache (.htaccess)
  https://brandonclapp.com/configuring-client-side-routing-on-apache-htaccess