Best practices for handling external libraries in Drupal 8/9/10 and 11

The Backstory

While talking to @webchick at BADCamp, I (samuel.mortenson) brought up that even with Drupal 8's new Library handling logic, there is still no answer to/best practice for one of the most common Library problems: "Where do I put my external Javascript/CSS files?". I can think of a few approaches to this, but we should standardize as a community on one or more best practices so that contributed module authors know the best methods for handling external libraries.

The stories that need to be worked out in the documentation are:

1. As a module author, I need to know what best practices to use when including external libraries.
2. As a module author, I need to deal with duplicate versions of libraries and conflicts with other modules.
3. As a module author, I need to verify library versions and warn users when libraries are out of date.

Your behaviors—Adding JS/CSS in a module or theme

• Prior to Drupal 8, we would have used drupal_add_js() and drupal_add_css(). Now, Drupal 8 uses a [my_module].libraries.yml file as a suitcase of assets.
• Adding stylesheets (CSS) and JavaScript (JS) to a Drupal 8 theme →
• Adding stylesheets (CSS) and JavaScript (JS) to a Drupal 8 module →
• hook_library_info_alter() (a Drupal core hook) to alter existing *.libraries.yml configurations, should this be necessary to your situation.
• also see: Understanding JavaScript behaviors in Drupal | lullabot

Best practices for handling External Libraries using Libraries API

Ultimately, the goal of the Libraries API is to make the assets added by it shareable between modules and themes, consistently done between projects and developers/sitebuilders — and it is easier to maintain through the lifespan of a site.

1. • With the Libraries module (3.x) for Drupal 8 → . Having contrib modules for each external common JS framework (and then, plugins of that framework), and mark those as a dependency of your module/theme.
   • Use hook_libraries_info() → to define a new library, use DRUPAL_ROOT/libraries as the general folder to uncompress those packages. Use a subfolder name reflecting that JS framework/plugin (e.g., /libraries/jquery.easing).
     

     DRUPAL_ROOT is the PHP Constant name for your web root folder where the other files (like index.php) would be found.

   • For multisite projects where you many want to limit to a unique site use DRUPAL_ROOT/sites/[domain]/libraries.
2. Add [my_module].install file in your module. Use hook_requirements($phase) with a loop for if ($phase=='install'){} to check for proper installation of Library.
3. Would be best to give as direct a link to the library. (ie if from github give path to the tagged version you know will work with the drupal behaviour that will be triggering it. do not just link to MASTER/HEAD, unless you want a string of issues against your module because the plugin has changed!

Some Aside Notes

Why not to include 3rd files in a Drupal Repo

RE: Regarding Software Licenses. Drupal.org's policies and other legal requirements

• Asset libraries should declare their license; implement JavaScript License Web Labels →
• 3rd party libraries and content on Drupal.org →

Simply, if we use the Libraries API (and only include the JS behaviour and custom CSS in our modules/themes) we will be in compliance with such policies and laws. Making such 3rd code sharable and maintainable in our custom work for clients. As well as then being ready to contribute work back to the Drupal Community.

Related Issues on Drupal core — Themes:

1. Add (back) hook_install for themes →
2. Allow themes to declare dependencies on modules →