Managing Library Dependenciesfor Drupal 8 , 9 , 10 , and 11

A library that quietly assumes jQuery is already on the page is like a recipe that assumes you already have a preheated oven — it works fine until someone tries it without that assumption in place, and then it fails in a confusing way. Drupal's dependencies key is how a library states its assumptions out loud, so Drupal can guarantee they're satisfied before your code ever runs.

What you'll learn in this lesson

• How to declare that one library depends on another
• What actually breaks if you skip this and just hope for the best
• The related weight option for ordering multiple JS files within the same library

Declaring a dependency, for real

Here's the colors library from the Examples project's js_example module, which genuinely needs jQuery and Drupal's own settings bridge to function:

colors:
  version: 4.0.0
  css:
    component:
      css/weights.css: {}
  js:
    # We use weight as example attribute. Its usage is discouraged, though;
    # dependencies should instead be used.
    # For JavaScript files, its value can be only negative, contrarily to CSS
    # files for which its value can be between -50 and +50.
    js/colors.rgb.js: { weight: -2 }
    js/colors.base.js: { weight: -8 }
    js/colors.cmy.js: { weight: -4 }
  dependencies:
    - core/jquery
    - core/drupalSettings

dependencies — a list, in module/library form

dependencies:
  - core/jquery
  - core/drupalSettings

Each entry names another library, in the same module_name/library_name form you met in the last lesson — here, two libraries that ship with Drupal core itself. Listing a dependency guarantees Drupal loads it first, in the right order, every time colors is attached anywhere on the site. Skip this, and your JavaScript might work by pure luck on one page (because something else happened to load jQuery first) and throw a "jQuery is not defined" error on another — a genuinely painful class of bug to track down, because it looks like it "sometimes works."

weight — ordering files inside one library

js/colors.rgb.js: { weight: -2 }
js/colors.base.js: { weight: -8 }
js/colors.cmy.js: { weight: -4 }

This is a different problem from dependencies: all three files belong to the same library and will always load together, but colors.base.js needs to run before the others (weight -8 is more negative, so it sorts first). Note the comment in the real source above: the Examples module's own authors flag weight as discouraged for this — dependencies is the preferred, more explicit tool whenever one file's code genuinely depends on another's having already run. Reach for weight only for looser "prefer this order" cases.

Quick check: your library's JS calls Drupal.behaviors and reads a value from drupalSettings. Which core library (or libraries) must you list under dependencies? (Answer: core/drupal for Drupal.behaviors, and core/drupalSettings for reading drupalSettings — two separate core libraries, both needed if your code uses both.)

Key takeaways

• dependencies is a list of other libraries (in module/library form) that must load before this one — Drupal enforces the order, not you.
• Missing a real dependency doesn't always fail immediately; it can "work by luck" on pages where the dependency happens to load first for unrelated reasons, then break elsewhere.
• weight orders files within one library; dependencies orders entire libraries relative to each other — they solve different problems.
• Circular dependencies between libraries are a real error, not an edge case Drupal silently resolves — treat it as a sign to refactor shared logic into its own library.

Coming up next

You've now defined a library and told it what it needs. The only piece left is actually getting it onto a page — next, you'll attach a library to a render array or a route so it loads exactly when and where it's needed, no more, no less.