Usage

What gets compiled

For the chosen theme and each additional directory, the module compiles every .scss file under the source directory, recursively, except:

• partials, whose names start with _; they are only imported;
• files listed under Files to ignore.

Files are compiled in alphabetical order of their path. Output mirrors the source tree:

Source	Output
scss/style.scss	css/style.css, css/style.css.map
scss/layout/grid.scss	css/layout/grid.css, css/layout/grid.css.map
scss/_variables.scss	nothing (partial)

Imports resolve against the importing file first, then the source directory, then each additional import path. scssphp 2.1 supports @import but not yet @use or @forward.

Add the compiled CSS to the theme's libraries as usual:

mytheme.libraries.yml

global:
  css:
    theme:
      css/style.css: {}
      css/layout/grid.css: {}

From the settings page

Test compiles every file and shows each file's CSS and size as a message, without writing anything. Use it to check a change before writing.

Compile and write compiles and writes every file. Both buttons use the values on the form, so you can try a change before saving it; neither saves the settings.

From Drush

drush scss:compile

The aliases drush scss and drush scss-c do the same. The command compiles every file, whether or not it changed, prints a message for each, and exits with status 1 if any directory or file failed. Use it in deployment scripts and CI.

Watch mode

With Watch for theme changes on, the module checks for changes on page requests and compiles when needed:

1. Only the main request is checked, not sub-requests.
2. By default only logged-in users trigger the check. Compile while logged out adds anonymous requests, but pages served from Drupal's internal page cache never reach the module.
3. The check runs at most once per Minimum seconds between watch checks (2 by default).
4. A compile is needed when any file in the source directory or an additional import path was modified after the directory's last compile.
5. Only one request compiles at a time; the others skip the check.

The check runs before Drupal's dynamic page cache responds, so cached pages for logged-in users still trigger it.

Production

Watch mode reads every source file's modification time on each check and writes into the code base, so it is for development only. Compiling from the browser also needs the web server to write into the theme or module directory, and a web server that can write code is a security risk.

On production:

• leave watch mode off, for example with $config['scss.settings']['active'] = FALSE; in settings.php;
• commit the compiled CSS, or run drush scss:compile during deployment or in CI as a user that may write to the code base;
• keep the code base read-only for the web server user.

Errors

Each problem is reported as a Drupal message (or a Drush log line) and the rest still compiles:

• a missing source directory or unwritable output directory skips that directory;
• a Sass error skips that file and shows scssphp's message with the file and line.