Laravel Mix für WordPress-Themes

Seit vielen Jahren sind Task-Runner wie Grunt, Gulp oder webpack aus der professionellen Webentwicklung nicht mehr wegzudenken. Ich hatte bisher schon mit allen dreien zu tun und während ich mit Grunt und Gulp noch ganz gut zurecht gekommen bin, hat mich webpack bisher nicht überzeugen können. Inzwischen bin ich auf Laravel Mix umgestiegen, dessen Claim auf der Website einfach nur ist:

An elegant wrapper around Webpack for the 80% use case.

Laravel Mix Website

Im Prinzip arbeitet man also mit webpack, allerdings wird die Komplexität durch eine recht einfache API zugänglich gemacht:

Laravel Mix provides a clean, fluent API for defining basic webpack build steps for your applications. Mix supports several common CSS and JavaScript pre-processors.

Beschreibung von Laravel Mix auf Github

Nun könnte man meinen, „Laravel Mix“ ist ausschließlich für das PHP-Framework Laravel verfügbar. Ursprünglich war es auch dafür gebaut worden, inzwischen ist es aber unabhängig davon nutzbar. Im WordPress-Umfeld lässt sich Laravel Mix wunderbar für Themes und auch Plugins einsetzen.

Laravel Mix im Theme einsetzen

Wenn bereits mit NPM im Theme gearbeitet wird, lässt sich Laravel Mix ganz einfach installieren:

npm install laravel-mix --save-dev

Anschließend muss noch eine Datei angelegt werden, in der alle Befehle für Laravel Mix enthalten sein werden:

touch webpack.mix.js

Dann öffnet man die webpack.mix.js und kann direkt mit den Befehlen loslegen. Ein Beispiel aus der offiziellen Dokumentation:

// webpack.mix.js
let mix = require('laravel-mix');

mix.js('src/app.js', 'dist').setPublicPath('dist');

In der zweiten Zeile wird Laravel Mix der Variable mix zugewiesen. Anschließend können die verschiedenen Befehle aneinandergekoppelt notiert werden. Im Beispiel wird die Datei app.js, die sich im Ordner src befindet, kompiliert und in den Ordner dist geschrieben. Der Befehl setPublicPath() ist laut Dokumentation für alle Nicht-Laravel-Projekte empfohlen.

Neben JavaScript können natürlich auch CSS-Dateien kompiliert werden. Dabei kann Laravel Mix mit normalen CSS-Dateien, PostCSS, SASS, LESS und Stylus umgehen. Ich nutze inzwischen PostCSS und brauche dafür diesen Befehl:

mix.css('src/app.css', 'dist');

Es gibt auch den Befehl postCss(), welcher ein Alias zu css() ist. Für die anderen Präprozessoren findet ihr die entsprechenden Befehle in der Dokumentation.

Wer mit zusätzlichen Plugins bei PostCSS arbeitet, der muss diese natürlich auch noch einbinden. Das geht über den Befehl options(). Als allererstes fügt man das Plugin per NPM hinzu und trägt das dann in den Options von Laravel Mix ein:

mix.options({
    postCss: [
        require('postcss-custom-properties')
    ]
});

Weitere Plugins werden einfach mit einem Komma getrennt in dem postCSS-Array eingetragen.

Alles zusammen sieht eine webpack.mix.js-Datei wie folgt aus:

// webpack.mix.js
let mix = require('laravel-mix');

mix.js('src/app.js', 'dist')
   .css('src/app.css', 'dist')
   .options({
       postCss: [
           require('postcss-custom-properties')
       ]
   })
   .setPublicPath('dist');

Die Dokumentation von Laravel Mix ist sehr umfangreich und absolut zu empfehlen.

Laravel Mix ausführen

Sobald die Konfigurations-Datei fertig ist, kann diese über die Konsole ausgeführt werden. Laravel Mix kommt seit Version 6 mit verschiedenen CLI-Befehlen, dieser hier ist zum einfachen Ausführen:

npx mix

Ich selbst nutze aber in der package.json eigene CLI-Befehle, wie man es von anderen Task-Runnern kennt:

"scripts": {
    "dev": "npm run development",
    "development": "cross-env NODE_ENV=development node_modules/webpack/bin/webpack.js --progress --config=node_modules/laravel-mix/setup/webpack.config.js",
    "watch": "npm run development -- --watch",
    "hot": "cross-env NODE_ENV=development node_modules/webpack-dev-server/bin/webpack-dev-server.js --inline --hot --config=node_modules/laravel-mix/setup/webpack.config.js",
    "prod": "npm run production",
    "production": "cross-env NODE_ENV=production node_modules/webpack/bin/webpack.js --config=node_modules/laravel-mix/setup/webpack.config.js"
  },

So kann ich einfach den Watch-Prozess mit folgendem Befehl starten:

npm run watch

Der Rest ist wie mit Grunt und Gulp auch: man muss sich durchprobieren, die Konfiguration anpassen und die Befehle ausführen. Ich nutze es z. B. auch für das Kopieren von Schriften und Bildern/Icons.