Contao Konferenz 2019

Webpack in Contao Projekten

Contao Agenturtag 2021

ACHTUNG!

Es lässt sich leider nicht vermeiden, dass es auch etwas technisch wird ;-)
Ich versuche aber, dass es allgemein verständlich bleibt.

Was ist Webpack?

Webpack I

Webpack ist ein "Modul-Bundler"
Versteht Abhängigkeiten & verkettet diese
2017 entwickelte sich Webpack zum meist genutzten JavaScript-Bundler & wird 14 Mio. Mal pro Woche von npm.com heruntergeladen (Stand 2021)

de.wikipedia.org/wiki/Webpack

Webpack II

Mit Loadern ...

... können benutzerdefinierte Aufgaben definiert werdn
... werden weitere Datei-Typen erkannt:
- CSS, SASS, Less
- png, jpeg, svg
- JSON, YAML, XLM
- ...

Wann / Warum soll ich das gebrauchen können?

Webpack III

Wenn Du modularen Code schreibst
Browser-Kompatibilität
Einfach ext. Pakete nutzen & aktuell halten
Abhängigkeiten auflösen
Mehrere Entrypoints

Webpack IV

Assets werden automatisch ...

... für verschiedene Entrypoints generiert
... für verschiedene Umgebungen (prod, dev) generiert
... bei Verwendung eingebunden
... versioniert abgelegt
...

Webpack V

Tools können implementiert werden für ...

... Hot-Reload
... DEV-Server
... Code-Qualität
- Korrektheit
- Style

Installation

Yarn vs npm

Yarn & npm sind beides Paketverwaltungen für JavaScript
Yarn ist lediglich ein anderes Entwicklerwerkzeug
Yarn kann auch über npm aufgerufen werden ;-)
Yarn verwendet eine Lock-Datei (analog composer)

OS


curl -sS https://dl.yarnpkg.com/debian/pubkey.gpg
    | sudo apt-key add -

echo "deb https://dl.yarnpkg.com/debian/ stable main"
    | sudo tee /etc/apt/sources.list.d/yarn.list

sudo apt update
sudo apt install yarn

Beispielhaft auf einem Linux System

Contao


yarn install

composer require symfony/webpack-encore-bundle

Installation innerhalb des Contao Projekts

Struktur

Verzeichnis-Struktur


|- ...
|- config
|  |- config.yml       ⇐ Ergänzungen
|
|- layout              ⇐ neu
|  |- backend
|  |  |- backend.ts
|  |  |- backend.scss
|  |  |- backend.js
|  |
|  |- frontend
|  |  |- scripts
|  |  |- styles
|  |  |- frontend.ts
|  |
|  |- resources
|     |- fonts
|     |- icons
|
|- templates           ⇐ Ergänzungen
|  |- encore           ⇐ neu
|
|- webpack.config.js   ⇐ neu ff
|- tsconfig.json
|- tslint.json
|- package.json
|- postcss.config.js
|- .stylelintrc
|- .stylelintignore
|
|- web
|  |- layout           ⇐ neu
|
|- ...

Ablage innerhalb des Contao Projekts; Verzeichnisse & Dateien

Konfiguration

Dateien

config.yml

webpack.config.js
package.json

tsconfig.json
tslint.json

.stylelintrc
.stylelintignore

postcss.config.js

be_main.html5
fe_page.html5

config.yml

Konfigurations-Datei Contao

docs.contao.org/dev/reference/config

config.yml

webpack_encore:
  output_path: '%kernel.project_dir%/web/layout/'
 
twig:
  default_path: '%kernel.project_dir%/templates'
  paths:
    '%kernel.project_dir%/templates': app

Ergänzungen zu einer bestehenden Contao Konfigurationsdatei

webpack.config.js

Ist ein Node.js-Modul, das ein config Objekt exportiert.
Es kann jeden beliebigen Node.js-Code enthalten.

webpack.js.org/configuration

webpack.config.js

let Encore = require('@symfony/webpack-encore');
 
Encore
    .setOutputPath('web/layout/')
    .setPublicPath('/layout')
 
    .addEntry('backend', './layout/backend/backend.ts')
    .addEntry('frontend', './layout/frontend/frontend.ts')
 
    .addLoader(
        {
            test: /\.scss|\.ts$/,
            enforce: 'pre',
            loader: 'import-glob-loader'
        }
    )
 
    .splitEntryChunks()
 
    .autoProvidejQuery()
 
    .cleanupOutputBeforeBuild()
 
    .enableSourceMaps(!Encore.isProduction())
    .enableVersioning(Encore.isProduction())
 
    .enableSingleRuntimeChunk()
    .enableBuildNotifications()
    .enableTypeScriptLoader()
    .enableSassLoader()
    .enablePostCssLoader()
;
 
if (Encore.isDevServer()) {
    Encore.disableCssExtraction()
}
 
const webpackConfig = Encore.getWebpackConfig();
 
