theme_compiler

Introduction

This module allows you to define dynamic assets in your themes. These assets will be compiled at runtime each time a theme is installed or uninstalled, or whenever the theme's settings are changed.

Usage

The basic steps required to set up a compiled asset are as follows:

1. Install a module in the Compiler ecosystem that provides a compiler plugin.
2. Install this module, and define one or more assets in a *.theme_compiler.yml file in your theme's root folder.
3. Add the compiled asset path as a theme library.
4. Rebuild the site cache (or invalidate the theme_compiler_assets cache tag) to trigger asset discovery.
5. Trigger asset compilation by manually invoking theme_compiler.compiler:compileAssets, or saving your theme's settings.
6. Extend your theme's settings and alter the compilation process using settings values via hook_theme_compiler_TYPE_alter().

The sections below will describe the structure of the *.theme_compiler.yml file, and show example library definitions.

*.theme_compiler.yml structure

For illustrative purposes, below is an example asset definition:

style.css:
  plugin: scss
  source:
    - scss/main.scss

This asset definition uses the scss compiler plugin to compile scss/main.scss, and stores the result at style.css.

More generally:

• The top-most key is the asset path where the compiled result is stored.
• The plugin key contains the machine name of a compiler plugin.
• The source key is a list of theme-relative paths to source code.

The path where the compiled asset will be stored is relative to %theme_compiler.asset_storage_path%/{$provider}, where:

• %theme_compiler.asset_storage_path% is a container parameter set to public://compiled-assets by default, and
• {$provider} is the machine name of the theme that defined the asset.

Library definitions

You can define a library for the above asset definition as follows:

example-library:
  css:
    theme:
      /sites/default/files/compiled-assets/THEME_MACHINE_NAME/style.css:
        preprocess: false

Simply replace THEME_MACHINE_NAME with the actual machine name of the theme that defines the asset.

More generally, if %theme_compiler.asset_storage_path% is publicly-accessible:

• Assets should be defined using their web root-relative paths.
• Assets should always have preprocess: false so that they are excluded from CSS/JS aggregation, which helps with asset caching behavior.

You can define assets dynamically, or provide a custom controller for serving assets if needed, but we cannot provide support in these situations.

Altering the compilation process

Depending on the compiler plugin that you intend to use, there may be ways to alter the compilation process to produce different results. In the above example, the scss plugin allows you to inject variables.

Altering the compilation process is done by implementing hook_theme_compiler_TYPE_alter():

/**
 * Implements hook_theme_compiler_TYPE_alter() for 'scss'.
 */
function example_theme_theme_compiler_scss_alter(
  \Drupal\compiler_scss\Plugin\Compiler\ScssInterface $compiler,
  \Drupal\theme_compiler\Asset $asset
): void {
  $settings = \Drupal::config('example_theme.settings');

  // Inject example_theme.settings:state before the source code is compiled.
  $compiler->setVariable('state', $settings->get('state'));
}

Responding to successful asset compilation

Since 3.1.x, you can implement hook_theme_compiler_asset_updated() to respond to asset compilation in case you need to perform some clean-up operation (e.g., surrogate cache invalidation):

/**
 * Implements hook_theme_compiler_asset_updated().
 */
function example_theme_theme_compiler_asset_updated(
  \Drupal\theme_compiler\Asset $asset
): void {
  /** @var \Drupal\Core\File\FileUrlGeneratorInterface $file_url_generator */
  $file_url_generator = \Drupal::service('file_url_generator');
  $file_url = $file_url_generator->generateString($asset->target);

  \pantheon_clear_edge_paths([$file_url]);
}