🚀 Guía de Instalación de Next.js desde Cero (Paso a Paso)

Esta guía documenta detalladamente el proceso para instalar y configurar un entorno de desarrollo para Next.js comenzando desde cero absoluto (sin tener nada preinstalado), cubriendo la instalación de herramientas clave, configuración con Tailwind CSS, problemas comunes de instalación y consejos prácticos.

🏗️ Requisitos Previos y Herramientas

Para desarrollar con Next.js, necesitas preparar tu entorno con las siguientes herramientas fundamentales:

Node.js (Entorno de ejecución): Next.js es un framework de React que se ejecuta tanto en el servidor como en el cliente. Requiere una versión moderna de Node.js.
Gestor de Paquetes (npm, pnpm o yarn): Para descargar y gestionar las dependencias del proyecto.
Git (Control de versiones): Indispensable para llevar el control de cambios e integrar tu código con GitHub u otras plataformas.
Editor de Código: Se recomienda Visual Studio Code (VS Code) con extensiones útiles como ESLint, Prettier y Tailwind CSS IntelliSense.

📋 Paso a Paso de la Instalación

Paso 1: Instalar Node.js y npm

Si no tienes Node.js en tu sistema, sigue estos pasos según tu sistema operativo:

Windows / macOS:
1. Ve al sitio oficial: nodejs.org.
2. Descarga la versión LTS (Long Term Support) recomendada para la mayoría de los usuarios.
3. Ejecuta el instalador y sigue los pasos del asistente (asegúrate de marcar la casilla para añadir Node a la variable de entorno PATH).

Linux (Ubuntu/Debian): Instala usando NodeSource para asegurar una versión actualizada:

curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash -
sudo apt-get install -y nodejs

✨ Consejo: Usa un gestor de versiones (NVM): Para evitar problemas de permisos y poder cambiar fácilmente de versión de Node.js entre proyectos, es altamente recomendable usar nvm-windows (en Windows) o nvm (en macOS/Linux).
nvm install 20
nvm use 20

Para verificar que la instalación fue exitosa, abre tu terminal y ejecuta:

node -v
npm -v

Paso 2: Crear el Proyecto Next.js

La forma oficial y recomendada de inicializar una aplicación Next.js es utilizando la herramienta interactiva create-next-app.

Abre tu terminal y navega a la carpeta donde deseas crear tu proyecto:
```
cd ruta/a/tus/proyectos
```

Ejecuta el asistente de creación:

npx create-next-app@latest mi-proyecto-next

El asistente te hará una serie de preguntas de configuración. A continuación te explicamos las opciones recomendadas:

Pregunta	Opción Recomendada	Razón
Would you like to use TypeScript?	Yes	Aporta tipado estático, previene bugs y mejora el autocompletado notablemente.
Would you like to use ESLint?	Yes	Te ayuda a mantener un código limpio y a seguir buenas prácticas de React/Next.js.
Would you like to use Tailwind CSS?	Yes	El estándar de diseño actual. Configura estilos modernos rápidamente con utilidades integradas de forma nativa.
Would you like to use `src/` directory?	Yes	Excelente para separar el código fuente de los archivos de configuración en la raíz del proyecto.
Would you like to use App Router?	Yes	Es el router moderno y recomendado por Next.js que soporta Server Components y layouts anidados de forma eficiente.
Would you like to customize the default import alias (@/)*?	No	Deja el valor por defecto `@/*` para hacer importaciones limpias relativas a la carpeta `src`.

Paso 3: Integración de Tailwind CSS (Opciones y Versiones)

Al elegir Yes en el asistente, create-next-app instalará y configurará Tailwind CSS automáticamente. Dependiendo de la versión de Next.js/Tailwind instalada, la estructura de configuración puede variar:

Opción A: Tailwind CSS v3 (Por defecto en la mayoría de plantillas)

Archivo de Configuración: tailwind.config.ts (en la raíz).

Uso de CSS: En src/app/globals.css verás las directivas base:

