Advanced CSS/JS Aggregation

Aggregates multiple CSS/JS files in a way that prevents 404 errors and provides enhanced optimization through gzip/brotli compression, minification, bundling, and CDN integration.

advagg

29,433 sites

189

drupal.org

performance optimization aggregation css JavaScript compression gzip brotli minification cdn caching http2

Drupal 8 Drupal 9

Install

Drupal 9 v5.0.0

composer require 'drupal/advagg:^5.0'

Drupal 8 v8.x-4.1

composer require 'drupal/advagg:8.x-4.1'

Overview

Advanced CSS/JS Aggregation (AdvAgg) is a powerful performance optimization module for Drupal that enhances the core CSS and JavaScript aggregation functionality. Unlike Drupal 7, AdvAgg for Drupal 8/9+ focuses on incremental improvements to the already-improved core asset handling.

The module provides URL query string parameters to bypass aggregation (?advagg=0, ?advagg=-1, ?advagg=1), administrative cookies for development mode, gzip and brotli pre-compression of optimized files, and DNS prefetch for external assets. With its various submodules, AdvAgg can significantly improve front-end performance through asset minification, bundling control, CDN integration, and various loading optimizations like defer and async attributes.

AdvAgg is particularly useful for HTTP/2 environments where multiple smaller files may perform better than single large aggregates, and for sites requiring fine-grained control over CSS/JS delivery optimization.

Features

URL query string control to enable/disable aggregation per request (?advagg=0, ?advagg=-1, ?advagg=1)
Browser cookie to temporarily disable optimization for development and debugging
Gzip pre-compression of all optimized CSS and JS files for faster delivery
Brotli compression support (requires PHP brotli extension) with ~30% better compression than gzip
DNS prefetch for external CSS/JS resources to speed up DNS lookups
Combine CSS files using media queries for more efficient aggregation
Automatic fix for improperly set asset types (file vs external)
Configurable cron maintenance for stale file cleanup
Apache .htaccess generation with Cache-Control: immutable headers
Global counter to force regeneration of all aggregates
CSS minification via YUI Compressor or Core algorithm
JavaScript minification via JSMin+, JShrink, JSqueeze, or JSMin C extension
Customizable bundle count for HTTP/2 optimization
CDN integration for jQuery and jQuery UI from Google or Microsoft
Asset modification options including defer, async, and preprocess forcing
Old Internet Explorer compatibility (4095 selector limit handling)
CSS and JavaScript validation using CSSLint, JSHint, and W3C validator

Use Cases

Optimizing for HTTP/2 servers

For sites running on HTTP/2, use the Bundler submodule to create multiple smaller aggregates (e.g., 4-6 bundles) instead of single large files. HTTP/2's multiplexing allows parallel loading of multiple files without the overhead of multiple connections, often providing better performance than fully aggregated single files.

Maximizing PageSpeed scores

Enable CSS media query combining, use the Modifier submodule to move JS to footer with defer, enable preprocess on all assets, and enable JavaScript minification with JSMin or JSqueeze. This configuration reduces render-blocking resources and improves Core Web Vitals.

Development workflow with aggregation testing

Use the bypass cookie feature or ?advagg=0 URL parameter to temporarily disable aggregation during development. This allows testing individual CSS/JS files while other users continue to see optimized assets. The development cache level can also be used for immediate change detection.

CDN-hosted jQuery for improved caching

Enable the CDN submodule to serve jQuery and jQuery UI from Google or Microsoft CDNs. Visitors who have cached these libraries from other sites won't need to download them again, improving initial page load times.

Legacy IE support for enterprise environments

Enable the Old IE Compatibility submodule for sites that must support Internet Explorer 6-9. This prevents CSS aggregates from exceeding the 4095 selector limit that causes styles to break in these browsers.

External build tool integration

Use the External Minification submodule to integrate professional minification tools like Google Closure Compiler (for JavaScript) or the Java-based YUI Compressor. This provides access to more aggressive optimizations than built-in minifiers.

CSS/JS code quality validation

Use the Validator submodule during development or before deployment to check CSS files with CSSLint or W3C Validator, and JavaScript files with JSHint. This helps identify syntax errors that could cause aggregation failures or runtime issues.

Tips

Use the JavaScript bookmarklet provided in the README to quickly toggle AdvAgg on/off while browsing your site
For best minification performance, install the JSMin PHP extension (PECL) - it's ~500x faster than pure PHP minifiers
Enable brotli compression if your server supports it - provides ~30% better compression than gzip
Set stale_file_threshold to a longer period (1-2 months) on production sites to reduce cron processing
Use settings.php overrides for environment-specific configuration: $config['advagg.settings']['enabled'] = FALSE; for development
The Bundler is most effective when combined with Modifier's preprocess options to maximize aggregation opportunities
Check the Information page periodically to see which modules are altering assets - unexpected modules may cause conflicts

Technical Details

AdvAgg: Configuration /admin/config/development/performance/advagg

Main configuration page for Advanced CSS/JS Aggregation. Configure global settings, compression options, CSS/JS specific options, cron maintenance settings, and obscure options for advanced server configurations.

AdvAgg: Information /admin/config/development/performance/advagg/info

Debugging information page displaying hook theme info, core asset hooks implemented by modules, and a tool to get detailed information about optimized files. No configuration options available.

