Zum Inhalt

Build-Kette

Quellen und Ergebnisse

Ort Was
source/scss/ SCSS-Quellen
source/js/ JavaScript-Quellen
assets/css/, assets/js/ gebaute Ergebnisse
includes/theme-options/*/*/assets/ Assets der Module, Quelle und Ergebnis

Bearbeitet wird immer die Quelle. Dateien in assets/ werden beim nächsten Build überschrieben.

Einrichten

cd wp-content/themes/twtheme
npm install

Gebraucht werden nur zwei Build-Werkzeuge: sass und esbuild. Die übrigen Einträge in der package.json sind Laufzeit-Bibliotheken, die in die Bundles wandern — Splide für den Slider, Tippy für Tooltips, CodeMirror für den Codeblock, Tom Select, Just Validate, fslightbox, Moveable, Spectrum.

Alles bauen

npm run build:all

Das ist der Befehl für den Normalfall. Er führt nacheinander aus:

Schritt Was
copy:tooltip-vendor Tippy-Dateien an ihren Platz kopieren
build:js Haupt-Bundle aus source/js/main/main.js
build:youtube-playlist-js JavaScript des YouTube-Moduls
build:mockups-admin-preview Admin-Vorschau des Mockup-Moduls
build:frontend-js alle JS-Einträge aus den module.json-Dateien
build:css alle SCSS-Einträge

Einzelne Schritte

Stylesheets

npm run build:css
npm run watch:css

Beides läuft über scripts/sass-build.mjs. Das Skript baut die Einstiegsdateien aus source/scss/ und zusätzlich jeden scss-Eintrag, den es in einer module.json findet.

npm run watch ist eine Kurzform für watch:css — beim Arbeiten an Stylesheets der übliche Befehl.

JavaScript

npm run build:js          # Haupt-Bundle
npm run watch:js          # Haupt-Bundle beobachten
npm run build:frontend-js # alle Modul-Einträge

Das Haupt-Bundle entsteht direkt mit esbuild: gebündelt, verkleinert, als IIFE, Ziel ES2018. Die Modul-Einträge laufen über scripts/esbuild-frontend-js.mjs.

build:addons-js ist ein Alias für build:frontend-js.

Assets aus Modulen

Ein Modul trägt seine Build-Einträge selbst in seiner module.json:

{
  "scss": [
    ["assets/foo.scss", "assets/foo.css"],
    ["assets/bar.scss", "theme:assets/css/bar.css"]
  ],
  "js": [
    { "src": "assets/foo.js", "bundle": true },
    { "src": "source/admin.js", "outfile": "admin.js", "bundle": true }
  ]
}
Regel Bedeutung
Pfad ohne Präfix relativ zum Modulordner
Präfix theme: relativ zur Theme-Wurzel

Gefunden werden sie von scripts/module-discovery.mjs. Ein neues Modul mit Assets muss also nirgends eingetragen werden — es genügt die module.json im Modulordner.

Fehlende Quelldateien werden übersprungen. Ein entferntes Modul bricht den Build nicht.

Einzelne Module direkt bauen

Für vier Module gibt es eigene Befehle, wenn man nur an ihnen arbeitet:

npm run build:loops-filter-js
npm run build:hyperlinks-js
npm run build:foreignwords-tooltips-js
npm run build:youtube-playlist-js

Wenn Änderungen nicht ankommen

Die Adressen der Assets tragen eine Versionsnummer, damit Browser und Caches nicht an alten Dateien hängen. Sie steht in der Option twtheme_assets_version.

Erhöhen lässt sie sich in der Admin-Bar unter TWtheme → Update assets. Nach einem Build auf einem laufenden System ist das der erste Griff, wenn im Browser die alte Fassung erscheint.

Reihenfolge beim Suchen:

  1. Ist der Build gelaufen und hat die Datei in assets/ ein neues Datum?
  2. Ist die Asset-Version erhöht?
  3. Ist ein Caching-Plugin oder ein CDN dazwischen?

Was nicht im Build steckt

Die PHP-Dateien werden nicht verarbeitet — sie laufen, wie sie im Repository liegen. Ein Build ist nur für CSS und JavaScript nötig.

Weiter