compiler_scss

Introduction

This module provides an SCSS compiler plugin powered by scssphp to enable runtime SCSS compilation within Drupal. It is intended for developers building custom modules or themes who need dynamic stylesheets that are directly influenced by the site's configuration.

This module can be used with Theme Compiler to define dynamic assets in your themes. Check its project page for more information. You may also want to check the Compiler ecosystem for other creative applications for this module.

Usage

A typical development workflow using this module consists of the following steps:

1. Building configuration forms that utilize the schema types and form elements provided by this module.
2. Creating and configuring an SCSS compiler plugin instance.
3. Compiling an asset and storing it on disk (e.g., the public:// file system).
4. Using the compiled asset (e.g., in a library definition).

The sections below will describe the available configuration schema types and form elements, and the basic process for using the compiler plugin.

Configuration schema

compiler_scss_color

A mapping with the following structure:

• red: The red channel value (0-255) of the color; integer.
• green: The green channel value (0-255) of the color; integer.
• blue: The blue channel value (0-255) of the color; integer.
• alpha: The alpha channel value (0-1) of the color; float, optional.

If the alpha channel is not supplied, it defaults to fully opaque.

compiler_scss_font_family

A sequence of font family names, or generic font family keywords (string).

compiler_scss_font_weight

An integer value from 1 to 1,000.

compiler_scss_number

A mapping with the following structure:

• value: The magnitude of the number; float.
• unit: The unit for the number; string enumeration.

See the schema definition for a list of supported units.

Form elements

compiler_scss_color

A custom element that supports setting color values.

Supported render array keys:

• #default_value: Sets the default value of the form element. Must be in the same format as the compiler_scss_color schema type.
• #description: Sets the description of the element; string or translatable markup.
• #required: Sets whether a value is required for submission; boolean.
• #title: Sets the title of the element; string or translatable markup.

This element does not support alpha channel values. This is largely because browsers lack support for this in their native inputs.

compiler_scss_font_family

A custom element that extends the textarea element, and supports setting a list of font family names (one per line).

compiler_scss_font_weight

A custom element that extends the number element, overriding the following render array keys:

• #max: 1,000
• #min: 1
• #step: 1

Additionally, the submitted values will be parsed into an integer in this range, or fall back to NULL on failure.

compiler_scss_number

A custom element that supports setting single-unit number values.

Supported render array keys:

• #default_value: Sets the default value of the form element. Must be in the same format as the compiler_scss_number schema type.
• #description: Sets the description of the element; string or translatable markup.
• #required: Sets whether a value is required for submission; boolean.
• #title: Sets the title of the element; string or translatable markup.
• #units: Sets the list of units available as options for the element; must be a UnitGroup, Unit, or a list of Unit values; required key.

Compiler plugin

You can get an instance of the plugin provided by this module as follows:

/** @var \Drupal\compiler\Plugin\CompilerPluginManagerInterface */
$compiler_plugin_manager = \Drupal::service('plugin.manager.compiler');
/** @var \Drupal\compiler_scss\Plugin\Compiler\ScssInterface */
$compiler = $compiler_plugin_manager->createInstance('scss');

// @todo Configure the compiler with injected variables, functions, etc...

You can compile SCSS source code as follows:

// Choose the appropriate input type based on how you want to feed source
// code to the compiler plugin.
$file = new \Drupal\compiler\CompilerInputFile('/path/to/source.scss');
$source = new \Drupal\compiler\CompilerInputSource('$text: "Hello, world!" !default; .style { content: $text; }');

// The compiler will return a string containing the compilation result, or
// throw an exception upon failure.
$result = $compiler->compile($file);
echo $result . \PHP_EOL;

$result = $compiler->compile($source);
echo $result . \PHP_EOL;

// @todo Store these assets for later use.

The SCSS compiler plugin offers several interface methods that can be used to configure the compilation process. These methods are summarized below.

Deprecation handling

The following methods allow you to configure how deprecation warnings will be handled:

• ScssInterface::setFatalDeprecations(Deprecation ...$deprecations): void: Set the list of deprecations that should be considered fatal.
• ScssInterface::setFutureDeprecations(Deprecation ...$deprecations): void: Set the list of deprecations to opt into early warnings.
• ScssInterface::setSilenceDeprecations(Deprecation ...$deprecations): void: Set the list of deprecations to silence.
• ScssInterface::setQuietDeps(bool $value): void: Set whether to silence deprecation warnings for imported stylesheets.

Variable / function injection

The following methods allow you to manage variables and host functions that your source code can leverage during compilation:

• ScssInterface::setFunction(string $identifier, \Closure $callback, array $arguments = [], bool $overwrite = FALSE): string: Set a user-defined host function to make available to the compiler.
• ScssInterface::setVariable(string $identifier, mixed $value, bool $overwrite = FALSE): string: Set a variable to inject into the compiler.
• ScssInterface::unsetFunction(string $identifier): void: Unset the function with the supplied identifier.
• ScssInterface::unsetVariable(string $identifier): void: Unset the variable with the supplied identifier.

A value conversion process is applied to all values provided to the compiler, including injected variables and function return values. Atomic values, basic arrays, plain data objects, and values that conform to the schema types provided by this module are automatically converted into their corresponding SCSS representations.

Miscellaneous

• ScssInterface::setImportPaths(string ...$paths): void: Set the import paths that the compiler should use during compilation.
• ScssInterface::setLogger(LoggerInterface $logger): void: Set the logger to use during compilation.
• ScssInterface::setOutputStyle(OutputStyle $style): void: Set the output style to use for the compiled result.