@tailwind base;
@tailwind components;
@tailwind utilities;

Opción B: Tailwind CSS v4 (Nueva versión CSS-first)

Si el asistente instala Tailwind v4 o si decides actualizarlo:

Sin archivo JS/TS: Tailwind v4 ya no requiere un archivo tailwind.config.js obligatorio, todo se configura directamente en tu CSS.
Uso de CSS: En src/app/globals.css, verás la nueva importación simplificada:
```
@import "tailwindcss";
```
Las variables y configuraciones personalizadas se definen usando la regla @theme dentro de ese mismo archivo CSS.

Paso 4: Levantar el Servidor de Desarrollo

Una vez completada la instalación:

Entra a la carpeta del proyecto creado:
```
cd mi-proyecto-next
```
Levanta el servidor local de desarrollo:
```
npm run dev
```
Abre tu navegador e ingresa a http://localhost:3000 para ver tu nueva aplicación Next.js funcionando.

⚠️ Precauciones y Errores Comunes

1. Error de Script Deshabilitado en Windows (PowerShell)

Síntoma: Al ejecutar npx o npm run dev obtienes un error tipo: "... no se puede cargar porque la ejecución de scripts está deshabilitada en este sistema."
Causa: La política de ejecución de scripts de Windows restringe la ejecución de archivos .ps1 no firmados.
Solución: Abre PowerShell como Administrador y ejecuta:
```
Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope LocalMachine
```
Confirma con Y (Sí) y reinicia tu terminal.

2. Versión de Node.js Desactualizada

Síntoma: Errores extraños durante la descarga de paquetes o un mensaje de error explícito diciendo que Next.js requiere una versión superior de Node.js.
Causa: Tienes una versión antigua de Node.js (ej. Node 16 o inferior). Next.js requiere Node.js 18.17.0 o superior.
Solución: Actualiza tu versión de Node.js descargando la versión LTS más reciente o usando tu gestor de versiones (NVM):
```
nvm install 20
nvm use 20
```

3. Problemas de Permisos con npm (`EACCES: permission denied`)

Síntoma: Errores al instalar dependencias globales o locales en sistemas macOS o Linux.
Causa: El directorio de node_modules o el caché de npm requiere permisos de administrador (root), frecuentemente causados por instalar previamente cosas con sudo.
Solución: Cambia la propiedad del directorio de trabajo al usuario actual (reemplaza tu-usuario por tu nombre de usuario local):
```
sudo chown -R $(whoami) ~/.npm
sudo chown -R $(whoami) /ruta/a/tu/proyecto
```
Nota: Nunca uses sudo npm install para dependencias locales de tu proyecto.

4. Conflictos con el puerto 3000 (`Port 3000 is already in use`)

Síntoma: Al correr npm run dev el servidor no inicia o levanta en un puerto alternativo (ej. 3001).
Causa: Tienes otro servidor local u otra app corriendo en el puerto 3000.
Solución: Puedes cerrar el proceso anterior, o bien forzar a Next.js a correr en otro puerto configurando la propiedad -p en tu comando de arranque:
```
npx next dev -p 3005
```
(O modifica el script "dev": "next dev" en tu package.json a "dev": "next dev -p 3005").

💡 Tips y Buenas Prácticas

🚀 Usa pnpm en lugar de npm: pnpm es significativamente más rápido y ahorra mucho espacio en disco al no duplicar dependencias físicamente en cada proyecto. Puedes instalarlo globalmente y usarlo para crear tus apps:
```
npm install -g pnpm
pnpm create next-app
pnpm dev
```
📦 Define la versión de Node en el proyecto: Crea un archivo .nvmrc en la raíz de tu proyecto con el número de versión (ej. 20) para que otros desarrolladores en el equipo utilicen la misma versión de Node.js ejecutando simplemente nvm use.
🔒 Mantén tu .gitignore actualizado: Asegúrate de que archivos como .env.local (donde almacenarás API keys privadas) estén listados en tu .gitignore para no subirlos por accidente a repositorios públicos de GitHub.