🚀 Guía Definitiva: Cómo subir tu proyecto Next.js a GitHub

¡Hola! Sé que subir tu primer proyecto a GitHub puede parecer un laberinto de comandos y errores extraños, pero no te preocupes. He preparado esta guía para que puedas hacerlo paso a paso, sin frustraciones y como todo un profesional.

📑 Índice de Contenidos

El Cimiento: El archivo .gitignore
Paso a Paso: Tu primera subida remota
Conexión con el Mundo (GitHub)
El día a día: Subir cambios nuevos
🛠️ ¿Algo salió mal? Solución de errores
💡 Consejos de Oro de programador

1. El Cimiento: El archivo `.gitignore`

Antes de tocar Git, hay una regla de oro en Next.js: No subas archivos basura. Para eso usamos el .gitignore.

[!IMPORTANT] > ¿Por qué te importa esto? Sin esto regalarías tus contraseñas o subirías la carpeta node_modules (que pesa muchísimo). Créeme, no quieres que tu repositorio sea un caos lento de manejar. Asegúrate de que esté en la raíz de tu proyecto.

2. Paso a Paso: La Primera Subida (Setup)

Sigue estos comandos en tu terminal de VS Code con cuidado:

Paso A: Inicializar Git

git init

Esto crea el "cerebro" de Git en tu carpeta local. Solo se hace una vez por proyecto.

Paso B: El "Semáforo" (git status)

git status

Úsalo siempre. Te dirá en rojo qué archivos han cambiado y no están guardados aún. Es tu mejor amigo para evitar errores.

Paso C: Preparar los archivos

git add .

Esto pone todos tus archivos en "verde" (zona de espera). Es como preparar las maletas antes del viaje.

Paso D: Guardar la versión (Commit)

git commit -m "Mi primer despliegue: Next.js PWA"

Aquí "cierras la maleta". Le pones una etiqueta descriptiva para saber qué cambios hiciste en esta versión.

3. Conexión con el Mundo (GitHub)

Sigue estos pasos para vincular tu código local con la nube:

Ve a GitHub.com/new y crea un repositorio vacío.
NO selecciones "Add a README" ni "Add .gitignore" (ya los tenemos). GitHub debe estar totalmente limpio.
Copia la URL que termina en .git (la verás en el cuadro rápido de GitHub).
En tu terminal, escribe estos 3 comandos maestros:

# 1. Creamos la rama principal 'main'
git branch -M main

# 2. Conectamos tu PC con GitHub (Sustituye por TU URL)
git remote add origin https://github.com/TU_USUARIO/TU_REPO.git

# 3. Subimos el código por primera vez
git push -u origin main

4. ¿Cómo subir cambios nuevos? (Día a día)

Una vez configurado, subir tus mejoras diarias es pan comido:

git add . (Mete los cambios en la maleta)
git commit -m "Añadí nueva característica" (Etiqueta la maleta)
git push (Envía la maleta a GitHub)

🛠️ ¿Algo salió mal? Solución de errores

No entres en pánico, a todos nos pasa. Aquí tienes los errores más típicos y cómo los arreglamos en un segundo:

🚩 "remote origin already exists"

¿Qué pasó? Ya habías intentado conectar este proyecto a otro repositorio antes. Solución: Borra el rastro antiguo con git remote remove origin y luego vuelve a intentar el remote add con tu nueva URL.

🚩 "failed to push some refs"

¿Qué pasó? GitHub y tu PC no están sincronizados (normalmente porque creaste el repo con un README en la web). Solución: Lo más fácil es borrar el repo en GitHub y crearlo de nuevo totalmente vacío. Esta vez funcionará.

🚩 "remote: Not Found"

¿Qué pasó? Hay una errata en la URL o no tienes permisos. Solución: Copia y pega la URL directamente de GitHub. Ojo con las mayúsculas y minúsculas, ¡Git es muy estricto!

🚩 "Everything up-to-date"

¿Qué pasó? Git cree que no hay nada nuevo que subir. Solución: ¿Hiciste el commit? Recuerda: siempre es git add . -> git commit -m "mensaje" -> git push. Sin commit, no hay viaje para GitHub.

🚩 "ERROR: Turbopack..."

¿Qué pasó? Next.js 16 es moderno y usa Turbopack, pero la PWA que estamos haciendo necesita el motor clásico (Webpack). Solución: Ve a tu package.json y asegúrate de que el script de build diga "next build --webpack".

🚩 "Event handlers cannot be passed..."

¿Qué pasó? Intentaste usar un botón o algo interactivo en un "Server Component". Solución: Simplemente escribe "use client"; al principio de todo en ese archivo. ¡Listo!

💡 Consejos de Oro

Mensajes claros: En lugar de "cambios", usa "Corregido error en el botón de navegación".
Vercel: Si conectas tu repo a Vercel, cada git push actualizará tu web automáticamente.
Frecuencia: Haz commits pequeños y seguidos. Es más fácil arreglar un error pequeño que uno gigante de hace 3 días.

Documentación creada profesionalmente para el flujo de trabajo con Next.js 16.1.1+.