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
-
Instala la dependencia:
npm install --save-dev gh-pages -
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
deploycompila tu app y publica la carpetadisten la ramagh-pages.
Despliega tu app
-
Ejecuta el despliegue:
npm run deploy -
Activa GitHub Pages: en tu repositorio, ve a Settings > Pages y selecciona la rama
gh-pages(carpeta raíz). -
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:
-
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> ) } -
Mantener
BrowserRoutery añadir una404.htmlque redirija aindex.html(más avanzado). Para la mayoría de casos,HashRouteres suficiente.
Problemas comunes y soluciones
-
404 Not Found / rutas rotas: usa
HashRoutero configura una404.htmlque redirija aindex.html. -
Recursos (CSS/JS) sin cargar: comprueba que
basetermina 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-pagesno aparece: se crea en el primernpm run deploy. Si falla, revisa el log del comando.
Checklist final
- He configurado
basecorrectamente 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.
