Deploy React Vite en GitHub Pages y Vercel

En pocas palabras: Para desplegar React con Vite en GitHub Pages, configurá base como ‘/nombre-del-repo/’, creá .github/workflows/deploy.yml y elegí GitHub Actions como fuente. En Vercel importás el repo, con preset Vite, comando npm run build y salida dist.

Para hacer deploy de React Vite en GitHub Pages tenés que configurar base con el nombre del repositorio y publicar la carpeta dist con GitHub Actions. En Vercel alcanza con importar el repo, porque detecta Vite solo.

Vite es una herramienta de build y servidor de desarrollo para proyectos frontend. Con React, levantás el entorno local con npm run dev y generás la versión de producción con npm run build, que según la guía de despliegue estático de Vite sale por defecto en la carpeta dist. Esa carpeta es lo que subís a cualquier hosting estático.

¿Por qué mi app de Vite se ve en blanco en GitHub Pages?

Se ve en blanco porque GitHub Pages sirve los sitios de proyecto desde una subruta, del tipo https://USUARIO.github.io/repo/, y Vite arma por defecto las rutas de los archivos como si la app viviera en la raíz del dominio. La solución es definir base en vite.config.js con el nombre exacto del repositorio. Vercel, en cambio, sirve desde la raíz de su dominio y ahí no hace falta tocar nada.

La guía de dev.to publicada el 9 de octubre de 2026 propone una variante que sirve para las dos plataformas:

import { defineConfig } from 'vite'
import react from '@vitejs/plugin-react'

export default defineConfig({
 plugins: [react()],
 base: process.env.GITHUB_ACTIONS ? '/my-react-app/' : '/',
})

En el build de GitHub Actions usa la subruta; en local y en Vercel usa /. Reemplazá my-react-app por el nombre real del repo, letra por letra. La documentación de Vite dice lo mismo: '/<REPO>/' si publicás en https://<USUARIO>.github.io/<REPO>/, y '/' si usás <USUARIO>.github.io o un dominio propio.

Subís el repo, el workflow termina en verde, abrís la URL con ganas de festejar y te encontrás con una página en blanco porque el index.html cargó pero los scripts apuntan a /assets/ en la raíz del dominio, que en GitHub Pages ya no es tu proyecto.

Abrí la consola del navegador y buscá los JS o CSS que devuelven 404 (spoiler: casi siempre es el base). Ya lo cubrimos antes en desplegar tu sitio gratis en Vercel.

¿Cómo creo un proyecto React con Vite y lo subo a GitHub?

Con Node.js y Git instalados, npm create vite@latest my-react-app -- --template react crea el proyecto, npm install baja las dependencias y npm run dev levanta el servidor local, que según la guía suele quedar en http://localhost:5173/.

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

git init
git branch -M main
git add .
git commit -m "Initial commit"
git remote add origin https://github.com/USUARIO/my-react-app.git
git push -u origin main

Antes del primer commit, revisá que .gitignore excluya .env y cualquier API key. En un repo público lo que subas lo puede leer cualquiera.

Cómo hacer deploy de React Vite en GitHub Pages con GitHub Actions

Para publicar en GitHub Pages creás el archivo .github/workflows/deploy.yml, activás Settings → Pages → Build and deployment → GitHub Actions como fuente y hacés push a main. El workflow instala dependencias, corre npm run build y publica dist. Según la documentación de Vite, este camino es el que corresponde porque el sitio necesita un paso de build.

• Requisito de npm. El ejemplo usa npm ci, así que necesitás npm y un package-lock.json commiteado.
• Disparadores. Cada push a main y una ejecución manual con workflow_dispatch.
• Permisos. contents: read, pages: write e id-token: write.
• Dos jobs. Uno de build (checkout, Node 22 con caché de npm, npm ci, npm run build, configure-pages y subida de dist) y otro de deploy con deploy-pages.

name: Deploy React App to GitHub Pages
on:
 push:
 branches: [main]
 workflow_dispatch:
permissions:
 contents: read
 pages: write
 id-token: write
concurrency:
 group: pages
 cancel-in-progress: true
