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
2. Métricas Core Web Vitals
3. Optimizaciones Implementadas
4. Configuración del Servidor
5. Testing y Medición
6. Mejores Prácticas
7. 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

// 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

// 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:

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:

- 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:

// 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)

# 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

# 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
• Google PageSpeed Insights
• WordPress Performance Team

Herramientas

• PageSpeed Insights
• WebPageTest
• GTmetrix
• Lighthouse

Optimización de Imágenes

• TinyPNG
• Squoosh
• ImageOptim
• AVIF Converter

---

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