Theme development with SCSS

This page is for developers who are customizing a sub-theme for a Drupal Kit site (read first: Creating and customizing a sub-theme). Developers can add CSS directly to their theme, but it is more sustainable to write SCSS, which can make use of reusable variables across various components.

The Drupal Kit’s “STARTERKIT” sub-theme includes pre-built tasks to develop with SCSS.


Prerequisites & setup

Developers first will need to install NodeJS and NPM on their local development machine. Node version 20 or more recent is required for compiling SCSS.


Using Node Version Manager (NVM) is now recommended for installing Node. It is not required, however, and you may continue to use a global installation of Node.

Your sub-theme of Forty Acres will include a package.json file, which defines package dependencies needed for theme development. The gulpfile.js file additionally defines tasks for linting and compiling CSS. From the root directory of your sub-theme, run:

npm install

This will generate a `node_modules/ directory of dependencies. This directory should not be versioned as part your codebase. If you are using Git for version control, you should add this directory to your .gitignore file so it will not be committed to your repository.

Writing & compiling SCSS

The CSS rendered for a Drupal theme is defined in that theme’s .libraries.yml file (see Adding stylesheets (CSS) and JavaScript (JS) to a Drupal theme). When using an SCSS workflow, however, you should not directly modify the referenced CSS files. The /css directory in your theme represents the compiled version of any SCSS files you are using.

Instead, you should edit the SCSS. There are a handful of boilerplate SCSS files located in the /src/scss directory to get started.

To build the CSS for use with your theme, run:

npm run gulp

Whenever a code change is saved to your SCSS, Gulp will recompile all SCSS files located in /src/scss into CSS equivalents in /css, and will prefix the CSS for cross-browser support.

Additionally, this Gulp task will “lint” your SCSS, enforcing syntax standards to make your code more consistent and readable. Syntax rule violations will print directly to your terminal window during the build process.


The command npm run gulp (as opposed to simply gulp) runs using the locally installed version of Gulp, located at node_modules/gulp/bin/gulp.js, ensuring that an expected version of the task runner is used.