roi-theme/wp-content/themes/apus-theme/docs/CORE-WEB-VITALS-OPTIMIZATION.md

# Guía de Optimización Core Web Vitals - Apus Theme

## Tabla de Contenidos

1. [Introducción](#introducción)
2. [Métricas Core Web Vitals](#métricas-core-web-vitals)
3. [Optimizaciones Implementadas](#optimizaciones-implementadas)
4. [Configuración del Servidor](#configuración-del-servidor)
5. [Testing y Medición](#testing-y-medición)
6. [Mejores Prácticas](#mejores-prácticas)
7. [Troubleshooting](#troubleshooting)

---

## Introducción

El tema **Apus Theme** ha sido diseñado desde el inicio con un enfoque en **rendimiento perfecto** y **Core Web Vitals óptimos**. Este documento detalla todas las optimizaciones implementadas y cómo mantener un rendimiento excepcional.

### Objetivos de Rendimiento

- **LCP (Largest Contentful Paint)**: < 2.5 segundos
- **FID/INP (First Input Delay / Interaction to Next Paint)**: < 100ms
- **CLS (Cumulative Layout Shift)**: < 0.1
- **PageSpeed Insights Score**: 90-100 (móvil y desktop)

---

## Métricas Core Web Vitals

### LCP - Largest Contentful Paint

**¿Qué mide?**: Tiempo que tarda en renderizarse el elemento de contenido más grande visible en el viewport.

**Elementos comunes de LCP**:
- Imágenes destacadas (featured images)
- Hero images
- Bloques de texto grandes
- Elementos de video

**Optimizaciones implementadas**:
- ✅ Preload de imágenes críticas (featured images)
- ✅ Lazy loading de imágenes below-the-fold
- ✅ Formato WebP/AVIF para imágenes
- ✅ Responsive images con srcset
- ✅ Preload de fuentes críticas
- ✅ Preload de CSS crítico (Bootstrap, fonts)
- ✅ DNS prefetch y preconnect para recursos externos
- ✅ Eliminación de recursos render-blocking

### FID/INP - First Input Delay / Interaction to Next Paint

**¿Qué mide?**: Tiempo desde que el usuario interactúa con la página hasta que el navegador puede responder.

**Optimizaciones implementadas**:
- ✅ Eliminación de jQuery (JavaScript bloqueante)
- ✅ Scripts con defer strategy
- ✅ Código JavaScript mínimo y optimizado
- ✅ Event delegation para reducir listeners
- ✅ Desactivación del Heartbeat API en frontend
- ✅ Minimización de JavaScript bloqueante

### CLS - Cumulative Layout Shift

**¿Qué mide?**: Cambios de layout inesperados durante la carga de la página.

**Optimizaciones implementadas**:
- ✅ Dimensiones explícitas en todas las imágenes (width/height)
- ✅ Aspect ratio CSS para contenedores de medios
- ✅ Font-display: swap en fuentes locales
- ✅ Espacios reservados para ads (AdSense delay)
- ✅ Sin inyección dinámica de contenido above-the-fold
- ✅ Header sticky sin afectar layout

---

## Optimizaciones Implementadas

### 1. Eliminación de Bloat de WordPress

**Archivo**: `inc/performance.php`

- ❌ Emojis deshabilitados
- ❌ oEmbed deshabilitado
- ❌ Feeds RSS deshabilitados
- ❌ RSD/WLW manifest deshabilitados
- ❌ Dashicons para usuarios no logueados
- ❌ Block Library CSS (Gutenberg)
- ❌ XML-RPC deshabilitado
- ❌ jQuery Migrate removido
- ❌ Admin bar para no-admins deshabilitado

### 2. Resource Hints

**Archivo**: `inc/performance.php`

```php
// DNS Prefetch para recursos externos
- https://cdn.jsdelivr.net (Bootstrap Icons)
- https://www.google-analytics.com
- https://www.googletagmanager.com
- https://pagead2.googlesyndication.com (AdSense)

// Preconnect para recursos críticos
- https://cdn.jsdelivr.net (con crossorigin)
```

### 3. Preload de Recursos Críticos

**Archivo**: `inc/performance.php`

```php
// Fuentes
- inter-var.woff2
- inter-var-italic.woff2

// CSS
- bootstrap.min.css
- fonts.css

// Imágenes (featured images)
- Automático en inc/image-optimization.php
```

### 4. Optimización de JavaScript

**Archivo**: `inc/enqueue-scripts.php`

Todos los scripts utilizan:
```php
array(
    'in_footer' => true,
    'strategy'  => 'defer',
)
```

Scripts incluidos:
- ✅ Bootstrap JS Bundle (defer)
- ✅ Header JS (defer)
- ✅ Main JS (defer)
- ✅ Accessibility JS (defer)
- ✅ AdSense Loader (defer)
- ✅ TOC JS (defer, solo en single posts)

### 5. Optimización de CSS

**Critical CSS**: Disponible pero desactivado por defecto
- Archivo: `inc/critical-css.php`
- Activar en: Customizer > Performance Optimization
- CSS crítico inline por tipo de página
- CSS no crítico cargado asíncronamente

**CSS Loading Order**:
1. Fuentes (fonts.css) - Priority 1
2. Bootstrap CSS - Priority 5
3. Header CSS - Priority 10
4. Custom styles - Priority 11
5. Footer CSS - Priority 12
6. Theme core - Priority 13
7. Utilities - Priority 13

### 6. Optimización de Imágenes

**Archivo**: `inc/image-optimization.php`

Características:
- ✅ Soporte WebP y AVIF
- ✅ Lazy loading nativo (loading="lazy")
- ✅ Dimensiones explícitas (width/height)
- ✅ Srcset responsive automático
- ✅ Sizes attribute optimizado por contexto
- ✅ Fetchpriority="high" en featured images
- ✅ Decoding="async" en todas las imágenes
- ✅ Primera imagen del contenido sin lazy loading (posible LCP)
- ✅ Preload automático de featured images en posts/pages

Tamaños de imagen:
```php
- apus-thumbnail: 400x300
- apus-medium: 800x600
- apus-large: 1200x900
- apus-featured-large: 1200x600
- apus-featured-medium: 800x400
- apus-hero: 1920x800
- apus-card: 600x400
```

### 7. Optimización de Fuentes

**Archivo**: `assets/css/fonts.css`

- ✅ Fuentes locales (no Google Fonts)
- ✅ Format WOFF2 (mejor compresión)
- ✅ Font-display: swap
- ✅ Preload de fuentes críticas
- ✅ Variable fonts (Inter VF)
- ✅ Subset latino solo

### 8. Optimización de Base de Datos

**Archivo**: `inc/performance.php`

- ✅ Límite de posts por página en archives (12)
- ✅ Optimización de WP_Query
- ✅ Self-pingbacks deshabilitados
- ✅ Limpieza periódica de transients expirados
- ✅ Reducción de queries innecesarias

**Recomendación en wp-config.php**:
```php
// Limitar revisiones de posts
define('WP_POST_REVISIONS', 5);

// Aumentar memoria si es necesario
define('WP_MEMORY_LIMIT', '256M');
```

### 9. AdSense Delay Loading

**Archivo**: `inc/adsense-delay.php` y `assets/js/adsense-loader.js`

- ✅ Carga de AdSense solo después de la primera interacción
- ✅ Detecta scroll, click, touch, mousemove
- ✅ Timeout de 5 segundos si no hay interacción
- ✅ Mejora significativa en Core Web Vitals

### 10. Heartbeat API

**Archivo**: `inc/performance.php`

- ✅ Desactivado completamente en frontend
- ✅ Reducido a 60 segundos en admin (default: 15s)

---

## Configuración del Servidor

### Requisitos Mínimos

- PHP 8.0 o superior (recomendado: 8.2+)
- MySQL 5.7+ o MariaDB 10.3+
- Apache 2.4+ o Nginx 1.18+
- Extensión GD o Imagick con soporte WebP/AVIF

### Apache (.htaccess)

```apache
# Compresión Gzip/Brotli
<IfModule mod_deflate.c>
    AddOutputFilterByType DEFLATE text/html text/plain text/xml text/css text/javascript application/javascript application/x-javascript application/json
</IfModule>

# Browser Caching
<IfModule mod_expires.c>
    ExpiresActive On

    # Images
    ExpiresByType image/jpg "access plus 1 year"
    ExpiresByType image/jpeg "access plus 1 year"
    ExpiresByType image/png "access plus 1 year"
    ExpiresByType image/webp "access plus 1 year"
    ExpiresByType image/avif "access plus 1 year"
    ExpiresByType image/svg+xml "access plus 1 year"
    ExpiresByType image/x-icon "access plus 1 year"

    # CSS and JavaScript
    ExpiresByType text/css "access plus 1 month"
    ExpiresByType application/javascript "access plus 1 month"
    ExpiresByType text/javascript "access plus 1 month"

    # Fonts
    ExpiresByType font/woff2 "access plus 1 year"
    ExpiresByType font/woff "access plus 1 year"
    ExpiresByType font/ttf "access plus 1 year"

    # Default
    ExpiresDefault "access plus 2 days"
</IfModule>

# Cache-Control Headers
<IfModule mod_headers.c>
    # Assets inmutables
    <FilesMatch "\.(jpg|jpeg|png|gif|webp|avif|ico|svg|woff2|woff|ttf)$">
        Header set Cache-Control "public, max-age=31536000, immutable"
    </FilesMatch>

    # CSS y JS
    <FilesMatch "\.(css|js)$">
        Header set Cache-Control "public, max-age=2592000"
    </FilesMatch>
</IfModule>

# MIME Types
<IfModule mod_mime.c>
    AddType image/webp .webp
    AddType image/avif .avif
    AddType font/woff2 .woff2
</IfModule>
```

### Nginx

```nginx
# Compresión Gzip
gzip on;
gzip_vary on;
gzip_min_length 1024;
gzip_types text/plain text/css text/xml text/javascript application/x-javascript application/xml+rss application/json application/javascript;

# Browser Caching
location ~* \.(jpg|jpeg|png|gif|webp|avif|ico|svg)$ {
    expires 1y;
    add_header Cache-Control "public, immutable";
}

location ~* \.(woff2|woff|ttf)$ {
    expires 1y;
    add_header Cache-Control "public, immutable";
}

location ~* \.(css|js)$ {
    expires 30d;
    add_header Cache-Control "public";
}

# MIME Types
types {
    image/webp webp;
    image/avif avif;
    font/woff2 woff2;
}
```

### Plugins Recomendados

**NO instalar plugins de caché pesados** (WP Rocket, W3 Total Cache, etc.)

El tema ya está optimizado. Solo considerar:
- ✅ **Redis Object Cache** o **Memcached** (caché de objetos)
- ✅ **Autoptimize** o **Asset CleanUp** (solo si necesario)
- ❌ **NO usar** plugins de lazy loading (ya implementado)
- ❌ **NO usar** plugins de minificación agresiva

---

## Testing y Medición

### Herramientas

1. **PageSpeed Insights**
   - URL: https://pagespeed.web.dev/
   - Medir tanto móvil como desktop
   - Verificar CrUX (field data) cuando esté disponible

2. **Lighthouse (Chrome DevTools)**
   - Chrome DevTools > Lighthouse
   - Modo incógnito para evitar extensiones
   - Throttling: Mobile/Desktop
   - Categorías: Performance, Accessibility, Best Practices, SEO

3. **WebPageTest**
   - URL: https://www.webpagetest.org/
   - Test desde múltiples ubicaciones
   - Configurar conexión 3G/4G
   - Film strip view para identificar LCP

4. **Chrome User Experience Report (CrUX)**
   - URL: https://developers.google.com/web/tools/chrome-user-experience-report
   - Datos reales de usuarios
   - Disponible después de suficiente tráfico

### Checklist de Testing

Antes de lanzar a producción:

- [ ] PageSpeed Insights - Móvil: 90+
- [ ] PageSpeed Insights - Desktop: 90+
- [ ] Lighthouse Performance: 100
- [ ] Lighthouse Accessibility: 90+
- [ ] Lighthouse Best Practices: 100
- [ ] Lighthouse SEO: 100
- [ ] LCP < 2.5s (móvil y desktop)
- [ ] FID/INP < 100ms
- [ ] CLS < 0.1
- [ ] Testing en 3G lento
- [ ] Testing en diferentes dispositivos
- [ ] Testing con diferentes tamaños de imagen
- [ ] Testing con AdSense activado

### Métricas a Monitorear

**Semanalmente**:
- Core Web Vitals (LCP, FID/INP, CLS)
- PageSpeed Score
- Tiempo de carga total
- Número de requests HTTP
- Tamaño total de página

**Mensualmente**:
- Auditoría completa con Lighthouse
- Revisión de imágenes no optimizadas
- Limpieza de plugins/código innecesario
- Actualización de dependencias

---

## Mejores Prácticas

### Para Contenido

1. **Imágenes**
   - Usar tamaños de imagen apropiados (no subir 5MB)
   - Comprimir antes de subir (TinyPNG, ImageOptim)
   - Usar formato WebP/AVIF cuando sea posible
   - Agregar alt text descriptivo
   - Especificar dimensiones siempre

2. **Videos**
   - Usar lazy loading (loading="lazy")
   - Considerar poster image para videos
   - Hostear en YouTube/Vimeo (no subir directo)
   - Usar iframe con loading="lazy"

3. **Embeds**
   - Minimizar embeds de redes sociales
   - Usar lazy loading para iframes
   - Considerar screenshots con enlace en lugar de embeds

### Para Desarrollo

1. **CSS**
   - No agregar archivos CSS adicionales innecesarios
   - Usar clases de Bootstrap cuando sea posible
   - Minimizar CSS custom
   - No usar !important excesivamente

2. **JavaScript**
   - Mantener jQuery deshabilitado
   - Usar JavaScript nativo o Bootstrap JS
   - Siempre cargar scripts con defer
   - Evitar librerías pesadas (moment.js, etc.)

3. **Fuentes**
   - No agregar fuentes adicionales
   - Usar solo los pesos necesarios
   - Mantener fuentes locales (no CDN)
   - Usar font-display: swap siempre

4. **Queries**
   - Limitar posts_per_page en queries custom
   - Usar transients para queries pesadas
   - No hacer queries dentro de loops
   - Usar índices apropiados en custom tables

### Para Hosting

1. **Servidor**
   - PHP 8.2+ con OPcache habilitado
   - MySQL 8.0+ o MariaDB 10.6+
   - Redis o Memcached para object cache
   - HTTP/2 o HTTP/3 habilitado
   - CDN configurado (Cloudflare, etc.)

2. **WordPress**
   - WordPress 6.4+ (latest)
   - Mantener plugins al mínimo
   - Usar plugins de calidad solo
   - Actualizar regularmente

3. **Base de Datos**
   - Optimizar tablas regularmente
   - Limitar revisiones de posts
   - Limpiar post meta innecesario
   - Usar persistent connections

---

## Troubleshooting

### Problema: LCP Alto (> 2.5s)

**Causas comunes**:
- Imagen destacada muy pesada
- CSS render-blocking
- Servidor lento
- Sin preload de recursos críticos

**Soluciones**:
1. Verificar tamaño de imagen destacada (< 200KB)
2. Activar Critical CSS (Customizer > Performance)
3. Verificar que preload de recursos funciona
4. Optimizar servidor/hosting
5. Usar CDN para imágenes

### Problema: FID/INP Alto (> 100ms)

**Causas comunes**:
- JavaScript bloqueante
- Scripts sin defer
- Plugins pesados
- Event listeners excesivos

**Soluciones**:
1. Verificar que jQuery está desactivado
2. Verificar que todos los scripts tienen defer
3. Desactivar plugins innecesarios
4. Revisar custom JavaScript
5. Usar Chrome DevTools Performance tab

### Problema: CLS Alto (> 0.1)

**Causas comunes**:
- Imágenes sin dimensiones
- Ads sin espacios reservados
- Fuentes sin font-display: swap
- Contenido dinámico above-the-fold

**Soluciones**:
1. Verificar que todas las imágenes tienen width/height
2. Activar AdSense delay si usa ads
3. Verificar fuentes locales con swap
4. No inyectar contenido dinámico above-the-fold
5. Usar Chrome DevTools Layout Shift Regions

### Problema: Muchos HTTP Requests

**Causas comunes**:
- Demasiados plugins
- Archivos CSS/JS no combinados
- Imágenes no optimizadas
- External scripts

**Soluciones**:
1. Desactivar plugins innecesarios
2. Combinar archivos cuando sea posible
3. Usar sprites CSS o inline SVG
4. Minimizar external scripts
5. Revisar Network tab en DevTools

### Problema: Tamaño de Página Grande

**Causas comunes**:
- Imágenes no optimizadas
- CSS/JS no minificado
- Demasiado HTML inline
- Recursos no comprimidos

**Soluciones**:
1. Optimizar todas las imágenes
2. Verificar minificación de CSS/JS
3. Reducir HTML inline
4. Habilitar Gzip/Brotli en servidor
5. Usar Coverage tab en DevTools

---

## Recursos Adicionales

### Documentación

- [Web.dev - Core Web Vitals](https://web.dev/vitals/)
- [Google PageSpeed Insights](https://pagespeed.web.dev/)
- [WordPress Performance Team](https://make.wordpress.org/performance/)

### Herramientas

- [PageSpeed Insights](https://pagespeed.web.dev/)
- [WebPageTest](https://www.webpagetest.org/)
- [GTmetrix](https://gtmetrix.com/)
- [Lighthouse](https://developers.google.com/web/tools/lighthouse)

### Optimización de Imágenes

- [TinyPNG](https://tinypng.com/)
- [Squoosh](https://squoosh.app/)
- [ImageOptim](https://imageoptim.com/)
- [AVIF Converter](https://avif.io/)

---

## Changelog

### Versión 1.0.0 - 2025-11-04

- ✅ Optimización completa de Core Web Vitals
- ✅ Resource hints (DNS prefetch, preconnect)
- ✅ Preload de recursos críticos
- ✅ Optimización de imágenes (WebP/AVIF)
- ✅ Lazy loading nativo
- ✅ Critical CSS (opcional)
- ✅ Scripts con defer strategy
- ✅ AdSense delay loading
- ✅ Eliminación de bloat de WordPress
- ✅ Optimización de queries
- ✅ GZIP compression
- ✅ Heartbeat API optimizado

---

## Soporte

Para reportar problemas o sugerir mejoras:
- GitHub Issues: [repositorio del tema]
- Documentación: `wp-content/themes/apus-theme/docs/`

---

**Última actualización**: 2025-11-04
**Versión del tema**: 1.0.0
**Autor**: Apus Theme Development Team