Mastering Drupal 8’s Libraries API
Along with Drupal 8 came the Libraries API and a new standard of adding CSS and JS assets and managing libraries. In true Drupal 8 fashion, the new system uses YAML files to grant developers flexibility and control over their CSS and JS assets. This gives you the ability to overwrite core libraries, add libraries directly to templates, specify dependencies and more.
If you haven’t yet experienced the glory that is the yml file, you’ll want to get familiar. Read this great introduction to YAML then come back to this post.
First step is to create your libraries.yml file at your-theme-name.libraries.yml or your-module-name.libraries.yml.
Here’s an example of how you define a Drupal 8 library.
A few things to note:
- The path to CSS and JS files are relative to the theme or module directory that contains the libraries.yml file. We’ll cover that in more depth shortly.
- The dependencies, in this case jQuery, are any other library your library depends on. They will automatically be attached wherever you attach your library and will load before yours.
- Multiple libraries can be defined in one libraries.yml file, so each library in the file must have a unique name. However the libraries will be namespaced as mytheme/mylibrary or mymodule/mylibrary so a libraries.yml file in your theme and libraries.yml file in your module can contain libraries with the same name.
Now that you know the library basics, it’s time to up the ante.
The simplest way to attach libraries globally is through the your-theme-name.info.yml file. Instead of adding stylesheets and scripts ala Drupal 7, you now attach libraries like so:
Global is great and all, but perhaps the coolest libraries upgrade in Drupal 8 is the ability to attach libraries via twig templates. For example, if you have a search form block, you can define the css and js for the block, add it to a library, and add that library to the search form block twig template. Those assets specific to the search form block will only be included when the block is rendered.
And yes, you can also attach libraries with our ol’ pal php.
Extending and Overriding Libraries
Another boon is the ability to extend and override libraries. These extensions and overrides take place in the your-theme-name.info.yml file.
As you might expect, libraries-extend respects the conditions of the library is being extended. Maybe you have a forum module that comes with css and js out-of-the-box. If you want to tweak the styling, you can extend the forum modules library, and add your own css file.
For overrides, you can remove or override a specific file or an entire library.
Before we wrap up, I'll send you on your way with a couple final considerations and gotcha's that you need to be aware of.
- The Libraries API Module is still relevant in Drupal 8, and should be used to handle external libraries that don't ship with drupal or a module or theme. It also allows libraries to be used by multiple modules or sites.
- If a file is already linked to within a library it won't get added a second time.
- Module CSS files are grouped before theme CSS files, so a module's css file will always be loaded before a theme's css file.
- Refer to the Drupal 8 Theming Guide for more info.
Thanks for reading. Now go forth and use your asset placing powers for good, not evil.