webpackConfig.devServer = {
    host: '0.0.0.0',
    publicPath: '/layout/',
    port: 8080,
    headers: {'Access-Control-Allow-Origin': '*'},
    https: false,
    disableHostCheck: true
};
 
module.exports = webpackConfig;

Bspl. mit zwei Entrypoints, verschiedenen Loadern & Dev-Server

package.json

Alle für ein Projekt benötigten Module & ihre installierten Versionen
Alle Metadaten zu einem Projekt, wie z.B. Autor, Lizenz usw.
Skripts, die ausgeführt werden können, um Aufgaben im Projekt zu automatisieren

docs.npmjs.com/cli/v7/configuring-npm/package-json

package.json

{
  "license": "UNLICENSED",
  "dependencies": {
    "@fortawesome/fontawesome-free": "^5.11.2",
    "bootstrap": "^4.3.1",
    "ekko-lightbox": "^5.3.0",
    "jquery": "^3.4.1",
    "leaflet": "^1.6.0",
    "popper.js": "^1.16.1"
  },
  "devDependencies": {
    "@symfony/webpack-encore": "^0.31.0",
    "core-js": "^3.0.0",
    "import-glob-loader": "^1.1.0",
    "node-sass": "^4.14.1",
    "postcss-import": "^12.0.1",
    "postcss-loader": "^3.0.0",
    "postcss-preset-env": "^6.7.0",
    "sass-loader": "^9.0.1",
    "stylelint": "^13.7.1",
    "stylelint-config-standard-scss": "^1.1.0",
    "stylelint-scss": "^3.18.0",
    "ts-loader": "^5.3.0",
    "typescript": "^4.0.3",
    "webpack-notifier": "^1.6.0"
  },
  "scripts": {
    "build": "yarn encore prod --progress",
    "dev": "yarn encore dev",
    "dev-server": "yarn encore dev-server",
    "watch": "yarn encore dev --https --watch"
  },
  "browserslist": [
    "> 0.5%",
    "last 2 versions",
    "Firefox ESR",
    "not dead"
  ]
}

Bspl. Modulen für Layout & Inhalt; Linting, Skripten, Browser-Kompatibilität

tsconfig.json

Das aktuelle Verzeichnis ist das Stammverzeichnis eines TypeScript-fähigen Projekts
Die meisten (wenn nicht alle) Optionen werden automatisch generiert

typescriptlang.org/docs/handbook/tsconfig-json.html

tsconfig.json

{
  "compilerOptions": {
    "target": "es5",
    "lib": ["es6", "dom"]
  },
  "exclude": [
    "node_modules",
    "vendor",
    "assets"
  ]
}

Bspl. einfach-Konfiguration

tslint.json

Lint-Regeln für syntaktische & semantische Überprüfungen des TypeScript-Quellcodes.

palantir.github.io/tslint/usage/cli

tslint.json

{
  "defaultSeverity": "error",
  "extends": [
    "tslint:recommended",
    "tslint-config-airbnb",
    "tslint-config-prettier"
  ],
  "rules": {
    "no-var-requires": false,
    "member-ordering": [true, {"order": "fields-first"}]
  },
  "jsRules": {},
  "rulesDirectory": []
}

Bspl. einfach-Konfiguration

.stylelintrc

Lint-Regeln bestimmen, wonach der Linter sucht & informiert.
In stylelint sind über 170 Regeln eingebaut.
Standardmäßig sind keine Regeln aktiviert & es gibt keine Standardwerte.
Jede muss Regel explizit konfiguriert werden um sie zu aktivieren.

stylelint.io

.stylelintrc

{
  "extends": [
    "stylelint-config-standard-scss"
  ],
  "rules": {
    "number-leading-zero": "never",
    "at-rule-empty-line-before": null,
    "selector-id-pattern": "^(wrapper|container|left|right|main|header|footer)$",
    "at-rule-no-unknown": null,
    "scss/at-rule-no-unknown": true,
    "block-no-empty": true,
    "comment-no-empty": true,
    "no-duplicate-at-import-rules": true,
    "no-empty-source": true,
    "no-invalid-double-slash-comments": true,
    "max-nesting-depth": 4,
    "indentation": 2,
    "no-descending-specificity": null
  },
  "ignore": [
    "blockless-at-rules",
    "pseudo-classes",
    "selectors-within-list"
  ]
}

Bspl. einfache Linter-Konfiguration

.stylelintignore

bestimmte Dateien ignorieren
stylelint ignoriert standardmäßig das Verzeichnis node_modules

stylelint.io

.stylelintignore

layout/resources

Bspl. einfache Konfiguration; extrene Ressourcen nicht berücksichtigen

postcss.config.js

Transformiert CSS mit JavaScript.
Hunderte PostCSS-Plugins für z.B. automatische Präfixe, zukünftige CSS-Syntaxen, Module, ...

github.com/postcss/postcss

