Always run PurgeCSS if the project configures it

README.md

@@ -107,3 +107,41 @@ module.exports = {
     "npmdir": "node_modules"
 }
 ```
+
+### Additional config options
+
+#### PurgeCSS
+
+[PurgeCSS](https://purgecss.com/) is a tool to automatically remove unused CSS. webfactory-gulp-preset comes with 
+postcss-purgecss preinstalled, but it is only activated if a `purgeCss` object is defined as a property of the 
+`styles` object in `gulp-config.js`.
+
+All documented options (for the PostCSS implementation) are supported. 
+
+Example (excerpt from `gulp-config.js`):
+
+```js
+// […]
+styles: {
+    files: [
+        {
+            name: 'main.css',
+            files: [
+                'PATH_TO_PROJECT_ASSETS_DIR/scss/main.scss',
+            ],
+            destDir: 'css'
+        }
+    ],
+    purgeCss: {
+        content: [
+            './src/PROJECT_TEMPLATES/**/*.twig',
+            './src/JS_COMPONENTS_THAT_USE_CSS_SELECTORS/**/*.js',
+            './vendor/PACKAGE/TEMPLATES/**/*.twig',
+        ],
+        safelist: ['ANY_VALID_CSS_SELECTOR']
+    },
+    postCssPlugins: postCssPlugins,
+    watch: ['src/**/*.scss']
+},
+// […]
+```

config/postcss-plugins-default.js

@@ -1,6 +1,16 @@
-const $ = require('../plugins')(); /// lädt alle gulp-*-Module in $.*
+const $ = require('../plugins')(); /// load all gulp-*-Modules in $.*
+
+// This custom extractor will also match selectors that contain
+// special chars like "_", ":", "\" and "@"
+function utilityCssExtractor(content) {
+    return content.match(/[a-zA-Z0-9-_:@\/]+/g)
+}
 
 function postCssPlugins(config, stylesheet) {
+    // Grab a PurgeCSS config to use;
+    // always prefers a stylesheet-specific one over a global config for all CSS files
+    let purgeCssConfig = stylesheet.purgeCss || config.styles.purgeCss;
+
     return [
         $.autoprefixer(),
         $.postcssurl({
@@ -10,8 +20,19 @@ function postCssPlugins(config, stylesheet) {
                 }
                 return $.path.relative(`${config.webdir}/${stylesheet.destDir}/`, asset.absolutePath).split("\\").join("/");
             }
-        })
-    ];
+        }),
+        // conditionally run PurgeCSS if any config (local or global) was found
+        purgeCssConfig ? $.purgecss({
+            content: purgeCssConfig.content,
+            extractors: [
+                {
+                    extractor: utilityCssExtractor,
+                    extensions: ['twig', 'js']
+                }
+            ],
+            safelist: purgeCssConfig.safelist
+        }) : false
+    ].filter(Boolean); // Strip falsy values (this enables conditional plugins like PurgeCSS)
 }
 
 exports.postCssPlugins = postCssPlugins;

package.json

@@ -1,8 +1,8 @@
 {
   "name": "webfactory-gulp-preset",
-  "version": "1.0.5",
+  "version": "1.1.0",
   "dependencies": {
-    "@fullhuman/postcss-purgecss": "^3.0.0",
+    "@fullhuman/postcss-purgecss": "^3.1.3",
     "autoprefixer": "^10.0.0",
     "browser-sync": "^2.26.7",
     "browserslist-config-webfactory": "^1.0.0",

plugins/index.js

@@ -6,7 +6,8 @@ module.exports = function() {
     $['browserSync'] = require('browser-sync').create();
     $['log'] = require('fancy-log');
     $['path'] = require('path');
-    $['postcssurl'] = require("postcss-url");
+    $['postcssurl'] = require('postcss-url');
+    $['purgecss'] = require('@fullhuman/postcss-purgecss');
     $['through2'] = require('through2');
 
     return $;