SASS / SCSS Compiler

SCSS Compiler compiles a theme's or module's SCSS into CSS from within Drupal, using scssphp, a pure-PHP Sass compiler. It needs no Node.js, no gulp or webpack and no command-line access. This makes it useful on managed hosting, on locked-down environments, and for teams that would rather not maintain a front-end build chain.

Features

• Watch mode for development: on page requests, checks the SCSS source directory and the additional import paths, at most once every few seconds (configurable), and recompiles when a file has changed since the last compile. By default this happens only for logged-in users. A separate setting turns it on for anonymous traffic.
• Manual compile from the settings form with Compile and write, or from Drush with drush scss:compile (aliases scss, scss-c), which exits non-zero if anything fails.
• Test button that compiles and shows the CSS output and file size on screen without writing anything.
• Compiles any theme installed on the site. The default theme is used if none is chosen.
• Additional directories to compile, such as custom modules that ship their own SCSS, and additional import paths.
• Recursive discovery of .scss files. Partials beginning with _ are skipped, as Sass convention requires, and a list of files to ignore can be set. Subdirectories are mirrored in the output: scss/layout/grid.scss becomes css/layout/grid.css.
• Output styles from scssphp (expanded or compressed), and optional source maps written next to the CSS, with paths relative to the map.
• Last-compile time for each watched directory, shown on the settings page.
• hook_scss_preprocess_alter(&$stylesheet, $path), available to both modules and themes, for injecting variables or rewriting SCSS before it is compiled.
• Errors are reported per file and per directory as Drupal messages. A broken file or a missing directory does not stop the others from compiling.

Requirements

• Drupal 10.2 or later, Drupal 11, or Drupal 12.
• scssphp/scssphp 2.x, installed automatically by Composer.
• To compile from the browser, the CSS output directory must be writable by the web server. See Production use.

Installation and configuration

1. composer require drupal/scss, then drush en scss.
2. Grant the restricted Administer SCSS Compiler permission to the roles that need it.
3. Go to Configuration › Development › SCSS Compiler (/admin/config/development/scss).
4. Choose the theme to compile, and set the source and destination directory names relative to the theme root. The defaults are scss and css.
5. Press Test to check the output, then Compile and write. To compile automatically while you work, enable Watch for theme changes.

Production use

Watch mode checks file modification times on page requests, so it is a development tool. Compiling from the browser also requires the web server to write into the theme or module directory, which is part of the code base. On production sites, leave watch mode off, and commit the compiled CSS or run drush scss:compile during deployment or in CI, so the code base can stay read-only for the web server.

Documentation

Configuration, usage, extending, troubleshooting and upgrade notes: project.pages.drupalcode.org/scss.

Known problems

scssphp lags behind Dart Sass on some newer language features. In scssphp 2.1, @use and @forward are not implemented; use @import. Unsupported syntax is reported as a compile error naming the file, and other files still compile.

Credits

Developed and maintained by Jason P. Salter and Tyler Brown Cifu Shuster of FivePaths, LLC.