Secrets of cssSweet 2.0

Jun 22, 2015

Secrets of cssSweet 2.0

What is it?

cssSweet is a "suite" of tools that can be installed in your MODX CMS website to help integrate, manage, and deliver front-end assets—with top-notch performance.

The first release, in 2013, was announced here, but from this article, you might glean some secret-sauce with regards to why and how to use it.

Why bother? I already use {insert workflow here}

There are countless workflows one can adopt that do essentially the same thing as cssSweet, but none (that I know of) are integrated into the MODX Manager.

This isn't much of a problem when you're working alone, on a static prototype—most devs probably prefer to work locally in their code editor.

When it comes time, however, to integrate a prototype into MODX, things happen. A style needs to be tweaked over here, a line added over there. For every little change, do we really have to edit locally, compile, and upload to the server before we can preview?

This is where cssSweet can come in handy, at least in my experience. You can create static Chunks that reference the assets developed during prototyping, then add a new Chunk for overrides. Setup cssSweet to include them all, and then whenever you save your override Chunk, it's all compiled down to a single file. That's the file you call into your templates, to view your changes immediately.

Screenshot 2015-06-22 12.28.00

If you want to edit the component SCSS files, you can do that in MODX as well. cssSweet 2.0 parses and compiles SCSS, so you can faithfully replicate your local workflow right inside MODX—regardless of the server (and whether it has SCSS or Node.js installed, for example).


I'm not talking about CSS inheritance here, but rather, when one inherits a site developed by others. There are (at least) 2 possible scenarios, and cssSweet will be your friend in both.

The Turtle

In this scenario, the previous developer didn't focus on performance at all or didn't have the toolset to do so. As a result, a multitude of requests are made for asset files, slowing down page load. This is OFTEN the case when importing a WP site or theme. Luckily, this scenario is trivial to fix with cssSweet:

  1. Create a static Chunk referencing each asset.
  2. Add the names of these Chunks to the appropriate cssSweet plugin property in the same order that they are called in the html.
  3. Optionally use a MODX comment tag to remove the link (and/or script) tags from the rendered page (see screenshot above.)
  4. Include the cssSweet output file instead.

I highly recommend also enabling gzip compression for CSS/JS files on the server, if you can. By taking only the steps described here, I've seen over 250kb of CSS—including huge framework and all—crunched down to a 30kb response!

The Hare

In this case the previous developer was committed to performance optimization, but maybe not as committed to documentation or team play. It's possible that dependencies—mixins, libraries, or component SCSS files—aren't available. Or, for some other reason, the original workflow can't be reproduced.

With cssSweet installed, you can combine your overrides/additions with the previous, complied stylesheet without adding another request to the front-end.

Cause You Like It?

All that aside, the reason I made cssSweet wasn't necessarily to handle the above cases, but because I enjoy working in the MODX Manager!

At one point, it was to my own folly, because early on in my MODX usage, I wrote stylesheets in the Manager using a Resource with CSS as its content type. This came to the attention of Jason Coward, Chief Architect of the MODX platform, who promptly grilled me on it. "Why do you do that?"

I responded with something ignorant, to the tune of, "Because I like it?"

That's when Jason explained to me that the browser will never cache the MODX-generated CSS response, because by default PHP sends no-cache headers. "MODX wasn't meant to deliver CSS in a Resource," he informed me. I couldn't help myself: "Then why is text/css available as a content type by default?"

Jason responded, the next day, by releasing microcache, which allows the setting of caching headers depending on content type or other variables defined in the plugin's properties. But I took Jason's words to heart: maybe the Resource wasn't the best place in MODX to handle CSS—and cssSweet was conceived.

The output file that cssSweet generates is a static CSS file, handled by the web server like any other static asset. With proper server configuration, and optionally a CDN, cssSweet helps you get the maximum possible performance in delivering your CSS.

To this day, my opinion is that there's more than one "right" way to do anything, and building a site in MODX is no exception. cssSweet may or may not be right for you, but personally I enjoy using it—the immediate preview after saving a Chunk, the Ace code editor for nice CSS syntax highlighting, and the comfort of knowing the front-end will meet Google's PageSpeed recommendations—these all give me the warm fuzzies when I use cssSweet. Which, one might argue, is the best reason to use any tool, right? Just look at Slack—they've made a multi-billion-dollar business out of giving people warm fuzzies :P

Other Features and Goodies

For an overview of other features and goodies in cssSweet, check out the readme file in the cssSweet github repo, which is auto-generated into the doc-site here: Issues and PRs are, of course, welcome.

Vive la MODX!