Working with SCSS in the OPAC and staff client
From Koha Wiki
The OPAC and staff client's default templates use Sass files in SCSS format to generate the CSS files used in the themes. Sass is a "CSS extension" (similar to LESS) which allows authors to use "variables, mixins, operations and functions." Koha's Sass files contain some use of variables and mixins, but their primary difference from standard CSS is the logical grouping of style rules through nested rules.
When making CSS changes in the OPAC or staff client, changes should be made to the .scss files, not the .css files.
As of 2018-09-09 the only Sass file in the staff client is
Setting up your development environment
sudo apt-get install nodejs npm [not necessary in kohadevbox] sudo npm install -g yarn yarn install
If this doesn't work or you're using koha-testing-docker, try the following:
wget -q -O- https://deb.nodesource.com/gpgkey/nodesource.gpg.key | sudo apt-key add -
Add "deb http://deb.nodesource.com/node_8.x stretch main" (where stretch matches your Debian distro) to "/etc/apt/sources.list.d/koha-node.list" Run the following:
apt-get update apt-get install nodejs npm install -g yarn cd <koha-git> yarn install
- Next, install required node modules by running the following command in the Koha base directory
npm install -E
Compiling Sass files
After you have made changes to any .scss file, compile your changes.
For the staff client, run
For the OPAC, run
yarn build --view opac
yarn build process automatically compiles SCSS to CSS, adds automatic vendor prefixing, and minifies the CSS.
There is also a
yarn css command available which might be used by
developers who are making changes to Sass. This command does two things
- Adds .css.map files which aid CSS debugging using in-browser inspector tools.
- Compiles staff-global.css without minification. It can be useful to see unminified CSS during development, especially to see how SCSS compiles.
The build process includes a tool called autoprefixer, used to "parse CSS and add vendor prefixes to CSS rules using values from Can I Use." autoprefixer is run without any explicit options. The default configuration adds automatic vendor prefixes in order to provide coverage for:
- Browsers with greater than 1% global usage
- The last 2 versions of browsers
- Firefox ESR.
This tool eliminates the necessity of adding vendor prefixes to SCSS code.
Guidelines for editing Sass files
As of 2018-08-09 when Bug 19474 and Bug 20427 were initially pushed to master, Koha's SCSS files differ from their previous CSS counterparts primarily in that they use nested syntax. There are two other Sass-specific features to note:
- Some variables are defined near the top of the file. These variables can be used in place of the strings which define them.
- Some mixins are defined.
When adding style rules to Sass files please look for existing rules in which your additions might be logically nested. Remember that nesting adds specificity to your CSS, which may not be necessary for the style you want to achieve. The minimum required specificity is recommended.
Adding Sass files
To add a new CSS file to the OPAC or staff client, simply create the corresponding .scss file in the
css/src directory. Each
.scss file in the
css/src directory is automatically compiled, minified, and saved to the
Committing Sass files
When committing patches, don't include the compiled .css files into any patches, but only the changed .scss files. The RM or RMaints will add the compiled files when pushing the patch.
Noting that yarn build is needed in your test plan is recommended.
.sass-lint.yml is a set of rules for writing consistent SCSS. It is a configuration file for linting SCSS with sass-lint. Various code editors can be set up to do inline SCSS linting, or it can be done on the command line. Currently our SCSS files do not pass all sass-lint tests. New additions should.
See Sass lint rules for information about some notable rules.