Enabling JS aggregation for faster page loadsfor Drupal 11 , 10 , 9 , and 8

JavaScript aggregation works on the same principle as CSS aggregation — bundle many small files into fewer, cached ones — but with one extra complication: unlike stylesheets, scripts often depend on running in a specific order (jQuery has to load before a plugin that uses it, for instance). Drupal's aggregator respects the dependency graph declared in each module's *.libraries.yml file, so combining files never silently breaks that ordering.

What you'll learn in this lesson

• How JS aggregation differs from CSS aggregation because of load-order dependencies
• How to enable it, and where the generated files live
• Why declaring library dependencies correctly matters even more once aggregation is on

Turning it on

Same screen as CSS aggregation: Configuration → Development → Performance (/admin/config/development/performance), the "Aggregate JavaScript files" checkbox. For production, set it in settings.php alongside its CSS counterpart:

$config['system.performance']['js']['preprocess'] = TRUE;

Why declared dependencies matter here

Every Drupal library is defined in a *.libraries.yml file with an explicit dependencies key:

my_module.my_script:
  js:
    js/my-script.js: {}
  dependencies:
    - core/jquery
    - core/drupal

When aggregation is off, the browser loads these as separate <script> tags in dependency order, and a missing dependency declaration might still "accidentally" work because jQuery happened to load first anyway. Turn aggregation on, and Drupal groups scripts into aggregate bundles strictly by that dependency graph — an incorrectly-declared or missing dependency is far more likely to actually break something visibly, which paradoxically makes aggregation a good way to catch sloppy library definitions during testing.

See it for yourself

Enable "Aggregate JavaScript files" at /admin/config/development/performance, save, then check any page's source — the many individual <script src="...core/misc/....js"> tags collapse into a much shorter list pointing at /sites/default/files/js/js_....js files.

Quick check: your custom library's JS silently stopped working the moment you turned on aggregation, even though it worked fine before. What's the single most likely cause? (A missing or incorrect dependencies entry in your *.libraries.yml — without aggregation, load order was accidentally correct by luck; aggregation exposed the real bug.)

Key takeaways

• JS aggregation bundles scripts the same way CSS aggregation bundles stylesheets, but strictly respects each library's declared dependencies order.
• Enable via /admin/config/development/performance or $config['system.performance']['js']['preprocess'] in settings.php.
• Aggregation can surface previously-hidden dependency-declaration bugs in your own libraries — treat a break here as a real bug to fix, not aggregation malfunctioning.
• Disable aggregation in local development for a sane debugging experience.

Coming up next

Aggregation reduces the number of files; minification reduces how big each one is. Next: Minifying CSS and JavaScript.