Como alojar tu proyecto Nuxt en GitHub Pages
Nuxt se ha consolidado como uno de los frameworks mas populares para crear aplicaciones web modernas con Vue. Aunque ofrece renderizado del lado del servidor SSR, muchos proyectos pueden desplegarse como sitios estaticos sin problema. Para proyectos personales, portafolios o apps pequeñas, GitHub Pages es una opcion gratuita y sencilla.
En esta guia veras el proceso completo para desplegar un proyecto Nuxt en GitHub Pages usando generacion estatica.
Por que elegir GitHub Pages
Hospedaje gratuito para repositorios publicos.
Integracion simple con GitHub Actions para despliegue continuo.
Ideal para sitios personales, documentacion y aplicaciones pequeñas.
Como GitHub Pages solo sirve archivos estaticos HTML CSS JavaScript, en Nuxt debes usar SSG generacion estatica.
Paso 1 Configurar nuxt.config.ts
En el archivo nuxt.config.ts desactiva SSR y define la base correcta para las rutas.
Configura las opciones clave asi sin usar comillas:
ssr en falso para desactivar el renderizado del lado del servidor
app baseURL en barra nombre-del-repo barra por ejemplo barra nuxt-portfolio barra
nitro preset en github-pages
Ejemplo si tu repositorio se llama nuxt-portfolio el sitio quedara en https://tu-usuario.github.io/nuxt-portfolio y por ello la base debe ser barra nuxt-portfolio barra.
Paso 2 Generar archivos estaticos
Ejecuta el comando yarn generate.
Esto construye tu proyecto Nuxt en la carpeta dist con HTML CSS y JavaScript estaticos.
Paso 3 Agregar un workflow de GitHub Actions
Crea el archivo .github workflows deploy.yml para automatizar el despliegue en cada push.
Configuracion recomendada para proyectos con Yarn 4 o superior
Evento push sobre la rama master o main segun tu repositorio
Permisos contents write para permitir publicar en la rama gh-pages
Job deploy en ubuntu-latest con estos pasos
Checkout del codigo con actions checkout v3
Configuracion de Node con actions setup-node v3 usando node-version 22
Habilitar Corepack con corepack enable
Usar la version de Yarn definida en packageManager con corepack use yarn
Instalacion de dependencias con yarn install --immutable
Generacion del sitio con yarn generate
Publicacion con peaceiris actions-gh-pages v3 usando github_token secrets GITHUB_TOKEN y publish_dir ./dist
Este workflow
1 Se ejecuta en cada push a master o main
2 Instala Node y Yarn
3 Genera el sitio con yarn generate
4 Despliega la carpeta dist en la rama gh-pages
Paso 4 Activar GitHub Pages
Tras el primer despliegue exitoso
1 Entra a tu repositorio en GitHub y ve a Settings Pages
2 En Source elige la rama gh-pages y la carpeta raiz
3 Guarda los cambios
En unos minutos tu sitio estara disponible en https://tu-usuario.github.io/tu-repo barra
Problemas frecuentes y como resolverlos
Pagina en blanco o assets que no cargan revisa app baseURL en nuxt.config.ts y asegurate de incluir la barra inicial y final
Error 403 permission denied verifica que en el workflow tengas permissions contents write
Version de Yarn incorrecta habilita Corepack y usa la version declarada en packageManager
Conclusion
Alojar tu proyecto Nuxt en GitHub Pages es una solucion economica y directa para sitios estaticos. Con GitHub Actions puedes recompilar y desplegar automaticamente en cada push. Es perfecto para portafolios personales, documentacion y aplicaciones ligeras. Si mas adelante necesitas SSR o integraciones con APIs, puedes migrar sin problema a plataformas como Vercel o Netlify.
Listo ya tienes tu app Nuxt funcionando gratis en GitHub Pages