Minify custom SharePoint themable CSS with Gulp

The ability to create your own themable CSS has been present in SharePoint for a long time:

How to: Make custom CSS files themable in SharePoint 2013

Working with the SharePoint Theming Engine

You can even define custom names/properties in your .spcolor files which can be used in your custom CSS. My colleague Matt Holden has a great post on this here:

Custom .spcolor files for SharePoint Composed Looks

We were using this method in one of our SharePoint Online projects along with Gulp tasks to bundle and minify all our JavaScript/CSS files as per my previous post Simple bundle, minify and upload JS to SharePoint using Gulp

Now, the SharePoint theming engine uses CSS comments to determine the color replacement:

	.myClass p {
	/* [ReplaceColor(themeColor:"ContentAccent1")] */
	background-color: #4b9461;
	}
	a#announcements .alert {
	/* [ReplaceColor(themeColor:"ContentAccent2")] */
	color: #225A40;
	}

view raw Themable_CSS.css hosted with ❤ by GitHub

As per Matt's post, the theming engine replaces the values at run-time to the color defined in the ContentAccess1 section in the spcolor file.

	<?xml version="1.0" encoding="utf-8"?>
	<s:colorPalette isInverted="false" previewSlot1="BackgroundOverlay" previewSlot2="BodyText" previewSlot3="AccentText" xmlns:s="http://schemas.microsoft.com/sharepoint/">
	<s:color name="TileText" value="FFFFFF" />
	<s:color name="TileBackgroundOverlay" value="7F000000" />
	<!-- Custom Dark Green -->
	<s:color name="ContentAccent1" value="225A40" />
	<!-- Custom Muted Green -->
	<s:color name="ContentAccent2" value="4b9461" />
	</s:colorPalette>

view raw spcolor_theme.xml hosted with ❤ by GitHub

For the theming engine to successfully carry out this replacement, the ReplaceColor comment needs to be present in the CSS file we load in SharePoint.

When I minified the Themable.css file using the clean-css gulp plugin, it stripped out all the comments which made the replacement not work:

.myClass p{background-color:#4b9461}a#announcements .alert{color:#225A40}

view raw invalid_css.css hosted with ❤ by GitHub

Then I noticed that the clean-css plugin provides an option to keepSpecialComments when it does the minification. I tired using that but it still did not work as special comments have to start with an exclamation mark: https://github.com/jakubpawlowicz/clean-css#how-to-preserve-a-comment-block

Adding an exclamation mark before the comment was not going to work as that would be invalid syntax for the SharePoint theming engine.

So my final solution was to convert the ReplaceColor comment to a special comment before processing it through the minifier, then letting the minifier do it's thing by minifying the css file but preserving the special comments, and then after the minification, again converting the special comment to a regular comment suitable for the SharePoint theming engine:

	var cleanCSS = require('gulp-clean-css');
	var replace = require('gulp-replace');
	var rename = require('gulp-rename');
	gulp.task('minify-css', function () {
	gulp.src("./Styles/**/*.css")
	.pipe(replace("/* [", "/*! [")) //convert all SP Replace comments to special comments
	.pipe(cleanCSS({ keepSpecialComments: "*" })) //Preserve all special comments
	.pipe(replace("/*! [", "/* [")) //convert the special comments back to SP Replace comments
	.pipe(rename({
	suffix: '.min'
	}))
	.pipe(gulp.dest("./Output/"));
	});

view raw minify_css.js hosted with ❤ by GitHub

Which then gave me the minified CSS along with the required comments preserved:

.myClass p{/* [ReplaceColor(themeColor:"ContentAccent1")] */background-color:#4b9461}a#announcements .alert{/* [ReplaceColor(themeColor:"ContentAccent2")] */color:#225A40}

view raw valid_minified_css.css hosted with ❤ by GitHub

Thanks for reading!