Advanced CSS/JS Aggregation
Agrega múltiples archivos CSS/JS de una manera que previene errores 404 y proporciona optimización mejorada mediante compresión gzip/brotli, minificación, agrupación e integración con CDN.
advagg
Install
composer require 'drupal/advagg:^5.0'
composer require 'drupal/advagg:8.x-4.1'
Overview
Advanced CSS/JS Aggregation (AdvAgg) es un potente módulo de optimización de rendimiento para Drupal que mejora la funcionalidad de agregación de CSS y JavaScript del núcleo. A diferencia de Drupal 7, AdvAgg para Drupal 8/9+ se centra en mejoras incrementales al manejo de assets del núcleo ya mejorado.
El módulo proporciona parámetros de cadena de consulta URL para omitir la agregación (?advagg=0, ?advagg=-1, ?advagg=1), cookies administrativas para modo de desarrollo, precompresión gzip y brotli de archivos optimizados, y prefetch de DNS para assets externos. Con sus diversos submódulos, AdvAgg puede mejorar significativamente el rendimiento del front-end mediante minificación de assets, control de agrupación, integración con CDN y varias optimizaciones de carga como atributos defer y async.
AdvAgg es particularmente útil para entornos HTTP/2 donde múltiples archivos más pequeños pueden rendir mejor que agregados grandes únicos, y para sitios que requieren control detallado sobre la optimización de entrega de CSS/JS.
Features
- Control mediante cadena de consulta URL para habilitar/deshabilitar agregación por solicitud (?advagg=0, ?advagg=-1, ?advagg=1)
- Cookie del navegador para deshabilitar temporalmente la optimización para desarrollo y depuración
- Precompresión gzip de todos los archivos CSS y JS optimizados para entrega más rápida
- Soporte de compresión Brotli (requiere extensión PHP brotli) con ~30% mejor compresión que gzip
- Prefetch de DNS para recursos CSS/JS externos para acelerar las búsquedas DNS
- Combinar archivos CSS usando media queries para agregación más eficiente
- Corrección automática de tipos de assets configurados incorrectamente (file vs external)
- Mantenimiento configurable por cron para limpieza de archivos obsoletos
- Generación de .htaccess de Apache con encabezados Cache-Control: immutable
- Contador global para forzar regeneración de todos los agregados
- Minificación de CSS mediante YUI Compressor o algoritmo del núcleo
- Minificación de JavaScript mediante JSMin+, JShrink, JSqueeze o extensión C de JSMin
- Cantidad de bundles configurable para optimización HTTP/2
- Integración con CDN para jQuery y jQuery UI desde Google o Microsoft
- Opciones de modificación de assets incluyendo defer, async y forzado de preprocess
- Compatibilidad con Internet Explorer antiguo (manejo del límite de 4095 selectores)
- Validación de CSS y JavaScript usando CSSLint, JSHint y validador W3C
Use Cases
Optimización para servidores HTTP/2
Para sitios que funcionan con HTTP/2, utiliza el submódulo Bundler para crear múltiples agregados más pequeños (por ejemplo, 4-6 paquetes) en lugar de archivos grandes únicos. La multiplexación de HTTP/2 permite la carga paralela de múltiples archivos sin la sobrecarga de múltiples conexiones, proporcionando a menudo un mejor rendimiento que los archivos únicos completamente agregados.
Maximización de puntuaciones PageSpeed
Habilita la combinación de media queries CSS, usa el submódulo Modifier para mover JS al footer con defer, habilita preprocess en todos los assets y habilita la minificación de JavaScript con JSMin o JSqueeze. Esta configuración reduce los recursos que bloquean el renderizado y mejora los Core Web Vitals.
Flujo de trabajo de desarrollo con pruebas de agregación
Usa la función de cookie de bypass o el parámetro URL ?advagg=0 para desactivar temporalmente la agregación durante el desarrollo. Esto permite probar archivos CSS/JS individuales mientras otros usuarios continúan viendo los assets optimizados. El nivel de caché de desarrollo también puede usarse para la detección inmediata de cambios.
jQuery alojado en CDN para mejor caché
Habilita el submódulo CDN para servir jQuery y jQuery UI desde los CDNs de Google o Microsoft. Los visitantes que hayan cacheado estas bibliotecas desde otros sitios no necesitarán descargarlas nuevamente, mejorando los tiempos de carga inicial de la página.
Soporte para IE antiguo en entornos empresariales
Habilita el submódulo Old IE Compatibility para sitios que deben soportar Internet Explorer 6-9. Esto evita que los agregados CSS excedan el límite de 4095 selectores que causa que los estilos fallen en estos navegadores.
Integración con herramientas de compilación externas
Usa el submódulo External Minification para integrar herramientas de minificación profesionales como Google Closure Compiler (para JavaScript) o YUI Compressor basado en Java. Esto proporciona acceso a optimizaciones más agresivas que los minificadores integrados.
Validación de calidad de código CSS/JS
Usa el submódulo Validator durante el desarrollo o antes del despliegue para verificar archivos CSS con CSSLint o W3C Validator, y archivos JavaScript con JSHint. Esto ayuda a identificar errores de sintaxis que podrían causar fallos de agregación o problemas en tiempo de ejecución.
Tips
- Usa el bookmarklet de JavaScript proporcionado en el README para activar/desactivar rápidamente AdvAgg mientras navegas tu sitio
- Para el mejor rendimiento de minificación, instala la extensión PHP JSMin (PECL) - es aproximadamente 500 veces más rápida que los minificadores en PHP puro
- Habilita la compresión brotli si tu servidor lo soporta - proporciona aproximadamente un 30% mejor compresión que gzip
- Configura stale_file_threshold a un período más largo (1-2 meses) en sitios de producción para reducir el procesamiento del cron
- Usa sobreescrituras en settings.php para configuración específica del entorno: $config['advagg.settings']['enabled'] = FALSE; para desarrollo
- El Bundler es más efectivo cuando se combina con las opciones de preprocess del Modifier para maximizar las oportunidades de agregación
- Revisa la página de Información periódicamente para ver qué módulos están alterando los assets - módulos inesperados pueden causar conflictos
Technical Details
Admin Pages 13
/admin/config/development/performance/advagg
Página principal de configuración para Advanced CSS/JS Aggregation. Configure ajustes globales, opciones de compresión, opciones específicas de CSS/JS, configuración de mantenimiento cron y opciones avanzadas para configuraciones de servidor especiales.
/admin/config/development/performance/advagg/info
Página de información de depuración que muestra información de hook theme, hooks de recursos del núcleo implementados por módulos y una herramienta para obtener información detallada sobre archivos optimizados. No hay opciones de configuración disponibles.
/admin/config/development/performance/advagg/operations
Colección de comandos para controlar el caché y gestionar pruebas. Útil para solucionar problemas de agregación. Incluye alternancia de cookie de bypass, tareas de mantenimiento cron y medidas drásticas para limpiar caché.
/admin/config/development/performance/advagg/bundler
Configurar el número de agregados CSS y JavaScript a crear por página. Beneficioso para servidores HTTP/2 donde múltiples archivos más pequeños pueden funcionar mejor que agregados grandes únicos.
/admin/config/performance/advagg/cdn
Configurar la integración con CDN para cargar las bibliotecas jQuery y jQuery UI desde CDNs públicos (Google o Microsoft) en lugar de copias locales.
/admin/config/development/performance/advagg/css-minify
Configurar ajustes de minificación de CSS usando minificadores integrados. YUI Compressor proporciona mejor minificación que el algoritmo del núcleo.
/admin/config/development/performance/advagg/js-minify
Configurar minificación de JavaScript usando varios minificadores. La extensión C de JSMin proporciona el rendimiento más rápido cuando está disponible.
/admin/config/development/performance/advagg/ext-minify
Configurar minificadores externos de línea de comandos para CSS y JavaScript. Permite usar herramientas como Google Closure Compiler, YUI Compressor o Microsoft Ajax Minifier mediante comandos de shell.
/admin/config/development/performance/advagg/mod
Configurar modificaciones avanzadas de recursos incluyendo forzado de preprocesamiento, eliminación de logs de consola, optimización del orden de scripts y carga diferida/asíncrona para CSS y JavaScript.
/admin/config/development/performance/advagg/old_ie_compatibility
Configurar ajustes de compatibilidad para versiones antiguas de Internet Explorer (6-9) que tienen un límite de 4095 selectores CSS por archivo.
/admin/config/development/performance/advagg/validate_css_lint
Validar archivos CSS usando la biblioteca JavaScript CSSLint con la configuración .csslintrc del núcleo de Drupal.
/admin/config/development/performance/advagg/validate_css_w3
Validar archivos CSS usando el servicio de Validación CSS del W3C. Nota: Los archivos se envían a servidores externos del W3C.
/admin/config/development/performance/advagg/validate_js_hint
Validar archivos JavaScript usando la biblioteca JSHint con globales predefinidos específicos de Drupal.
Permissions 1
Hooks 5
hook_module_implements_alter
Se utiliza para asegurar que los hooks js_alter y css_alter de AdvAgg se ejecuten en último lugar en el orden de procesamiento, permitiéndole aplicar optimizaciones finales después de otros módulos.
hook_js_alter
Procesa el array de recursos JavaScript a través del servicio optimizador de AdvAgg cuando AdvAgg está habilitado.
hook_css_alter
Procesa el array de recursos CSS a través del servicio optimizador de AdvAgg cuando AdvAgg está habilitado.
hook_cron
Realiza tareas de mantenimiento incluyendo la generación del archivo htaccess y la limpieza de archivos optimizados obsoletos según los umbrales configurados.
hook_form_FORM_ID_alter (system_performance_settings)
Añade información útil sobre las opciones de bypass de AdvAgg al formulario de configuración de rendimiento del núcleo.
Drush Commands 5
drush advagg-cron
Ejecuta el hook cron de AdvAgg para limpiar archivos agregados obsoletos.
drush advagg-disable
Desactiva toda la funcionalidad de AdvAgg.
drush advagg-enable
Activa toda la funcionalidad de AdvAgg.
drush advagg-clear-all-files
Elimina todos los archivos CSS y JS generados/optimizados y limpia la caché de AdvAgg.
drush advagg-force-new-aggregates
Fuerza la creación de todos los archivos optimizados nuevos incrementando el contador global. Limpia todos los agregados existentes.
Troubleshooting 6
Primero, intenta agregar ?advagg=0 a la URL para confirmar que AdvAgg es la causa. Revisa la página de Información para ver qué módulos implementan hooks de assets que podrían entrar en conflicto. Desactiva los submódulos uno por uno para identificar el problemático. Las opciones defer/async del submódulo Modifier son causas comunes de problemas con JS.
Limpia todas las cachés usando el botón 'Clear All Caches' en la página de Operaciones, o ejecuta 'drush advagg-caf'. Si usas un CDN, incrementa el contador global para forzar nuevos nombres de archivo. Revisa la configuración cache_level - el modo Development proporciona actualizaciones inmediatas.
Un error de minificación de JavaScript puede estar corrompiendo la salida. Desactiva la minificación, limpia las cachés, luego vuelve a habilitarla con un minificador diferente. JSqueeze es la alternativa más confiable. Revisa los logs de error del servidor para errores específicos de minificación.
Los archivos .htaccess de AdvAgg no funcionan en Nginx. Agrega las directivas gzip_static on; y/o brotli_static on; a la configuración de tu servidor Nginx para la ubicación /sites/*/files/(css|js).
Archivos JavaScript grandes con JSMin+ o JSqueeze pueden consumir memoria significativa. Usa la extensión C de JSMin para mejor rendimiento, o usa el submódulo External Minification para delegar el procesamiento a herramientas externas.
Esto es causado frecuentemente por referencias obsoletas. Limpia todas las cachés e incrementa el contador global. Asegúrate de que los directorios public://css/optimized y public://js/optimized tengan permisos de escritura. Verifica que los archivos htaccess se hayan generado correctamente.
Security Notes 4
- El submódulo External Minification ejecuta comandos de shell basados en la configuración del administrador - otorga el permiso 'administer site configuration' solo a usuarios de confianza
- El W3C CSS Validator envía el contenido de tu CSS a servidores externos - ten en cuenta las implicaciones de privacidad para sitios con estilos sensibles
- El permiso bypass advanced aggregation permite a los usuarios ver assets sin minificar/comprimir, lo que puede exponer comentarios de código o estructura
- Siempre valida que los archivos htaccess generados por AdvAgg tengan los permisos apropiados y no sobreescriban directivas de seguridad importantes