README

Compiles SCSS files to CSS at runtime. Uses SCSSPHP as compiler. Compiled CSS is cached and only recompiled when source files or variables change.

Installation

composer require wapplersystems/ws-scss

Requirements

• TYPO3 v14
• PHP 8.2+

Usage via TypoScript

Include SCSS files with the standard page.includeCSS — the extension automatically compiles any .scss file:

page.includeCSS {
  main = EXT:my_sitepackage/Resources/Private/Scss/main.scss
}

Custom output file

page.includeCSS {
  bootstrap = fileadmin/bootstrap/sass/bootstrap.scss
  bootstrap.outputfile = fileadmin/bootstrap/css/mybootstrap.css
}

Output style

compressed (default) or expanded:

page.includeCSS {
  main = EXT:my_sitepackage/Resources/Private/Scss/main.scss
  main.outputStyle = expanded
}

Source maps

Enables SCSS file/line references in browser DevTools:

page.includeCSS {
  main = EXT:my_sitepackage/Resources/Private/Scss/main.scss
  main.sourceMap = true
}

Inline output

Renders CSS inline in a <style> tag instead of a <link> reference:

page.includeCSS {
  critical = EXT:my_sitepackage/Resources/Private/Scss/critical.scss
  critical.inlineOutput = true
}

Variables

Global variables

Available in all SCSS files:

plugin.tx_wsscss.variables {
  primaryColor = #007bff
  secondaryColor = #6c757d
  baseFontSize = 16px
}

Per-file variables

Override or extend global variables for a specific file:

page.includeCSS {
  main = EXT:my_sitepackage/Resources/Private/Scss/main.scss
  main.variables {
    primaryColor = #ff6600
    containerWidth = 1200px
  }
}

Using variables in SCSS

Variables defined via TypoScript are directly available as SCSS variables:

body {
  color: $primaryColor;
  font-size: $baseFontSize;
}

Variable type conversion

The extension automatically converts TypoScript values to proper SCSS types:

SCSS imports

Standard SCSS imports work as expected. Additionally, the extension supports TYPO3's EXT: paths:

@import "variables";
@import "mixins";
@import "EXT:bootstrap/Resources/Public/Scss/bootstrap";

File resolution order: filename.scss, _filename.scss, filename.css.

Usage via Fluid ViewHelper

The extension registers a ViewHelper for compiling SCSS in Fluid templates.

File-based

<wsscss:asset.scss
    identifier="main"
    href="EXT:my_sitepackage/Resources/Private/Scss/main.scss"
/>

With variables

<wsscss:asset.scss
    identifier="styled"
    href="EXT:my_sitepackage/Resources/Private/Scss/styles.scss"
    scssVariables="{primaryColor: '#0066cc', borderRadius: '4px'}"
/>

Inline SCSS

<wsscss:asset.scss identifier="inline">
    $color: red;
    body { background: $color; }
</wsscss:asset.scss>

ViewHelper arguments

Events

AfterVariableDefinitionEvent

Modify variables before compilation:

use WapplerSystems\WsScss\Event\AfterVariableDefinitionEvent;

#[AsEventListener]
final class AddDynamicVariables
{
    public function __invoke(AfterVariableDefinitionEvent $event): void
    {
        $variables = $event->getVariables();
        $variables['dynamicColor'] = '#ff0000';
        $event->setVariables($variables);
    }
}

AfterScssCompilationEvent

Post-process compiled CSS:

use WapplerSystems\WsScss\Event\AfterScssCompilationEvent;

#[AsEventListener]
final class PostProcessCss
{
    public function __invoke(AfterScssCompilationEvent $event): void
    {
        $css = $event->getCssCode();
        $css .= "\n/* Compiled at " . date('c') . " */";
        $event->setCssCode($css);
    }
}

Caching

Compiled CSS is cached in typo3temp/assets/css/. The cache is automatically invalidated when:

• SCSS source files change
• Imported files change
• Variables change
• Output style or source map settings change

To force recompilation, flush caches via backend or CLI:

vendor/bin/typo3 cache:flush --group=system

Development tip

Disable the TypoScript template cache in your backend user settings to trigger SCSS recompilation on every page load during development.

Complete example

plugin.tx_wsscss.variables {
  brandColor = #0066cc
  fontFamily = "Open Sans, sans-serif"
  baseFontSize = 16px
}

page.includeCSS {
  bootstrap = EXT:my_sitepackage/Resources/Private/Scss/bootstrap.scss
  bootstrap.outputStyle = compressed

  theme = EXT:my_sitepackage/Resources/Private/Scss/theme.scss
  theme.outputStyle = compressed
  theme.variables {
    headerHeight = 80px
    sidebarWidth = 300px
  }
}

License

GPL-2.0-or-later