Guía de Instalación Completa

Requisitos del Sistema

Software Requerido

• Node.js 18.0.0 o superior
• npm 8.0.0+
• VS Code (recomendado)
• Git (para control de versiones)

Hardware Recomendado

• CPU: 2 cores o superior
• RAM: 4GB mínimo
• Almacenamiento: 1GB libre mínimo
• Conexión Internet: 5Mbps+

Cuentas Necesarias

• Vercel (para hosting)
• Resend (para emails)
• Lemonsqueezy (opcional, para afiliados)
• Umami (para analytics)

1. Preparación del Entorno

Windows

1. Instala Node.js:

# Usando winget
winget install OpenJS.NodeJS.LTS
# O descarga el instalador de nodejs.org
 
# Verifica instalación
node --version  # debe mostrar 18.x+
npm --version   # debe mostrar 8.x+

macOS

# Instala Homebrew si no lo tienes
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
 
# Instala dependencias
brew install node
 
# Verifica instalaciones
node --version
npm --version

Linux (Ubuntu/Debian)

# Actualiza sistema
sudo apt update && sudo apt upgrade
 
# Instala Node.js
curl -fsSL https://deb.nodesource.com/setup_18.x | sudo -E bash -
sudo apt install -y nodejs
 
# Verifica instalaciones
node --version
npm --version

2. Configuración del Proyecto

1. Prepara el directorio:

cd directory-template

2. Instala todas las dependencias:

npm install
 
# Verifica la instalación correcta
npm run build

3. Configura Variables de Entorno:

# Copia el template
cp .env.example .env.local
 
# Estructura completa del .env.local:
 
# APIs Requeridas
RESEND_API_KEY=re_xxx                    # Requerido para emails
UMAMI_TRACKING_ID=xxx                    # Requerido para analytics
RESEND_SPACEHUNT_AUDIENCE_ID=xxx         # Requerido para newsletter
 
# URLs y Endpoints
NEXT_PUBLIC_BASE_URL=http://localhost:3000

3. Desarrollo Local

1. Inicia el servidor de desarrollo:

npm run dev

2. Verifica en http://localhost:3000

3. Prueba funcionalidades principales:

• Navega el directorio
• Prueba el formulario de contacto
• Prueba el formulario de contribución
• Verifica suscripción newsletter

4. Despliegue en Vercel

1. Prepara el proyecto:

npm run build  # Verifica build local primero

2. Configura Vercel:

• Crea cuenta en Vercel
• Instala Vercel CLI: npm i -g vercel
• Login: vercel login

3. Configura proyecto:

vercel
# Responde las preguntas:
# - Set up and deploy? Yes
# - Directory? ./
# - Override settings? No

4. Configura variables de entorno en Vercel:

• Ve a Dashboard → Settings → Environment Variables
• Copia todas las variables de .env.local
• Asegúrate de agregar NEXT_PUBLIC_BASE_URL

5. Despliega:

vercel --prod

5. Scripts Disponibles

# Desarrollo
npm run dev           # Servidor desarrollo
npm run build        # Construye app
npm run start        # Inicia producción
npm run lint         # Ejecuta linter

6. Solución de Problemas

Problemas Comunes

# Error: Cannot find module
npm install          # Reinstala módulos
rm -rf .next        # Limpia cache
npm run build       # Reconstruye
 
# Error: API Keys
- Verifica configuración en .env.local
- Comprueba variables en Vercel
- Verifica límites de API
 
# Error: Build
npm clean           # Limpia build
npm install --force # Fuerza reinstalación

7. Verificación Final

Checklist Local

1. ✓ Servidor inicia sin errores
2. ✓ Directorio carga datos
3. ✓ Formularios funcionan
4. ✓ Newsletter suscribe correctamente
5. ✓ UI responde correctamente

Checklist Producción

1. ✓ Build completa sin errores
2. ✓ Todas las variables están configuradas
3. ✓ Emails funcionan
4. ✓ Analytics registra datos
5. ✓ Performance es óptima

Monitoreo

1. Verifica logs en Vercel
2. Monitorea uso de Resend
3. Revisa analytics en Umami
4. Comprueba métricas de performance

8. Optimización

Performance

1. Implementa caché de imágenes
2. Optimiza carga de componentes
3. Minimiza JavaScript
4. Usa imágenes optimizadas

Costos

1. Monitorea uso de APIs
2. Optimiza envío de emails
3. Usa tier gratuito cuando posible
4. Implementa límites de uso