AdvAgg: Operations /admin/config/development/performance/advagg/operations

Collection of commands to control the cache and manage testing. Useful for troubleshooting aggregation issues. Includes bypass cookie toggle, cron maintenance tasks, and drastic measures for cache clearing.

AdvAgg: Bundler /admin/config/development/performance/advagg/bundler

Configure the number of CSS and JavaScript aggregates to be created per page. Beneficial for HTTP/2 servers where multiple smaller files may perform better than single large aggregates.

Advanced CSS/JS Aggregation: CDN Settings /admin/config/performance/advagg/cdn

Configure CDN integration to load jQuery and jQuery UI libraries from public CDNs (Google or Microsoft) instead of local copies.

AdvAgg: CSS Minification /admin/config/development/performance/advagg/css-minify

Configure CSS minification settings using built-in minifiers. YUI Compressor provides better minification than the Core algorithm.

AdvAgg: JS Minification /admin/config/development/performance/advagg/js-minify

Configure JavaScript minification using various minifiers. JSMin C extension provides fastest performance when available.

AdvAgg: External Minifiers /admin/config/development/performance/advagg/ext-minify

Configure external command-line minifiers for CSS and JavaScript. Allows using tools like Google Closure Compiler, YUI Compressor, or Microsoft Ajax Minifier via shell commands.

AdvAgg: Modifications /admin/config/development/performance/advagg/mod

Configure advanced asset modifications including preprocess forcing, console log removal, script ordering optimization, and deferred/async loading for CSS and JavaScript.

AdvAgg: Old IE Compatibility /admin/config/development/performance/advagg/old_ie_compatibility

Configure compatibility settings for old Internet Explorer versions (6-9) which have a 4095 CSS selector limit per file.

AdvAgg: CSS Validator using CSSLint /admin/config/development/performance/advagg/validate_css_lint

Validate CSS files using the CSSLint JavaScript library with Drupal core's .csslintrc settings.

AdvAgg: CSS Validator using w3.org /admin/config/development/performance/advagg/validate_css_w3

Validate CSS files using the W3C CSS Validator service. Note: Files are submitted to external W3C servers.

AdvAgg: JavaScript Validator using JSHint /admin/config/development/performance/advagg/validate_js_hint

Validate JavaScript files using the JSHint library with Drupal-specific predefined globals.

Bypass advanced aggregation

Allows users to use URL query strings (?advagg=0, ?advagg=-1, ?advagg=1) to bypass AdvAgg optimization on a per-request basis.

hook_module_implements_alter

Used to ensure AdvAgg's js_alter and css_alter hooks run last in the processing order, allowing it to apply final optimizations after other modules.

hook_js_alter

Processes the JavaScript asset array through the AdvAgg optimizer service when AdvAgg is enabled.

hook_css_alter

Processes the CSS asset array through the AdvAgg optimizer service when AdvAgg is enabled.

hook_cron

Performs maintenance tasks including htaccess file generation and cleanup of outdated optimized files based on configured thresholds.

hook_form_FORM_ID_alter (system_performance_settings)

Adds helpful information about AdvAgg bypass options to the core performance settings form.

drush advagg-cron

Run the AdvAgg cron hook to clean up stale aggregate files.

drush advagg-disable

Disable all AdvAgg functionality.

drush advagg-enable

Enable all AdvAgg functionality.

drush advagg-clear-all-files

Remove all generated/optimized CSS and JS files and clear the AdvAgg cache.

drush advagg-force-new-aggregates

Force creation of all new optimized files by incrementing the global counter. Clears all existing aggregates.

CSS or JavaScript breaks after enabling AdvAgg

First, try adding ?advagg=0 to the URL to confirm AdvAgg is the cause. Check the Information page to see which modules implement asset hooks that might conflict. Disable submodules one by one to identify the problematic one. The Modifier submodule's defer/async options are common causes of JS issues.

Aggregates not updating after file changes

Clear all caches using the Operations page 'Clear All Caches' button, or run 'drush advagg-caf'. If using a CDN, increment the global counter to force new filenames. Check the cache_level setting - Development mode provides immediate updates.

Blank page or WSOD after enabling minification

A JavaScript minification error may be corrupting output. Disable minification, clear caches, then re-enable with a different minifier. JSqueeze is the most reliable fallback. Check server error logs for specific minification errors.

Nginx not serving compressed files

AdvAgg's .htaccess files don't work on Nginx. Add gzip_static on; and/or brotli_static on; directives to your Nginx server configuration for the /sites/*/files/(css|js) location.

High memory usage during aggregation

Large JavaScript files with JSMin+ or JSqueeze can consume significant memory. Use the JSMin C extension for better performance, or use the External Minification submodule to offload processing to external tools.

404 errors for aggregate files

This is often caused by stale references. Clear all caches and increment the global counter. Ensure the public://css/optimized and public://js/optimized directories are writable. Check that htaccess files were generated correctly.

The External Minification submodule executes shell commands based on admin configuration - only grant 'administer site configuration' permission to trusted users
The W3C CSS Validator sends your CSS content to external servers - be aware of privacy implications for sites with sensitive styling
The bypass advanced aggregation permission allows users to see unminified/uncompressed assets which may expose code comments or structure
Always validate that AdvAgg-generated htaccess files have appropriate permissions and don't override important security directives