postcss.config.js

module.exports = {
    plugins: {
        'postcss-import': {},
        'postcss-preset-env': {},
        'cssnano': {}
    }
};

Bspl. einfache Konfiguration

be_main.html5
fe_page.html5

Generiertes JavaScript & CSS einbinden
Die Namen beim Einbinden entsprechen den Twig-Templates

docs.contao.org/dev/framework/templates

be_main.html5

<?php $this->extend('be_main'); ?>
 
<?php $this->block('head'); ?>
    <?php $this->parent(); ?>
    <?= \Contao\System::getContainer()
            ->get('twig')
            ->render('@app/encore/be_encore_link_tags.html.twig'); ?>
<?php $this->endblock(); ?>
 
<?php $this->block('container'); ?>
    <?php $this->parent(); ?>
    <?= \Contao\System::getContainer()
            ->get('twig')
            ->render('@app/encore/be_encore_script_tags.html.twig'); ?>
 
<?php $this->endblock(); ?>

Bspl. Einbindung in BE Template

_encore_entry_link_tags.html.twig
_encore_entry_scripts_tags.html.twig

In den Twig-Templates werden die Entry-Points referenziert

twig.symfony.com

be_encore_entry_link_tags.html.twig

{{ encore_entry_link_tags('backend') }}

Bspl. Style Backend Entry Point

be_encore_entry_script_tags.html.twig

{{ encore_entry_script_tags('backend') }}

Bspl. Script Backend Entry Point
Name innerhalb der einfachen Hochkommata entspricht dem Namen in der webpack.config.js

Arbeiten

;-)

ck21-webpack-demo.trilobit.home

Live Beispiel

Commands


yarn encore dev

yarn encore dev-server --watch

yarn encore dev-server --hot --https --disable-host-check --host ck21-webpack-demo.trilobit.home

yarn encore production

Beispielhaft auf einem Linux System

Vereinfachungen

Ganz schön viel Overhead?!

Ja! & Nein!

Wir haben sehr viele Punkte vereinheitlicht
Migrieren z.T. Projekte auf unseren neuen Standard
Pflegen ein trilobit-contao-Skeleton
haben sehr viele weitere Möglichkeiten wie
- automatisches inlinen von Grafiken
- ...

Erfahrungen

Lohnt sich der Overhead?

Ja!

Die Code Qualität steigt
... und damit werden Fehler und Feedbackrunden weniger
Benötigte Ressourcen werden erkannt & gemeinsam abgelegt
Einfacheres Debugging durch unterschiedliche Ausleitung des Codes
Höhere Kompatibilität von Code

Unser Alltag

Weniger Caching-Probleme nach Deployment
Integration in unsere CI
Einfachere Wiederverwendbarkeit von Code
Bessere Performance
Gute Integration in die IDE (PhpStorm)

Weitere Schritte

Durchatmen
Eure Fragen ;-)

Vielen DANK!

Wir lieben Kunden, für die der Livegang einer Webseite nicht das Ende sondern der Anfang des Abenteuers ist.

trilobit GmbH

KnowHow

trilobit GmbH / Peter Adelmann

twitter.com/trilobitgmbh
twitter.com/mineralwa
facebook.com/trilobitgmbh
facebook.com/peter.adelmann.offenburg
xing.com/companies/trilobitgmbh
xing.com/profile/Peter_Adelmann2

github.com/trilobit-gmbh
packagist.org/packages/trilobit-gmbh

Webpack in Contao Projekten

Contao Agenturtag 2021

ACHTUNG!

Was ist Webpack?

Webpack I

Webpack II

Wann / Warum soll ich das gebrauchen können?

Webpack III

Webpack IV

Webpack V

Installation

Yarn vs npm

OS

Contao

Struktur

Verzeichnis-Struktur

Konfiguration

Dateien

config.yml

config.yml

webpack.config.js

webpack.config.js

package.json

package.json

tsconfig.json

tsconfig.json

tslint.json

tslint.json

.stylelintrc

.stylelintrc

.stylelintignore

.stylelintignore

postcss.config.js

postcss.config.js

be_main.html5fe_page.html5

be_main.html5

*_encore_entry_link_tags.html.twig*_encore_entry_scripts_tags.html.twig

be_encore_entry_link_tags.html.twig

be_encore_entry_script_tags.html.twig

Arbeiten

;-)

Live Beispiel

Commands

Vereinfachungen

Ganz schön viel Overhead?!

Erfahrungen

Lohnt sich der Overhead?

Unser Alltag

Weitere Schritte

Weitere Schritte

Vielen DANK!

Wir lieben Kunden, für die der Livegang einer Webseite nicht das Ende sondern der Anfang des Abenteuers ist.

KnowHow

trilobit GmbH / Peter Adelmann

be_main.html5
fe_page.html5

_encore_entry_link_tags.html.twig
_encore_entry_scripts_tags.html.twig