feat: add option.transform

README.md

@@ -79,6 +79,47 @@ If defined, the style-loader will re-use a single `<style>` element, instead of
 
 If convertToAbsoluteUrls and sourceMaps are both enabled, relative urls will be converted to absolute urls right before the css is injected into the page. This resolves [an issue](https://github.com/webpack/style-loader/pull/96) where relative resources fail to load when source maps are enabled.  You can enable it with the convertToAbsoluteUrls query parameter (`?convertToAbsoluteUrls`).
 
+#### `cssTransformation`
+
+A `cssTransformation` is a function that can modify the css just before it is loaded into the page by the style-loader. 
+This function will be called on the css that is about to be loaded and the return value of the function will be loaded into the page instead of the original css.
+If the return value of the `cssTransformation` function is falsy, the css will not be loaded into the page at all. 
+
+Usage:
+
+**webpack.config.js**
+```js
+{
+  loader: 'style-loader'
+  options: {
+    cssTransformation: 'path/to/transformCSS'
+  }
+}
+```
+
+**transformCSS.js**
+```js
+module.exports = function(originalCss) {
+    // Here we can change the original css
+    const transformed = css.replace('.classNameA',  '.classNameB');
+    return transformed;
+}
+```
+
+Example of conditional loading of css:
+
+**conditionalCSS.js**
+```js
+module.exports = function (css) {
+   // If the condition is matched load [and transform] the CSS
+   if (css.includes('something I want to check')) {
+     return css; 
+   }
+   // If a falsy value is returned, the CSS won't be loaded 
+   return false
+}
+```
+
 #### `attrs`
 
 If defined, style-loader will attach given attributes with their values on `<style>` / `<link>` element.

addStyles.js

@@ -174,7 +174,24 @@ function attachTagAttrs(element, attrs) {
 }
 
 function addStyle(obj, options) {
-	var styleElement, update, remove;
+	var styleElement, update, remove, cssTransformationResult;
+
+	// If a cssTransformation function was defined, run it on the css
+	if (options.cssTransformation && obj.css) {
+	    cssTransformationResult = options.cssTransformation(obj.css);
+
+	    if (cssTransformationResult) {
+	    	// If cssTransformation returns a value, use that instead of the original css.
+	    	// This allows running runtime transformations on the css.
+	    	obj.css = cssTransformationResult;
+	    } else {
+	    	// If the cssTransformation function returns a falsy value, don't add this css. 
+	    	// This allows conditional loading of css
+	    	return function() {
+	    		// noop
+	    	};
+	    }
+	}
 
 	if (options.singleton) {
 		var styleIndex = singletonCounter++;

index.js

@@ -14,8 +14,13 @@ module.exports.pitch = function(remainingRequest) {
 		"// load the styles",
 		"var content = require(" + loaderUtils.stringifyRequest(this, "!!" + remainingRequest) + ");",
 		"if(typeof content === 'string') content = [[module.id, content, '']];",
+		"// Prepare cssTransformation",
+		"var cssTransformation;",
+		query.cssTransformation ? "cssTransformation = require('" + path.resolve(query.cssTransformation) + "');" : "",
+		"var options = " + JSON.stringify(query),
+		"options.cssTransformation = cssTransformation",
 		"// add the styles to the DOM",
-		"var update = require(" + loaderUtils.stringifyRequest(this, "!" + path.join(__dirname, "addStyles.js")) + ")(content, " + JSON.stringify(query) + ");",
+		"var update = require(" + loaderUtils.stringifyRequest(this, "!" + path.join(__dirname, "addStyles.js")) + ")(content, options);",
 		"if(content.locals) module.exports = content.locals;",
 		"// Hot Module Replacement",
 		"if(module.hot) {",

test/basicTest.js

@@ -280,4 +280,29 @@ describe("basic tests", function() {
     runCompilerTest(expected, done, function() { return this.css.locals.className; });
   }); // it local scope
 
+  describe("cssTransformation function", function() {
+
+    it("should not load the css if the cssTransformation function returns false", function(done) {
+      styleLoaderOptions.cssTransformation = 'test/cssTransformations/returnFalse';
+      const expected = existingStyle;
+      runCompilerTest(expected, done);
+    });
+
+    it("should not load the css if the cssTransformation function returns undefined", function(done) {
+      styleLoaderOptions.cssTransformation = 'test/cssTransformations/returnNothing';
+      const expected = existingStyle;
+      runCompilerTest(expected, done);
+    });
+
+    it("should load the transformed css returned by the cssTransformation function", function(done) {
+      const transformCssFunction = require('./cssTransformations/transformCss');
+      styleLoaderOptions.cssTransformation = 'test/cssTransformations/transformCss';
+
+      const expectedTansformedStyle = transformCssFunction(requiredStyle);
+      const expected = [existingStyle, expectedTansformedStyle].join("\n");
+      runCompilerTest(expected, done);
+    });
+
+  });
+
 }); // describe

test/cssTransformations/returnFalse.js

@@ -0,0 +1,3 @@
+module.exports = function(originalCss) {
+    return false;
+}

test/cssTransformations/returnNothing.js

@@ -0,0 +1,3 @@
+module.exports = function(originalCss) {
+
+}

test/cssTransformations/transformCss.js

@@ -0,0 +1,3 @@
+module.exports = function(originalCss) {
+    return originalCss.replace('.required', '.transformed');
+}