Implementar una aplicación Vite/React en páginas de GitHub es un hito emocionante, pero el proceso a veces puede presentar desafíos inesperados, especialmente cuando se trata de imágenes y recursos. Esta publicación de blog lo guiará a través de todo el proceso, desde la implementación inicial hasta la resolución de problemas comunes y la búsqueda de soluciones efectivas.

Ya sea que seas un principiante o alguien con experiencia, esta guía te ayudará a evitar errores comunes e implementar con éxito tu aplicación Vite/React con todos los recursos renderizados correctamente.

Requisitos previos

Antes de profundizar, asegúrese de tener lo siguiente:

• Un proyecto de Vite/React: Esta guía asume que has configurado tu proyecto usando Vite como herramienta de compilación y React como marco.
• Repositorio de GitHub: Deberías tener un repositorio de GitHub existente donde impulsarás tu aplicación para su implementación.
• Páginas de GitHub habilitadas: asegúrese de que las páginas de GitHub estén habilitadas en la configuración de su repositorio para su implementación.

Paso 1: inicializar el proyecto y la implementación de páginas de GitHub

Primero, asegúrese de que su aplicación Vite/React esté correctamente inicializada y funcione en localhost. Puede crear un proyecto Vite básico de la siguiente manera:

npm create vite@latest

Instalar dependencias:

npm install

Ejecute el proyecto localmente para confirmar que todo funciona:

npm run dev

Una vez que tu proyecto esté listo, envíalo a tu repositorio de GitHub.

Cree un vite.config.js para páginas de GitHub

GitHub Pages espera que la aplicación se entregue desde una URL base específica, que normalmente es el nombre de su repositorio. Actualice el archivo vite.config.js para reflejar esto:

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

export default defineConfig({
  base: process.env.NODE_ENV === 'production' ? '/your-repo-name/' : '/',
  plugins: [react()],
})

La opción base garantiza que la aplicación utilice la ruta base correcta cuando se implemente.

Paso 2: construir e implementar el proyecto

Deberás instalar el paquete gh-pages para manejar la implementación.

npm install gh-pages --save-dev

En su paquete.json, agregue los siguientes scripts para automatizar el proceso de implementación:

"scripts": {
  "predeploy": "npm run build",
  "deploy": "gh-pages -d dist"
}

Ejecutar la implementación:

npm run deploy

En este punto, tu proyecto debería estar activo en https://.github.io//, pero si eres como yo, es posible que tengas algunos problemas. con la aplicación no se procesa correctamente o las imágenes no se muestran.

Paso 3: Problemas comunes y soluciones

Problema 1: página en blanco después de la implementación

Después de la implementación, es posible que notes que la aplicación carga una página en blanco. Esto suele deberse a problemas de enrutamiento. De forma predeterminada, se utiliza BrowserRouter de react-router-dom, que se basa en el enrutamiento del lado del servidor, pero GitHub Pages sirve archivos estáticos y no maneja rutas del lado del cliente.

Solución: usar HashRouter

Para resolver esto, cambie de BrowserRouter a HashRouter en su archivo index.js o main.jsx.

Nota: No es necesario que tengas la, solo es una biblioteca de interfaz de usuario conveniente que uso muy a menudo en mis proyectos.

import { HashRouter } from 'react-router-dom';

createRoot(document.getElementById('root')).render(
  
);

HashRouter usa un símbolo de almohadilla (#) en la URL para realizar un seguimiento del estado de navegación, lo que permite que las páginas de GitHub sirvan correctamente diferentes rutas sin devolver un 404.

Problema 2: Error 404 al actualizar u otras rutas

Después de solucionar el problema de la página en blanco, otro problema que puedes enfrentar es que la aplicación funciona en la página de inicio pero muestra un error 404 al navegar a otras rutas, especialmente si accedes directamente a una ruta como /blogs o /projects.

Esto sucede porque GitHub Pages solo sabe cómo servir el archivo index.html y no reconoce las rutas administradas por React Router.

Solución: Manejar errores 404 en la configuración de páginas de GitHub

Para solucionar este problema, debe crear un archivo 404.html en su carpeta pública/. Este archivo garantizará que GitHub Pages proporcione su archivo index.html para cualquier ruta que no reconozca, permitiendo que React Router maneje el enrutamiento:

1. Copia tu index.html a un nuevo archivo llamado 404.html.
2. Coloque este archivo en su carpeta pública/.
3. Reconstruir y volver a implementar el proyecto.

Problema 3: las imágenes no se cargan en producción

Uno de los problemas de implementación más comunes es que las imágenes no se cargan correctamente. Si bien funcionan bien en localhost, es posible que notes enlaces de imágenes rotos después de implementarlos en GitHub Pages.

Por ejemplo, podrías hacer referencia a una imagen como esta en tus componentes:

Problema: Rutas de imagen incorrectas

El problema aquí es que las rutas absolutas (que comienzan con /) no funcionan bien cuando la aplicación se implementa en un subdirectorio (por ejemplo, /tu-nombre-de-repo/). GitHub Pages intenta encontrar la imagen en https://.github.io/Images/myImage.png en lugar de https://.github.io/your-repo-name/Images/myImage.png , lo que genera un error 404.

Solución: usar BASE_URL

Para solucionar este problema, mueva todas sus imágenes a Público/Imágenes. Si bien esto es opcional, le recomiendo encarecidamente que lo haga. Luego antepondrá dinámicamente BASE_URL a las rutas de las imágenes según el entorno:

1. Defina una constante BASE_URL que dependa del entorno:

   const BASE_URL = import.meta.env.BASE_URL;

1. Utilice esta BASE_URL cuando haga referencia a imágenes:

NOTA: No olvides eliminar el / delante de Imágenes, de lo contrario lo tendrás duplicado, uno de BASE_URL y otro de /Images que olvidaste eliminar.

Esto garantiza que se utilice la ruta correcta tanto en desarrollo (localhost) como en producción (GitHub Pages).

Paso 4: Implementación final

Después de implementar las correcciones para el enrutamiento y las rutas de imágenes, reconstruya y vuelva a implementar su aplicación:

npm run build
npm run deploy

Su aplicación Vite/React ahora debería estar completamente implementada con todas las imágenes renderizadas correctamente y todas las rutas manejadas correctamente.

En resumen:

1. Problemas de enrutamiento: use HashRouter para un enrutamiento adecuado en implementaciones estáticas como GitHub Pages.
2. Errores 404 en rutas: cree un archivo 404.html para garantizar que GitHub Pages proporcione su aplicación correctamente.
3. Las imágenes no se cargan: mueva todas las imágenes a Público/Imágenes y agregue dinámicamente BASE_URL a las rutas de sus activos para manejar los entornos de desarrollo y producción.

Con estos pasos, tu aplicación Vite/React debería estar activa y funcionando sin problemas en GitHub Pages. ¡Feliz codificación e implementación!