Drupal 7 lacked a streamlined mechanism for handling assets, which necessitated the development of more efficient solutions like the Asset Library introduced in Drupal 8 and the latest versions. Asset library solves the problem of loading JS and CSS files on every page. However, unless specified, Drupal does not load these assets as it can affect front-end performance.

Let’s learn more about asset libraries in Drupal 10 and how to work with them.

What is an Asset Library in Drupal

An Asset library in Drupal is nothing but a YAML data structured inside a THEMENAME.libraries.yml file and they contain only CSS and JS files. They are the bundles of CSS and JavaScript files that present inside a module or theme and perform together for style and functionality.

• The Asset Library in Drupal provides a centralized and organized repository for managing various types of digital assets.
• Assets Library boasts various features designed to enhance usability, scalability, and flexibility.
• Asset Library in Drupal is designed to support responsive web design, ensuring that assets are displayed consistently on various devices.
• Drupal places a strong emphasis on accessibility, and the Asset Library follows these standards to ensure a positive user experience for all.
• Drupal's Asset Library includes version control features, allowing users to manage and track changes to assets over time.
• Performance Optimization

Define an Asset Library

Let’s declare a new Asset library named custom-slider.

custom-slider:
  version: 1.0
  CSS:
    theme:
      css/custom-slider-theme.css: {}
  js:
    js/custom-slider.js: {}

Some of the attributes used include:

• Minified: If the file is already minified, set this to True to avoid minifying it again, else default value is False.
• Preprocess: Default value is True, set to False to exclude a file from Aggregation.
• Type (Javascript Only): 
         ◦ The default value is a file, if you leave it blank.
         ◦ For external files, use type as external like:

//cdn.com/js/example.js: {type: external}

Assets Loading Order

• By default, all JS files are loaded in the order in which files are listed.
• By default, JS files are loaded in the footer.
• Set header: true for a library to get loaded in the header.
• For example:

jquery.ui:
  header: true
  js:
    assets/vendor/jquery.ui/ui/core-min.js: {}

SMACSS Categorization

• Drupal follows a SMACSS-style categorization and all CSS files are loaded first based on their category and then by the order.
• SMACSS categorization is used to set the weight of CSS files, this will not work for JS files.
• To set CSS weights there are 5 different levels:
         ◦ base – This rule consists of styling HTML elements only. CSS_BASE = -200
         ◦ layout – Macro management of page or arrangements of elements on the page, including any grid system. CSS_LAYOUT = -100
         ◦ component – Components are reusable and discrete UI elements. CSS_COMPONENT = 0
         ◦ state – Styles that deal mostly with client-side changes such as hovering links, opening modal dialog, etc. CSS_STATE = 100
         ◦ theme – This is purely visual styling such as box-shadow, backgrounds, borders, colors, etc. CSS_THEME = 200

Attach an Asset Library

1. Globally: 

1. We can attach the asset library globally via the THEMENAME.info.yml file, but this approach would work only for a Theme.
2. For any modules you should use hook_page_attachments_alter() or similar.
3. For example:

name: 'My Custom Theme'
type: theme
description: 'A custom Drupal 9 theme for demonstration purposes.'
package: Custom
core_version_requirement: ^8 || ^9 || ^10
base theme: false

libraries:
  - THEMENAME/global-styling
  - THEMENAME/global-scripts

2. Conditionally, via a preprocess function using #attached: 

If you need to restrict the library to a particular page or element, then this is the best way to add libraries.

For example:
Taking a case where we need to attach a library to our page, then we can use hook_page_attachments_alter():

/**
* Implements hook_page_attachments_alter().
*/
function custom_module_page_attachments_alter(array &$attachments) {
  // Adding stylesheet to the page.
  $attachments['#attached']['library'][] = 'custom_module/custom-styles';
  
  // Add a custom JavaScript file to the page.
  $attachments['#attached']['library'][] = 'custom_module/custom-scripts';

  }

Or hook_preprocess_page():

/**
* Implements hook_preprocess_page().
*/
function custom_module_preprocess_page(&$variables) {
  // Adding stylesheet to the page.
  $attachments['#attached']['library'][] = 'custom_module/custom-styles';
}

Similarly, with different preprocess functions we can attach a library using the #attached render array property like:

/**
* Implements hook_page_attachments_alter
*/
function custom_module_attachments_alter(array &$page) {
  // Get the current path.
  $path = $current_path = \Drupal::service('path.current')->getPath();
  // If we're on the node listing page, add our retro library.
  if ($path == '/node') {
    $page['#attached']['library'][] = 'custom_module/custom-styles';
  }
}

3. Inside a Twig template file:

Use attach_library() in twig template.

{# Attach a CSS library #}
{% attach_library('my_theme/global-styling') %}

{# Attach a JavaScript library #}
{% attach_library('my_theme/global-scripts') %}

Final Thoughts

Assets Library in Drupal (versions 8 and above) has a profound impact on web development. It centralizes the management of CSS and JavaScript files within modules or themes, ensuring consistency and ease of maintenance across a website or application. By bundling these assets together, developers can efficiently control the presentation and functionality of their digital creations. If you’re looking to implement fantastic features of Drupal like this one in your next project, we have a team of Drupal experts who can help you. We’d love to talk!