Naming conventions for D8 libraries

Given the fact, that in Drupal 8 every module and theme has to declare their CSS and JS files as libraries, we should think about and discuss naming conventions and best practices for these.

We will have a massive increase in library definitions in D8, as every single theme developer and many module developers are concerned. Before in D7, a theme just had their JS and CSS files listed in its info file, without any explicit library declaration, and therefore without naming the assets. Also most of the modules didn't have to declare anything. Most of time, the modules just include their assets on page load and/or attach it to a form element, etc. In fact, the only D7 modules that have to care about library definiton and naming, are the ones that integrate a third-party Javascript library in Drupal, like Colorbox or our Outdated Browser module.

This changes with D8. There will be a lot of simliar use-cases and repetitive tasks. Every theme of course has its global CSS and JS file(s). Also a module, that integrates a 3rd part JS library, does have at least two libraries to define: the library itself and a small custom script that does the initialization and attaches a Drupal behavior. These are some typical examples, you'll often need yourself to declare. And for these cases, it would be important, if we would have some naming conventions.

Themes

Let's start with themes. This is rather easy, as there are already some standard themes shipped with D8, e.g. Bartik. The recommended way here seems to combine your CSS files into a library named "global-styling".

The only open question is, what if you also have some scripts in your theme? Should we imply that the script file(s) should be declared separately as a "global-scripts" library?

But what, if they belong together inseparably? Wouldn't it be better to define a single library containing both CSS and JS assets? Then something like "global-styling-and-scripts" or "global-styles-and-scripts" sound appropriate.

(While reviewing my post, I've just found a blog post by Andrei from Appnovation, recommending "global-scripts" for JS files only and "global-styles-and-scripts" for combined libraries.)

Modules

I'm now talking about the typical use case of modules doing third party JS library integration. Typically we have the JS library itself one the one hand, and the module's initialization script on the other hand. In D7, it was easy: you don't declare your initialization script, but just load it under certain circumstances. And the JS library would be declared with the help of Libraries API, naturally based on the name of the JS library itself. So for example the Colorbox module defines the JS library under the name "colorbox", Outdated Browser module "outdatedbrowser", etc.

In D8, you have the different situation, that the libraries are namespaced with your module's name, e.g. there's "core/jquery" or "core/modernizr" defined in Drupal core. That means, that whatever name we give our library, it's name only has to be unique within our module.

That leads us to our first question: as typically the module's name matches the JS library's name, should we still name the library based on its original name, so that we end up with "colorbox/colorbox", "outdatedbrowser/outdatedbrowser", etc.? Or should we use something like "library" instead, so that the full qualified name will be "outdatedbrowser/library"? Then of course, we have to distinct between modules having equal names as the integrated library and the ones whose names differ (image something like a "mycoolslideshow" module, that integrates different libraries like "ultraslider" and "megaslider").

Maybe, a combined third option would be even better, taking "LIBRARY_NAME.library", like "outdatedbrowser/outdatedbrowser.library"?

And what about the initialization script - the file, that mostly only a few lines of code, that actually initialize and start the library? Here, a few things came up into my mind, like "init", "setup", "drupal". Additionally we have to think about the same question like above, whether or not to include the library's name. Based on examples above, we now have multiple combinations, like: "outdatedbrowser/init", "outdatedbrowser/drupal", "outdatedbrowser/outdatedbrowser.init", "outdatedbrowser/outdatedbrowser.drupal", "outdatedbrowser/drupal.outdatedbrowser", and so on.

Examples in the wild

I've done a small research on the currently existing D8 modules. Unfortunately there aren't many existing at the moment and a couple of them doesn't seem very mature or even working.

It's always good to have a look at Drupal core first, but I couldn't find exactly the use case described above. CKEditor for example is split: the library itself is defined within the core libraries as "core/ckeditor", whereas the actual usage of the library is done within the ckeditor modulem, defined as "ckeditor/drupal.ckeditor", thus following the pattern "drupal.LIBRARYNAME" for the initialization script.

In our Outdated Browser module, we've decided to use "outdatedbrowser/library" and "outdatedbrowser/drupal" for the moment. But I'm thinking about changing it to "outdatedbrowser/outdatedbrowser" and "outdatedbrowser/drupal.outdatedbrowser".

Colorbox does it differently. At the moment, the Colorbox library isn't defined within libraries.yml file at all, but with Libraries API hook. The initialization script of course is part of the yml file, but named "colorbox/colorbox", which is very misleading imho.

Another example I've found is using "core" for the library and "drupal" for the behaviors (sidecomments/core and sidecomments/drupal), which is slightly different to another example: mathjax/source and mathjax/setup.

Sticky Sharre Bar's decision is again different to all the others: sticky_sharrre_bar/sharre for the Sharre JS library, and splitting its own assets in sticky_sharrre_bar/sticky_sharrre_bar_css and sticky_sharrre_bar/sticky_sharrre_bar_js.

I've also seen modules defining one single library containing both the external library and its own assets, which is imho not the best solution, and that's not what was intended by the Drupal library API.