jobs:
 build:
 runs-on: ubuntu-latest
 steps:
 - name: Checkout
 uses: actions/checkout@v4
 - name: Setup Node.js
 uses: actions/setup-node@v4
 with:
 node-version: 22
 cache: npm
 - name: Install dependencies
 run: npm ci
 - name: Build project
 run: npm run build
 - name: Setup Pages
 uses: actions/configure-pages@v5
 - name: Upload build output
 uses: actions/upload-pages-artifact@v4
 with:
 path: dist
 deploy:
 environment:
 name: github-pages
 url: ${ steps.deployment.outputs.page_url }
 runs-on: ubuntu-latest
 needs: build
 steps:
 - name: Deploy
 id: deployment
 uses: actions/deploy-pages@v4

Ojo con las versiones. El ejemplo de dev.to usa checkout@v4, setup-node@v4 y upload-pages-artifact@v4, mientras que el de la documentación de Vite referencia versiones más nuevas (v7 para checkout y setup-node, v6 para configure-pages, v5 para upload-pages-artifact y deploy-pages), fijadas por hash de commit, con un solo job y node-version: lts/*. Antes de copiar cualquiera de los dos, mirá la documentación oficial.

Después abrís la pestaña Actions, esperás que termine y entrás a https://USUARIO.github.io/my-react-app/. El primer deploy puede tardar unos minutos. Tema relacionado: qué hacer si GitHub Actions se cae.

¿Cómo desplegar el mismo proyecto de Vite en Vercel?

Entrás a Vercel con tu cuenta de GitHub, elegís Add New → Project, importás el repositorio y confirmás la configuración: Framework Preset Vite, Root Directory ./, Build Command npm run build y Output Directory dist. Al hacer clic en Deploy, Vercel te da una URL tipo https://my-react-app.vercel.app (la tuya puede ser distinta).

Según la guía de Vite, Vercel detecta que usás Vite y activa la configuración correcta. También podés deployar desde la terminal con npm i -g vercel y después vercel. Los pushes a ramas que no son la de producción generan Preview Deployments, y los cambios en la rama de producción (casi siempre main) generan un Production Deployment.

Un solo git push actualiza las dos versiones.

Ahora bien, ese deploy “automático” no es magia: GitHub Actions rebuilda Pages y Vercel arma su propio deployment, así que podés tener una versión funcionando y la otra rota. Revisá el estado en los dos paneles.

¿Cómo arreglo el error 404 de React Router al recargar una ruta?

El 404 aparece cuando usás BrowserRouter y recargás una ruta anidada (ponele /perfil/editar), porque el host busca ese archivo, no lo encuentra y no redirige a index.html. La solución depende de la plataforma: en Vercel es un rewrite en vercel.json, y en GitHub Pages hace falta otro enfoque.

{
 "rewrites": [
 { "source": "/(.*)", "destination": "/index.html" }
 ]
}

Ese rewrite manda cualquier ruta a index.html. Para GitHub Pages, la guía de dev.to solo dice que hay que usar routing con hash o alguna estrategia de fallback, sin detallar cuál. No te voy a inventar una receta que las fuentes no traen.

¿GitHub Pages o Vercel para publicar un proyecto React?

Para un proyecto React con Vite sirven las dos y ambas tienen hosting estático gratis según la guía. Vercel trae el deploy automático integrado con Git, y en GitHub Pages tenés que escribir un workflow. El autor recomienda Vercel como plataforma principal para principiantes y GitHub Pages para aprender Actions (es su opinión, no un dato medido). Te puede servir nuestra cobertura de comparativa entre Vercel y AWS Amplify.

Característica	GitHub Pages	Vercel
Hosting estático gratis	Sí	Sí
Dominio propio	Sí	Sí
Deploy automático	Con GitHub Actions	Integrado con Git
Configuración de build	Workflow de GitHub Actions	Ajustes del proyecto
Mejor para	Sitios estáticos y aprender CI/CD	Apps React con deploy simplificado

Mi lectura: si publicás un portfolio y no querés tocar YAML, Vercel. Si querés entender cómo se arma un pipeline, Pages es mejor escuela. Lo que estos datos no permiten concluir es el costo, porque la guía no trae precios ni límites de planes. Para eso hay que mirar las condiciones vigentes de cada plataforma.

Un límite que no depende de la elección: GitHub Pages es solo estático. Un MERN con Express y MongoDB necesita backend y base de datos en otro lado, y si ese es tu caso, o si querés un dominio .ar, en donweb.com tenés hosting y dominios.

¿Cómo verifico el deploy antes de publicar?

Una propuesta editorial (no sale de las fuentes y no la probamos): reproducí en local el build de Actions antes de hacer push. Como el base cambia cuando existe la variable GITHUB_ACTIONS, un build común no te muestra el problema de la subruta.

# PowerShell
$env:GITHUB_ACTIONS="true"; npm run build; npm run preview
Remove-Item Env:GITHUB_ACTIONS

GITHUB_ACTIONS=true npm run build && npm run preview

La documentación de Vite aclara que vite preview levanta un servidor local en http://localhost:4173 y no es un servidor de producción. Si la app carga con estilos y scripts bajo la subruta, el base debería estar bien. Confirmalo en tu proyecto, y no reemplaza mirar el deploy real.

¿Qué errores comunes rompen el deploy en GitHub Actions o Vercel?

La guía de dev.to lista los problemas típicos de quien deploya por primera vez, y casi todos se resuelven mirando logs.

Si el proyecto funciona en tu máquina pero falla al publicarlo, mirá este artículo sobre el deploy de React en Vercel.

• Pantalla en blanco en Pages. El base no coincide con el nombre del repo. Corregilo y revisá la consola por archivos JS o CSS que no cargan.
• Falla npm ci. El lockfile falta o no coincide con package.json. Corré npm install y npm run build en local, y commiteá package.json y package-lock.json.
• Falla el deploy en Vercel. Abrí los build logs y revisá que el root directory sea correcto, que npm run build ande en local, que el output directory sea dist y que las dependencias estén en package.json.
• No se ven los cambios. Confirmá que el último deployment terminó bien, hacé hard refresh con Ctrl + Shift + R y verificá que esté conectada la rama correcta.
• Secretos en el repo. Un .env o una API key en un repo público es un error que no se arregla borrando el archivo en el próximo commit, porque queda en el historial.

Preguntas Frecuentes

¿Cómo subo un proyecto de React con Vite a GitHub Pages?

Definí base: '/nombre-del-repo/' en vite.config.js, creá un workflow en .github/workflows/deploy.yml y elegí GitHub Actions como fuente en Settings → Pages. Después hacé push a main y esperá que termine la pestaña Actions. Cubrimos ese tema en detalle en automatizar deploys a cPanel con GitHub Actions.

¿Cómo se despliega una app de Vite en Vercel?

Importás el repositorio desde Add New → Project con el preset Vite, Build Command npm run build y Output Directory dist. También podés usar la CLI con npm i -g vercel y el comando vercel.

¿Por qué mi sitio en GitHub Pages se ve en blanco?

Casi siempre el base de Vite no coincide con la subruta del repo. Corregilo y revisá en la consola del navegador qué archivos JS o CSS no se cargan.

¿Qué es mejor para publicar React: GitHub Pages o Vercel?

Según el autor de la guía de dev.to, Vercel es mejor como plataforma principal para principiantes por su deploy simplificado, y GitHub Pages sirve para aprender GitHub Actions. Es una recomendación personal y las fuentes no comparan costos.

¿Por qué React Router da 404 al recargar la página?

Con BrowserRouter, el host recibe la ruta anidada y falla si no redirige a index.html. En Vercel se resuelve con un rewrite de /(.*) a /index.html en vercel.json.

Conclusión

El deploy de React Vite se complica en dos puntos concretos: el base en GitHub Pages y el fallback de rutas con React Router. Si resolvés esos dos, el resto es seguir pasos. Mi recomendación práctica: publicá primero en Vercel para tener la app online rápido, y armá el workflow de Pages cuando quieras aprender CI/CD, simulando el build con GITHUB_ACTIONS=true antes de cada push. Antes de copiar el YAML de cualquier guía, comparalo con la documentación oficial, porque las versiones de las actions ya difieren entre las fuentes.

Fuentes

• Vite – Guía oficial de despliegue de un sitio estático
• dev.to – How to Deploy a React + Vite Project to GitHub Pages and Vercel (9 de octubre de 2026)