Cómo desplegar tu aplicación de React + Vite en GitHub Pages

Publicar tu app en GitHub Pages es una forma rápida y gratuita de mostrar tus proyectos front-end. En esta guía te explico, paso a paso, cómo hacerlo desde un proyecto creado con React y Vite.

Requisitos previos

• Proyecto creado con React + Vite.
• Repositorio en GitHub con tu código.
• Node.js y terminal operativos.

Nota: GitHub Pages sirve sitios estáticos (HTML/CSS/JS); no ejecuta código de servidor.

Configura la ruta base en vite.config.ts o vite.config.js

Vite necesita saber desde qué ruta se servirá tu sitio en producción. Para repositorios de proyecto
(https://TU_USUARIO.github.io/NOMBRE_DEL_REPO/), define base con esa URL.

Ejemplo: vite.config.ts

import { defineConfig } from 'vite'
import react from '@vitejs/plugin-react'
export default defineConfig({
  plugins: [react()],
  base: 'https://TU_USUARIO.github.io/NOMBRE_DEL_REPO/',
})

Si usas un User/Org Page (repositorio llamado TU_USUARIO.github.io), la base suele ser '/':

export default defineConfig({
  plugins: [react()],
  base: '/',
})

Instala y prepara gh-pages

1. Instala la dependencia:

   npm install --save-dev gh-pages

2. Añade scripts en package.json:

   {
     "scripts": {
       "dev": "vite",
       "build": "vite build",
       "preview": "vite preview",
       "deploy": "npm run build && gh-pages -d dist"
     }
   }

   El script deploy compila tu app y publica la carpeta dist en la rama gh-pages.

Despliega tu app

1. Ejecuta el despliegue:

   npm run deploy

2. Activa GitHub Pages: en tu repositorio, ve a Settings > Pages y selecciona la rama gh-pages (carpeta raíz).

3. Verifica la URL final:

   https://TU_USUARIO.github.io/NOMBRE_DEL_REPO/

Resumen rápido

Paso	Acción
1	Definir base en Vite según tu tipo de página (User/Org o Project).
2	Instalar gh-pages.
3	Añadir scripts build y deploy en package.json.
4	Ejecutar npm run deploy.
5	Configurar GitHub Pages para usar la rama gh-pages.
6	Comprobar la URL publicada.

Rutas con React Router (SPA)

GitHub Pages no soporta el history API del navegador sin configuración extra. Tienes dos alternativas:

1. Usar HashRouter (recomendado por simplicidad):

   import { HashRouter, Routes, Route } from 'react-router-dom'
   export function App() {
     return (
       <HashRouter>
         <Routes>
           <Route path="/" element={<Home />} />
           <Route path="/about" element={<About />} />
         </Routes>
       </HashRouter>
     )
   }

2. Mantener BrowserRouter y añadir una 404.html que redirija a index.html (más avanzado). Para la mayoría de casos, HashRouter es suficiente.

Problemas comunes y soluciones

• 404 Not Found / rutas rotas: usa HashRouter o configura una 404.html que redirija a index.html.

• Recursos (CSS/JS) sin cargar: comprueba que base termina en / y apunta a la URL correcta.

• La página no actualiza tras desplegar: puede ser la caché. Fuerza recarga (Ctrl/Cmd + Shift + R) o espera unos minutos a la propagación.

• Error de permisos al publicar: verifica que el repositorio no es privado (o que tu configuración de Pages permite despliegue desde gh-pages).

• Rama gh-pages no aparece: se crea en el primer npm run deploy. Si falla, revisa el log del comando.

Checklist final

• He configurado base correctamente según el tipo de página.
• La app compila sin errores con npm run build.
• Las rutas funcionan (preferiblemente con HashRouter).
• GitHub Pages está activado apuntando a gh-pages.
• La URL final carga estilos, imágenes y navegación.