DESPLIEGA APLICACIONES REACT CON ENRUTAMIENTO EN GITHUB PAGES
Introduccion al despliegue de aplicaciones React en GitHub Pages
El desarrollo de aplicaciones web modernas con React permite crear interfaces interactivas y dinamicas con gran facilidad. Sin embargo, una vez finalizado el desarrollo local, surge la necesidad de exponer el proyecto al publico de manera sencilla y gratuita. GitHub Pages emerge como una solucion ideal para alojar sitios estaticos directamente desde un repositorio de GitHub, eliminando la necesidad de adquirir dominios o configurar servidores complejos. Este enfoque resulta especialmente util cuando se trabaja con proyectos que combinan JavaScript, HTML y CSS, y se extiende con pequenas configuraciones a frameworks como React, Vue o Angular.
En este tutorial se explora paso a paso como crear una aplicacion React basica, integrarle enrutamiento con react-router-dom y desplegarla exitosamente en GitHub Pages. Se presta especial atencion al manejo del enrutamiento, ya que este aspecto suele generar errores comunes como el codigo 404 al recargar paginas secundarias. Ademas, se actualizan las practicas al contexto actual del desarrollo frontend en 2025, considerando las ultimas versiones estables de Node.js, npm y las herramientas de despliegue.
Preparacion del entorno de desarrollo
Antes de iniciar el proyecto, es fundamental contar con las herramientas necesarias instaladas en el sistema. Node.js constituye la base para ejecutar npm y yarn, gestores de paquetes esenciales en el ecosistema JavaScript. Para verificar la instalacion, abre una terminal y ejecuta los siguientes comandos:
node -v
npm -v
yarn -v
Estos comandos deben mostrar las versiones correspondientes. En octubre de 2025, se recomienda utilizar Node.js en su version LTS activa, preferiblemente 20.x o superior, junto con npm 10.x y yarn 1.22.x o la version berry si se prefiere una gestion moderna de dependencias. Si algun comando falla, descarga e instala las herramientas desde sus sitios oficiales.
Adicionalmente, requiere un repositorio publico en GitHub. Accede a tu cuenta y crea uno nuevo. Para este ejemplo, se utilizara el nombre starter-project, aunque puedes elegir cualquier identificador descriptivo. La visibilidad publica es obligatoria, ya que GitHub Pages no permite alojamiento desde repositorios privados sin suscripcion paga.
Creacion de la aplicacion React con create-react-app
La herramienta create-react-app, aunque en 2025 ha sido parcialmente reemplazada por frameworks como Vite en nuevos proyectos, sigue siendo una opcion robusta y bien documentada para aplicaciones con enrutamiento tradicional. Para generar el proyecto, ejecuta en la terminal:
npx create-react-app starter-project
Este comando descarga las dependencias necesarias y genera una estructura de carpetas estandar. Una vez completado, ingresa al directorio del proyecto:
cd starter-project
Inicia el servidor de desarrollo para verificar el funcionamiento:
yarn start
El mensaje en consola indicara que la aplicacion corre en http://localhost:3000. Al abrir esta direccion en el navegador, visualizara la plantilla predeterminada de React con el logo giratorio y el mensaje de bienvenida. Este paso confirma que el entorno local opera correctamente.
Configuracion inicial del repositorio remoto
Aunque el proyecto ya existe localmente, aun no esta vinculado a GitHub. Regresa a la interfaz web y copia la URL del repositorio recien creado. En la terminal, agrega el remoto con el nombre origin, convencion estandar en Git:
git remote add origin https://github.com/tu-usuario/starter-project.git
Verifica la configuracion con:
git remote -v
Antes de empujar el codigo, inicializa el seguimiento de la rama principal. En proyectos modernos, la rama predeterminada suele ser main, pero create-react-app aun genera master en algunas versiones. Ajusta segun corresponda:
git push --set-upstream origin master
Este comando establece la relacion upstream y sube todos los archivos. Refresca la pagina del repositorio en GitHub para confirmar que el contenido aparece correctamente.
Instalacion y configuracion de gh-pages para despliegue automatico
El despliegue en GitHub Pages requiere convertir la aplicacion React en archivos estaticos. El paquete gh-pages automatiza este proceso al construir el proyecto y empujarlo a una rama especial llamada gh-pages. Instalalo como dependencia de desarrollo:
yarn add gh-pages --dev
Modifica el archivo package.json para incluir scripts de predespliegue y despliegue. Busca la seccion scripts y agregale las siguientes lineas:
"predeploy": "npm run build",
"deploy": "gh-pages -d build"
El script predeploy ejecuta el build antes del despliegue, mientras que deploy envia el contenido de la carpeta build a la rama gh-pages. Adicionalmente, agrega el campo homepage en la raiz del package.json para indicar la URL final:
"homepage": "https://tu-usuario.github.io/starter-project/"
Reemplaza tu-usuario con tu nombre de usuario real en GitHub. Este campo es critico porque React utiliza esta informacion para generar rutas absolutas en el HTML final.
Ejecuta el despliegue por primera vez:
npm run deploy
El proceso mostrara progreso en la terminal y finalizara con el mensaje Published si todo funciona. Accede a la configuracion del repositorio en GitHub, seccion Pages, y verifica que la fuente este establecida en la rama gh-pages y la carpeta / (root). En pocos minutos, la URL indicada estara activa.
Introduccion al enrutamiento en aplicaciones de pagina unica
Hasta este punto, la aplicacion desplegada muestra una sola vista. Sin embargo, las aplicaciones reales requieren multiples secciones accesibles mediante navegacion. El enrutamiento cliente-side permite cambiar el contenido sin recargar la pagina completa, mejorando la experiencia de usuario.
React no incluye enrutamiento nativo, por lo que se recurre a react-router-dom, la libreria estandar para aplicaciones web. Instalala con:
yarn add react-router-dom
En 2025, la version 6.x es la mas utilizada, con mejoras en rendimiento y sintaxis basada en hooks, aunque este tutorial mantiene la aproximacion basada en clases para compatibilidad con create-react-app.
Estructura basica de navegacion
Crea un componente de navegacion persistente. Edita src/App.js y reemplaza el contenido predeterminado por una barra superior con enlaces. Importa los componentes necesarios:
import { Link } from "react-router-dom";
Agrega el siguiente markup dentro del render del componente App:
<nav>
<ul id="navigation">
<li>
<Link to="/">Home</Link>
</li>
<li>
<Link to="/about">About</Link>
</li>
<li>
<Link to="/contact">Contact</Link>
</li>
</ul>
</nav>
El componente Link genera anclas que no recargan la pagina, sino que actualizan la URL y el estado interno del router.
Creacion de componentes de pagina
Divide el contenido en componentes independientes. Crea un archivo src/Home.jsx con el contenido original de App.js:
import React from "react";
import logo from "./logo.svg";
class Home extends React.Component {
render() {
return (
<div className="App">
<header className="App-header">
<img src={logo} className="App-logo" alt="logo" />
<p>
Edit <code>src/App.js</code> and save to reload.
</p>
<a
className="App-link"
href="https://reactjs.org"
target="_blank"
rel="noopener noreferrer"
>
Learn React
</a>
</header>
</div>
);
}
}
export default Home;
Repite el proceso para About.jsx:
import React from "react";
const divStyle = { color: "white" };
class About extends React.Component {
render() {
return (
<div style={divStyle}>
<h2>About Page</h2>
<main>
<p>
This section contains information about the project and
its author.
</p>
</main>
</div>
);
}
}
export default About;
Importa ambos componentes en App.js:
import Home from "./Home";
import About from "./About";
Configuracion de rutas con Switch y Route
Dentro del metodo render de App.js, justo debajo de la navegacion, define las rutas utilizando Switch y Route:
import { Route, Switch } from "react-router-dom";
<Switch>
<Route exact path="/">
<Home />
</Route>
<Route path="/about">
<About />
</Route>
</Switch>;
El atributo exact en la ruta raiz evita coincidencias parciales. Switch garantiza que solo se renderice la primera ruta que coincida. El archivo App.js completo luce asi:
import React from "react";
import { Route, Switch, Link } from "react-router-dom";
import Home from "./Home";
import About from "./About";
import "./App.css";
class App extends React.Component {
render() {
return (
<div className="App">
<nav>
<ul id="navigation">
<li>
<Link to="/">Home</Link>
</li>
<li>
<Link to="/about">About</Link>
</li>
<li>
<Link to="/contact">Contact</Link>
</li>
</ul>
</nav>
<Switch>
<Route exact path="/">
<Home />
</Route>
<Route path="/about">
<About />
</Route>
</Switch>
</div>
);
}
}
export default App;
Envoltura con BrowserRouter y pruebas locales
Para activar el enrutamiento, envuelve la aplicacion en un router. Edita src/index.js:
import { BrowserRouter } from "react-router-dom";
ReactDOM.render(
<React.StrictMode>
<BrowserRouter>
<App />
</BrowserRouter>
</React.StrictMode>,
document.getElementById("root")
);
Ejecuta yarn start y navega entre secciones. La transicion es fluida gracias al enrutamiento cliente-side. Sin embargo, al desplegar con npm run deploy y visitar la version en vivo, al recargar /about aparecera un error 404.
El problema del enrutamiento en GitHub Pages
GitHub Pages sirve archivos estaticos y no interpreta rutas dinamicas del lado del cliente. Cuando el navegador solicita /about directamente, el servidor busca un archivo fisico que no existe, generando el error. La solucion radica en modificar el tipo de router para que todas las rutas se gestionen detras del simbolo # (hash).
Cambio a HashRouter para compatibilidad
Reemplaza BrowserRouter por HashRouter en index.js:
import { HashRouter } from "react-router-dom";
ReactDOM.render(
<React.StrictMode>
<HashRouter>
<App />
</HashRouter>
</React.StrictMode>,
document.getElementById("root")
);
Con HashRouter, las URLs adoptan el formato https://tu-usuario.github.io/starter-project/#/about. El fragmento despues de # es ignorado por el servidor, por lo que siempre sirve index.html, y el router interno interpreta la ruta. Despliegue con hash routing resuelve el problema de recarga.
Ejecuta nuevamente:
npm run deploy
Visita la URL publicada y prueba recargar en cualquier seccion. El contenido se carga correctamente sin errores.
Optimizacion del proceso de despliegue continuo
Para mantener el sitio actualizado, integra el despliegue en el flujo de trabajo. Cada vez que realices cambios, sigue estos pasos:
- Confirma los cambios localmente con git add . y git commit -m “mensaje”.
- Empuja a la rama master con git push.
- Ejecuta npm run deploy.
Alternativamente, automatiza con GitHub Actions. Crea un archivo .github/workflows/deploy.yml:
name: Deploy to GitHub Pages
on:
push:
branches: [master]
jobs:
build-and-deploy:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v3
- name: Setup Node
uses: actions/setup-node@v3
with:
node-version: 20
- run: yarn install
- run: yarn build
- uses: peaceiris/actions-gh-pages@v3
with:
github_token: ${{ secrets.GITHUB_TOKEN }}
publish_dir: ./build
Este workflow construye y despliega automaticamente en cada push a master.
Mejores practicas para aplicaciones React en produccion
Aunque el enfoque basico funciona, considera las siguientes recomendaciones:
- Utiliza Vite en nuevos proyectos para tiempos de construccion mas rapidos.
- Implementa lazy loading con React.lazy y Suspense para rutas secundarias.
- Configura un archivo .env con REACTAPP para variables de entorno.
- Agrega un favicon y meta tags en public/index.html.
- Prueba la accesibilidad con herramientas como Lighthouse.
Manejo de rutas parametricas y protegidas
Para rutas dinamicas como /user/123, emplea:
<Route path="/user/:id">
<UserProfile />
</Route>
Accede al parametro con useParams() en componentes funcionales. Para rutas protegidas, crea un componente PrivateRoute que verifique autenticacion antes de renderizar.
Personalizacion del dominio en GitHub Pages
Si posees un dominio propio, configurarlo es sencillo. En la seccion Pages de GitHub, ingresa el dominio en Custom domain. Actualiza los registros DNS con un registro CNAME apuntando a tu-usuario.github.io. GitHub provee certificados SSL automaticos.
Conclusiones
El despliegue de aplicaciones React con enrutamiento en GitHub Pages representa una solucion eficiente y gratuita para desarrolladores independientes y equipos pequenos. Mediante el uso de gh-pages, HashRouter y una configuracion adecuada del package.json, se logra una experiencia de navegacion fluida sin errores 404. La integracion con GitHub Actions eleva el proceso a un nivel profesional de integracion continua. Este enfoque no solo facilita la publicacion inicial, sino que establece una base solida para iteraciones futuras, manteniendo el codigo sincronizado con la version en vivo de manera automatica y confiable.
