berecont/contao-scss-compiler-bundle

Compiles SCSS files to CSS from the Contao backend.

1.1.0 2026-08-12 21:00 UTC

Requires

• php: ^8.3 || ^8.4
• contao/core-bundle: ^5.3
• contao/manager-bundle: ^5.3
• scssphp/scssphp: ^1.12 || ^2.0

Requires (Dev)

• contao/manager-plugin: ^2.0

Conflicts

• contao/manager-plugin: <2.0 || >=3.0

MIT

• Bernhard Renner

• css
• sass
• scss
• compiler
• contao

Published on Packagist.org on 2026-08-13 11:42 UTC

README

Ein Backend-Bundle für Contao, mit dem SCSS-Dateien direkt in der Contao-Administration zu CSS kompiliert werden können.

Das Bundle richtet sich an Projekte, in denen Styles komfortabel in SCSS gepflegt, im Frontend jedoch als fertig kompilierte CSS-Datei eingebunden werden sollen.

Features

• SCSS-Quelldatei über den Contao-Dateipicker auswählen
• CSS-Zieldatei über den Contao-Dateipicker festlegen
• Zielpfad und Zieldatei getrennt von der Quelle wählbar
• vorhandene CSS-Zieldateien aktualisieren bzw. überschreiben
• mehrere Compiler-Konfigurationen als eigene Datensätze verwalten
• einzelne SCSS-Konfigurationen direkt im Backend kompilieren
• mehrere konfigurierte Stylesheets zentral verwalten
• optionale Erstellung einer Source Map
• Status- und Fehlermeldungen direkt im Contao-Backend
• Integration als Backend-Modul unter System

Voraussetzungen

• PHP ^8.3 || ^8.4
• Contao ^5.3 || ^5.7
• Composer

Die tatsächlich unterstützten Versionen richten sich zusätzlich nach den Abhängigkeiten, die in der composer.json des Bundles definiert sind.

Installation

Über Composer / Packagist

Sobald das Bundle über Packagist veröffentlicht ist:

composer require berecont/contao-scss-compiler-bundle

Anschließend den Contao Manager bzw. die Datenbankmigration ausführen.

Verwendung

Nach der Installation steht im Contao-Backend unter System das Modul für den SCSS-Compiler zur Verfügung.

Für jede gewünschte Kompilierung wird ein eigener Datensatz angelegt.

Dabei werden im Wesentlichen folgende Angaben definiert:

1. Quelldatei
   Die zu kompilierende .scss-Datei.

2. Zieldatei
   Die CSS-Datei, in welche das Ergebnis geschrieben werden soll.

3. Ausgabeformat
   Es kann zwischen Komprimiert und Formatiert gewählt werden. Komprimiert erzeugt eine *.min.css.

4. Source Map
   Optional kann eine Source Map für die erzeugte CSS-Datei erstellt werden.

Die SCSS-Datei kann anschließend über die entsprechende Aktion im Backend kompiliert werden.

Beispiel

Eine mögliche Projektstruktur:

files/
└── assets/
    ├── scss/
    │   ├── main.scss
    │   ├── base/
    │   ├── components/
    │   ├── layout/
    │   └── vendors/
    └── css/
        └── main.css

Eine Compiler-Konfiguration könnte damit beispielsweise folgende Zuordnung enthalten:

Quelle:
files/assets/scss/main.scss

Ziel:
files/assets/css/main.css

Im Seitenlayout von Contao wird anschließend nur noch die erzeugte CSS-Datei eingebunden.

SCSS-Syntax und Sass-Kompatibilität

Welche SCSS-Funktionen verwendet werden können, hängt vom eingesetzten Sass-Compiler bzw. der verwendeten Sass-Implementierung ab.

Insbesondere moderne Dart-Sass-Funktionen wie

@use 'base/variables';
@use 'components/buttons';

werden nicht von jeder PHP-basierten Sass-Implementierung unterstützt.

Falls beim Kompilieren beispielsweise folgende Meldung erscheint:

Sass modules are not implemented yet.

unterstützt der aktuell eingesetzte Compiler das Sass-Modulsystem mit @use bzw. @forward nicht.

In diesem Fall muss entweder:

• die SCSS-Struktur an die vom Compiler unterstützte Syntax angepasst werden, oder
• eine Sass-Implementierung verwendet werden, die das moderne Modulsystem unterstützt.

Dies ist keine Einschränkung von Contao selbst, sondern des jeweiligen Sass-Compilers.

Hinweise für produktive Projekte

Die generierte CSS-Datei sollte im Contao-Seitenlayout eingebunden werden – nicht die SCSS-Quelldatei.

SCSS-Dateien dienen damit ausschließlich als Entwicklungsquelle:

SCSS → Kompilierung → CSS → Frontend

Dadurch muss im Frontend keine SCSS-Kompilierung während eines Seitenaufrufs stattfinden.

Es empfiehlt sich außerdem, generierte Source Maps nur dann produktiv bereitzustellen, wenn sie tatsächlich benötigt werden.

Dateirechte

Der PHP-/Webserver-Prozess benötigt Schreibrechte für das Verzeichnis der CSS-Zieldatei.

Kann eine Datei nicht erzeugt oder überschrieben werden, sollten daher insbesondere folgende Punkte geprüft werden:

• Existiert das Zielverzeichnis?
• Ist das Verzeichnis für PHP beschreibbar?
• Darf eine bereits vorhandene CSS-Datei überschrieben werden?
• Liegen Quelle und Ziel innerhalb der von Contao verwalteten bzw. erlaubten Verzeichnisse?

Projektstatus

Das Bundle befindet sich in aktiver Entwicklung.

Vor dem produktiven Einsatz empfiehlt es sich, die Kompilierung mit der im jeweiligen Projekt verwendeten SCSS-Struktur und Sass-Syntax zu testen.

Fehler melden

Fehler und Verbesserungsvorschläge können über die Issues des GitHub-Repositories gemeldet werden.

Bei Compiler-Fehlern sind insbesondere folgende Angaben hilfreich:

• Contao-Version
• PHP-Version
• Bundle-Version
• verwendete SCSS-Syntax
• vollständige Fehlermeldung
• möglichst kleines Beispiel, mit dem sich der Fehler reproduzieren lässt

Lizenz

Dieses Projekt ist unter der MIT-Lizenz veröffentlicht. Contao und verwendete Drittanbieter-Bibliotheken unterliegen ihren jeweiligen eigenen Lizenzen.

Entwicklung

Dieses Projekt wurde teilweise mit Unterstützung von KI-Werkzeugen entwickelt. KI-Unterstützung wurde insbesondere bei Code-Generierung, Review und Dokumentation eingesetzt. Konzeption, Integration, Tests und Freigabe erfolgen durch den Autor.

Autor

berecont

Contao Bundle zur komfortablen SCSS-zu-CSS-Kompilierung im Backend.