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

> Aprende a publicar tu aplicación de React + Vite en GitHub Pages fácilmente con esta guía detallada y paso a paso.

- URL canónica: https://www.martagonzalez.dev/blog/como-desplegar-tu-aplicacion-de-react-vite-en-github-pages/
- Fecha de publicación: 2025-09-12T19:56:07
- Última actualización: 2025-11-04T23:58:33

---

![🚀 Cómo desplegar tu aplicación de React + Vite en GitHub Pages](https://martagonzalez.dev/wp/wp-content/uploads/2025/09/como-desplegar-tu-aplicacion-de-react-vite-con-githubpages.avif)
 

 
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 deploy compila tu app y publica la carpeta dist en la rama gh-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 ( } /> } /> ) }

- 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.