Optimizing a Drupal site for performance usually involves enabling CSS and JavaScript aggregation. This process combines multiple files into single assets, reducing HTTP requests and improving load times for your users. However, when you are in the heat of development, aggregation is your worst enemy. It masks your changes, makes debugging styles nearly impossible, and forces you to clear caches constantly just to see a single line of CSS update.

If you have transitioned from Drupal 7 to modern versions like Drupal 8, 9, or 10, you likely noticed that the old ways of managing these settings have changed. The familiar drush vset commands and the variable database table are gone, replaced by the more robust Configuration Management system. In this guide, you will learn the most efficient ways to disable aggregation using Drush, PHP configuration overrides, and the Drupal UI.

Why Disable Aggregation During Development?

Before diving into the technical steps, it is important to understand why you would want to disable these features. In a production environment, Drupal's aggregation system turns dozens of CSS and JS files into just a few. In a development environment, however, you need the raw, individual files.

When aggregation is active, Drupal generates a hash for the combined file. If you change a single file, Drupal may not immediately realize it needs to regenerate that aggregate unless the cache is flushed. Furthermore, tools like Chrome DevTools or Firefox Developer Tools cannot accurately point you to the specific line number in your source Sass or CSS files when everything is bundled into one massive, minified blob. Disabling aggregation ensures that what you see in your editor is exactly what the browser loads.

Method 1: Disabling Aggregation via Drush

For most developers, the command line is the fastest way to toggle system settings. Since Drupal 8, settings are stored as configuration objects rather than simple variables. To disable CSS and JS aggregation, you need to interact with the system.performance configuration.

You can use the following Drush commands to instantly update your site's configuration:

# Disable CSS aggregation
drush -y config-set system.performance css.preprocess 0

# Disable JS aggregation
drush -y config-set system.performance js.preprocess 0

Breaking Down the Command

  • config-set: This tells Drush you want to modify a specific configuration value.
  • system.performance: This is the name of the configuration object that holds performance-related settings.
  • css.preprocess / js.preprocess: These are the specific keys within the object. Setting them to 0 (false) disables the feature.
  • -y: This flag automatically accepts the confirmation prompt, saving you a keystroke.

After running these commands, it is always a good practice to rebuild the cache to ensure the changes take effect immediately:

drush cr

Method 2: Using settings.local.php Overrides

While the Drush method updates the database configuration, the best practice for local development is to use a configuration override in your settings.local.php file. This approach is superior because it ensures that aggregation remains disabled on your local machine even if you import a production database where aggregation is turned on.

Step 1: Enable settings.local.php

First, ensure your main sites/default/settings.php file is configured to look for a local settings file. Look for the following code block at the end of the file and make sure it is uncommented:

if (file_exists($app_root . '/' . $site_path . '/settings.local.php')) {
  include $app_root . '/' . $site_path . '/settings.local.php';
}

Step 2: Add the Overrides

Next, open (or create) sites/default/settings.local.php. Add the following lines to override the performance settings:

/**
 * Disable CSS and JS aggregation.
 */
$config['system.performance']['css']['preprocess'] = FALSE;
$config['system.performance']['js']['preprocess'] = FALSE;

Why This Method is Better for Teams

Using $config overrides in a local settings file prevents accidental deployments of unaggregated assets. Since settings.local.php is typically excluded from version control (via .gitignore), these settings stay local to your environment. Your production site stays fast with aggregation enabled, while your local environment stays flexible for development.

Method 3: The Drupal Admin Interface

If you prefer using the graphical user interface, Drupal provides a simple toggle within the administration menu. This is useful if you do not have terminal access or are working on a quick fix.

  1. Navigate to Configuration > Development > Performance in your admin toolbar.
  2. Locate the Bandwidth Optimization section.
  3. Uncheck "Aggregate CSS files".
  4. Uncheck "Aggregate JavaScript files".
  5. Click Save configuration.

Note that if you have used the settings.local.php method described above, these checkboxes may appear checked or unchecked but will be overridden by the code. Drupal usually displays a message indicating that there are configuration overrides in effect.

Understanding the Change from Drupal 7

If you are searching for the variable table in your database and coming up empty, don't panic. Drupal moved away from the variable table in favor of the CMI (Configuration Management Interface).

In Drupal 7, you would have used:

# This ONLY works in Drupal 7
drush vset preprocess_js 0
drush vset preprocess_css 0

In modern Drupal, variables are no longer global blobs in the database. They are structured YAML-based configuration objects. This allows for better deployment workflows, as you can export your configuration to files and version-control them. However, it does mean that the old Drush vset and vget commands are deprecated in favor of config-set, config-get, and config-export.

Frequently Asked Questions

Why are my changes still not showing after disabling aggregation?

Even after disabling aggregation, Drupal or your server might be caching the old HTML output. Always run drush cr (cache rebuild) after changing performance settings. Additionally, check if you have an external cache like Varnish or a CDN like Cloudflare that might be serving cached versions of your assets.

Does disabling aggregation affect my site's security?

No, disabling CSS/JS aggregation does not impact the security of your Drupal site. It only affects how files are delivered to the browser. However, it will significantly increase the number of HTTP requests, which can lead to slower page load times, so it should never be left disabled on a live production site.

Can I disable aggregation for only one specific theme?

Aggregation is a global system setting in Drupal. While you can technically use hooks like hook_css_alter() or hook_js_alter() to manipulate how specific libraries are handled, it is much more efficient to toggle the global setting during development rather than writing theme-specific logic to bypass the core system.

Wrapping Up

Managing CSS and JS aggregation is a fundamental skill for any Drupal developer. Whether you prefer the speed of Drush or the persistence of settings.local.php overrides, knowing how to toggle these settings ensures you can debug your frontend code without the frustration of stale, aggregated files.

For local development, the settings.local.php method is the gold standard. It keeps your development environment tailored to your needs without interfering with the production configuration. If you need a quick change on a staging site, the Drush config-set commands are your best friend. By mastering these two approaches, you'll save time and reduce the headaches associated with Drupal's performance layer.