The history of libraries, part 1
During the early development of Drupal 8, assets such as javascript and stylesheets had their own, different way of getting imported into themes. Importing a custom javascript file was done using the scripts
property inside the .info.yml
-file of the theme. To import stylesheets, the stylesheets
property was used. This was more or less the way it was done in Drupal 7. Here is an example from a Drupal 7 theme.info
file.
...
# Adding stylesheets
stylesheets[all][] = css/styles.css
stylesheets[print][] = css/print.css
# Adding javascript files
scripts[] = js/script.js
...
An alternative path was chosen. Javascript maintainer _nod created an issue on using AMD for JS architecture. The patch for the issue became so big that a separate issue was created. This issue handled the splitting up of the dependencies. This patch, Explicitly declare all JS dependencies, don't use drupal_add_js, where all javascript files are declared as libraries and added the relevant dependencies to the scripts, got committed about two weeks after the creation. The original issue [AMD architecture] however was posponed to a later Drupal release (Drupal 9.x).
{}.libraries.yml
During the early stages of Drupal 8, this was done using hook_library_info
. Since this was one of the last remaining hooks in Drupal 8, it got replaced by a *.libraries.yml
file). This means modules, themes and profiles can define their own *.libraries.yml
file. The file should be in the root directory of the theme (or module).
# example.libraries.yml
base:
version: 1.x
js:
js/scripts.js: {}
css:
component:
css/components/component.css: {}
dependencies:
- core/drupal
- core/jquery
Inside the .info.yml
file from a module or theme, the library can be included using the libraries
property.
# example.info.yml
libraries:
- example/base
The example theme now has a global dependency on the base
library (from the example theme/module); example/base
. Therefor it's included on every page (where this theme is loaded). The base
library itself contains a single javascript file (scripts.js
), a css file (categoried as a component) and has dependencies on the drupal
and jquery
library from core (read more on this in the Javascript chapter).
The history of libraries, part 2
Due to this change, the scripts
tag from the .info.yml
, was removed and replaced with the libraries
property. This means scripts can only be included using the libraries
property and a libraries.yml
file. Stylesheets however (in themes) could still included using the old stylesheets
property:
_nod:
remove scripts[] from info files and replace it with library[] …
stylesheets[] can be kept as is, it's totally fair to add a single css file without dependencies. It's highly unlikely for scripts, they will need to depend on jquery, drupal.js 99% of the time.
It became clear this new way of adding assets had some major advantages. Wim Leers created a new issue stating Themes should use libraries, not individual stylesheets. Due to the advantages pointed out in this issue, the stylesheets
property from the .info
file got removed. Thanks to this, there is now a unified way for adding assets libraries.