Scss compiling

Your themes can, if you need to, compile scss files into css. The compiler itself has its own package, please refer to it for documentation.

All scss features are considered unstable until the underlying compiler has a stable release. It's likely future versions of this package will see breaking changes regarding scss compiling.

The default compiler defines the following :

• minified css on production
• sourcemaps disabled on production
• parent themes added as import paths. This means you can import scss files from a parent theme.Theme file loader plugin for images and fonts. This means you can reference assets (in the url() function) from a parent theme and they will be extracted.
• JSON Manifest plugin
• Public path set to @themesWebPath/theme-handle which is equivalent to @webroot/themes/theme-handle. That's where the css files will be written

You can overridde your theme's method getScssCompilerOptions() to change the default options, or getScssCompilerPlugins() to change the default plugins.

Compiling can be done in two ways :

Scss bundle

Define a bundle that extends Ryssbowh\CraftThemes\scss\ScssAssetBundle and reference some scss files to compile. The compiling by default will only happen if devMode is on (This can be changed in the bundle). If you're on devMode and use such a bundle, the scss will be compiled at each request.

Example for a compilation that uses a manifest :

use Ryssbowh\CraftThemes\scss\ScssAssetBundle;

class FrontCssAssets extends ScssAssetBundle
{
    public $baseUrl = '/themes/my-theme';
    public $theme = 'my-theme';
    public $scssFiles = [
        'assets/src/scss/app.scss' => 'app.css'
    ];
    public $basePath = '@themeWebPath';
    //optional
    public $compilerOptions = [
        'style' => 'compressed'
    ];
    
    /**
    * Optional, only needed if you use a manifest
    */
    public function registerAssetFiles($view)
    {
        $manifestFile = \Craft::getAlias('@themeWebPath/manifest.json');
        if (file_exists($manifestFile)) {
            $manifest = json_decode(file_get_contents($manifestFile), true);
            $this->css[] = $manifest['app.css'];
        }
        parent::registerAssetFiles($view);
    }

    /**
    * Enable/disable compilation here
    */
    protected function isCompilingEnabled(): bool
    {
        return parent::isCompilingEnabled();
    }

    /**
    * Optionally change the compiler, the default one (defined by your theme) will be used otherwise
    */
    protected function getCompiler(): Compiler
    {
        return parent::getCompiler();
    }
}

In templates

Raw scss

Use the twig tag scss to compile scss at page load.

Example :

{% scss %}
    @import "../../scss/main.scss";
    h1 a::after {
        content: "";
        background: center/contain no-repeat url(../../assets/images/image.png);
    }
{% endscss %}

The scss will be compiled once (and every time the scss is changed) and put in cache so your page load is not slowed down.

Imports or urls path are relative to the folder where the template is.

Caches can be cleared using the backend or the command craft clear-caches/themes-scss-cache

File

You can also compile an existing file :

{% scss file "../../assets/src/scss/components/main.scss" %}

Options

Use the force option to force the compiling.

{% scss force %}
    @import "../../scss/main.scss";
    h1 a::after {
        content: "";
        background: center/contain no-repeat url(../../assets/images/image.png);
    }
{% endscss %}

// Or

{% scss file "../../assets/src/scss/components/main.scss" force %}

Use the with options {} to override some compiler options :

{% scss with options {style: 'compressed'} %}
    @import "../../scss/main.scss";
    h1 a::after {
        content: "";
        background: center/contain no-repeat url(../../assets/images/favicon.png);
    }
{% endscss %}

// Or

{% scss file "../../assets/src/scss/components/main.scss" with options {style: 'expanded'} %}

Note that changing the compiler options publicFolder and fileName will have no effect as they will be overridden.

Command line

Use craft themes/scss/compile theme-handle src-file dest-file to compile a scss file.