>>> [!note] Migrated issue <!-- Drupal.org comment --> <!-- Migrated from issue #2605130. --> Reported by: [samuel.mortenson](https://www.drupal.org/user/2582268) >>> <h3>The Backstory</h3> <p>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.</p> <p>The stories that need to be worked out in the documentation are:</p> <ol> <li>As a module author, I need to know what best practices to use when including external libraries.</li> <li>As a module author, I need to deal with duplicate versions of libraries and conflicts with other modules.</li> <li>As a module author, I need to verify library versions and warn users when libraries are out of date.</li> </ol> <h3><big>Your behaviors</big>&mdash;Adding JS/CSS in a module or theme </h3> <ul> <li>Prior to Drupal 8, we would have used <code>drupal_add_js()</code> and <code>drupal_add_css()</code>. Now, Drupal 8 uses a <code>[my_module].libraries.yml</code> file as a suitcase of assets.</li> <li><a href="https://www.drupal.org/theme-guide/8/assets">Adding stylesheets (CSS) and JavaScript (JS) to a Drupal 8 theme</a></li> <li><a href="https://www.drupal.org/developing/api/8/assets">Adding stylesheets (CSS) and JavaScript (JS) to a Drupal 8 module</a></li> <li><a href="https://api.drupal.org/api/drupal/core%21lib%21Drupal%21Core%21Render%21theme.api.php/function/hook_library_info_alter/8">hook_library_info_alter()</a> (a Drupal core hook) to alter existing *.libraries.yml configurations, should this be necessary to your situation.</li> <li>also see: <a target="_blank" href="https://www.lullabot.com/articles/understanding-javascript-behaviors-in-drupal">Understanding JavaScript behaviors in Drupal | lullabot</a></li> </ul> <h3>Best practices for handling External Libraries using Libraries API^{<a href="https://www.drupal.org#checked-into-git">[3rd]</a>}</h3> <p>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 &mdash; and it is easier to maintain through the lifespan of a site.</p> <ol> <li> <ul> <li>With the <a href="https://www.drupal.org/project/libraries">Libraries module (3.x) for Drupal 8</a>. 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^{<a href="https://www.drupal.org#drupal-themes">[T]</a>}.</li> <li>Use <a href="https://www.drupal.org/node/2170763">hook_libraries_info()</a> to define a new library, use <code>DRUPAL_ROOT/libraries</code> as the general folder to uncompress those packages. Use a subfolder name reflecting that JS framework/plugin (e.g., <code>/libraries/jquery.easing</code>).<br> <blockquote><p>DRUPAL_ROOT is the <a href="http://php.net/manual/en/language.constants.php">PHP Constant</a> name for your web root folder where the other files (like index.php) would be found.</p></blockquote> </li> <li>For multisite projects where you many want to limit to a unique site use <code>DRUPAL_ROOT/sites/[domain]/libraries</code>.</li> </ul> </li> <li>Add <code>[my_module].install</code> file in your module. Use <a href="https://api.drupal.org/api/drupal/core%21lib%21Drupal%21Core%21Extension%21module.api.php/function/hook_requirements/8">hook_requirements($phase)</a> with a loop for <code>if ($phase=='install'){}</code> to check for proper installation of Library.</li> <li>Would be best to give as direct a link to the library. (ie if from github give path to the <strong>tagged version</strong> 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!</li> </ol> <h3>Some Aside Notes</h3> <ull> <li>On Tools of the trade: <ul> <li><del>Have users run a post-install script like "bower install" from your module directory, and include your libraries relative to your module directory. (ex: bower_components/my_library/my_library.js) IE: <a href="https://www.drupal.org/project/file_browser">File Entity Browser</a>.</del> </li> <li>Let's not focus on how a developer/site builder downloaded to their file system, as there is a variety of tools to do so and will change in time. (ie: no one uses MAKE files anymore)</li> </ul> </li> <li>Linking from 3rd party Servers: <del>Use a CDN like cdnjs.com to ensure the correct version is being used and reduce install complexity.</del> <ul> <li>Not recommending module developers linking CDN's in their *.libraries.yml file. This is a poor development practice, you can't guarantee your module/theme's functionality this way.</li> <li>Problems with 3rd services (CDN's or general linking to other live Servers) with 404 &amp; maintenance realities or just slow load times..</li> <li>Some issues on the effects on js/css caching can occur with CDN use.</li> </ul> </li> <h3>Why not to include 3rd files in a Drupal Repo<sup id="checked-into-git">[3rd]</sup></h3> <p>RE: Regarding Software Licenses. Drupal.org's policies and other legal requirements</p> <ul> <li><a href="https://www.drupal.org/node/2307387">Asset libraries should declare their license; implement JavaScript License Web Labels</a></li> <li><a href="https://www.drupal.org/node/422996">3rd party libraries and content on Drupal.org</a></li> </ul> <p>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.</p> <h3>Related Issues on Drupal core &mdash; Themes<sup id="drupal-themes">[T]</sup>:</h3> <ol> <li> <a href="https://www.drupal.org/node/2652542">Add (back) hook_install for themes</a> </li> <li> <a href="https://www.drupal.org/node/474684">Allow themes to declare dependencies on modules</a></li> </ol> </ull> > Related issue: [Issue #667058](https://www.drupal.org/node/667058) > Related issue: [Issue #1167496](https://www.drupal.org/node/1167496) > Related issue: [Issue #2231385](https://www.drupal.org/node/2231385) > Related issue: [Issue #474684](https://www.drupal.org/node/474684) > Related issue: [Issue #2652542](https://www.drupal.org/node/2652542) > Related issue: [Issue #1398772](https://www.drupal.org/node/1398772) > Related issue: [Issue #2002304](https://www.drupal.org/node/2002304) > Related issue: [Issue #2873160](https://www.drupal.org/node/2873160)