README

On the go SCSS compiling, CSS/JS minifying, merging and caching.

Requirements

This plugin requires Craft CMS 4.0.0 or later.

Installation

composer require cloudgrayau/pitch

Pitch Overview

Pitch is a plugin that allows for on the go SCSS compiling, CSS/JS minifying, merging and caching.

Configuring Pitch

SCSS compiling uses the latest version of scssphp and two output styles are included:

Expanded
Compressed (default)

CSS and JS minifying uses the 'MatthiasMullie\Minify' package (which can be disabled via the settings).

Caching is enabled by default (recommended) and the cache directory and duration can be customised.

3.0.0 Upgrade Notes

Pitch files should now be loaded using the new preferred and cache-busting pitch() twig command. To upgrade, please replace url('scss/asset.scss') with pitch('asset.scss') for example, as per the instructions below. The old method of loading pitch files will still function.

Pitch will now scan the template files and try to automatically regenerate the cache after the cache has been cleared (this is disabled in development mode).

For Craft 5, Pitch now uses the version 2 branch of the scssphp compiler. This release is a full rewrite of the compiler and requires >= PHP8.1.

Advanced Caching Mode

Advanced Caching Mode can also be enabled, which offers superior performance but requires server rewrites and changes to the default storage path. For instructions on how to setup Advanced Caching Mode, please refer to the ADVANCED.md.

Using Pitch

SCSS - {% do view.registerCssFile(pitch('<FILENAME>.scss')) %}
CSS - {% do view.registerCssFile(pitch('<FILENAME>.css')) %}
JS - {% do view.registerJsFile(pitch('<FILENAME>.js')) %}

For example files, please browse to the /vendor/cloudgrayau/pitch/examples/ directory for installation.

You can now compile inline SCSS and minify CSS/JS directly via your templates in Twig.

SCSS - <style>{{ craft.pitch.renderSCSS(entry.field)|raw }}</style>
CSS - <style>{{ craft.pitch.renderCSS(entry.field)|raw }}</style>
JS - <script type="text/javascript">{{ craft.pitch.renderJS(entry.field)|raw }}</script>

Further instructions for the inline method are found below.

Merging & Loading Files

SCSS

{% do view.registerCssFile(pitch('style.scss')) %} will load and compile the following SCSS file:

/CRAFT/web/style.scss

{% do view.registerCssFile(pitch('assets/style,chosen,plugin/owl.scss')) %} will merge and compile the following SCSS files:

/CRAFT/web/assets/style.scss
/CRAFT/web/assets/chosen.scss
/CRAFT/web/assets/plugin/owl.scss

All files being merged will need to have the .scss extension.

In SCSS, #{$baseUrl} refers to the relative @web directory (no trailing slash).

Please note, the old method of loading SCSS files via {% do view.registerCssFile(url('scss/style.scss')) %} will still work.

CSS

{% do view.registerCssFile(pitch('style.css')) %} will load and minify the following CSS file:

/CRAFT/web/style.css

{% do view.registerCssFile(pitch('assets/style,chosen,plugin/owl.css')) %} will merge and minify the following CSS files:

/CRAFT/web/assets/style.css
/CRAFT/web/assets/chosen.css
/CRAFT/web/assets/plugin/owl.css

All files being merged will need to have the .css extension.

In CSS, #{$baseUrl} refers to the relative @web directory (no trailing slash).

Please note, the old method of loading CSS files via {% do view.registerCssFile(url('css/style.css')) %} will still work.

JS

{% do view.registerJsFile(pitch('script.js')) %} will load and minify the following JS file:

/CRAFT/web/script.js

{% do view.registerJsFile(pitch('assets/script,chosen,plugin/owl.js')) %} will merge and minify the following JS files:

/CRAFT/web/assets/script.js
/CRAFT/web/assets/chosen.js
/CRAFT/web/assets/plugin/owl.js

All files being merged will need to have the .js extension.

In JS, $baseUrl refers to the relative @web directory (no trailing slash).

Please note, the old method of loading JS files via {% do view.registerCssFile(url('js/script.js')) %} will still work.

Cache Busting

The new twig pitch() command will automatically embed the last-modified date of the file/s into the compiled filename. Pitch will also scan the template files and try to automatically regenerate the cache after the cache has been cleared (this is disabled in development mode).

If using the old load method, you can also force the browser to re-cache asset files by using :DIGIT in the asset URL prior to the extension, for example 'js/assets/site,plugin/chosen:01.js'.

Whilst in development mode, the browser cache of all assets will be forced to refresh on each page load.

Subresource Integrity (SRI)

You can generate a SRI for pitch files, using the new twig pitch_sri(<FILE>, <HASH>) command. By default, it will use sha384 and it should only be used in tandom with the pitch() command. For example:

{% do view.registerJsFile(pitch('script.js'), {type:'module',integrity:pitch_sri('script.js', 'sha512')}) %}

Please note, the SRI will only be generated after the cache file has been generated.

Inline Compiling & Minifying

You can now compile inline SCSS and minify CSS/JS directly via your templates in Twig, as follows:

SCSS - <style>{{ craft.pitch.renderSCSS(entry.field)|raw }}</style>
CSS - <style>{{ craft.pitch.renderCSS(entry.field)|raw }}</style>
JS - <script type="text/javascript">{{ craft.pitch.renderJS(entry.field)|raw }}</script>

Please note, the @import command in SCSS, will be relative to the @web directory.

I would highly recommend that the inline method is inclosed in {% cache %}{% endcache %} tags for performance reasons.

The Inline Compiling & Minifying integrates great with the Code Field from @nystudio107.

Clearing Cache

The Pitch cache can be cleared via the following methods:

Via the CraftCMS Dashboard Widget
Via the CraftCMS Settings => Pitch
Via the CraftCMS Utilities => Caches
Via the console ./craft pitch/clear

Brought to you by Cloud Gray Pty Ltd

cloudgrayau / pitch

Maintainers

Details