Loading Minified Scripts in WordPress Plugins & Themes

The WP Crowd
Published: June 14, 2016

Similar to “tabs vs spaces” you’ll find WordPress developers who are passionate about their opinions on whether or not plugin and theme styles and scripts should be minified or not.

I personally think that developers should be doing everything possible to make their plugins have the lightest footprint possible on a users website.

Those who argue against it typically argue that minified scripts are difficult and tedious to troubleshoot. That’s absolutely true, but that’s not a reason to not use them in your theme or plugin. At least not if you are doing so responsibly. That’s what this article is about.

Why You Should Load Minifed CSS in Plugins and Themes

There are a few strong reasons to use minified scripts in your plugins and themes.

#1 It’s Considerate to your Users

This to me is the most important reason. When you are shipping code for others to use you want to be as considerate of their website as you can be. This goes along the lines of why you include inline documentation and easy to read function names.

Shipping the smallest files you can to your users tells them that you know their bandwidth and page speed is important to you.

#2 Caching and Minification Plugins

Many WordPress users use plugins or services which combine all their stylesheets together and/or their JavaScript files together. This is called concatenation.

Unfortunately, one downside to concatenation in WordPress is that sometimes scripts or stylesheets don’t concatenate well. This can happen for a wide variety or reasons, but I find overall that is rarely happens if the files have already been minified before concatenation.

If one of your users tries to concatenate their files and finds out that it’s YOUR plugin or theme which is making it difficult to do so, they won’t be so happy with you. This helps avoid that unpleasantness.

PRO TIP: Avoid JS errors with minification plugins by always starting your JS file with a semicolon (;), and prefix all your functions or variable, like “e” which gets used a lot with JS.

#3 Be a Bandwidth Environmentalist

Bandwidth Environmentalism is a THINGThis is really something many people don’t think of often enough. Bandwidth is a real resource. It uses processing power which uses electricity. The more bandwidth you use the more electricity you use the more natural resources we all use.

So maybe your un-minified script is 12kb and minified it’s just 6kb. That’s only 6kb, who cares!? Well, think of all the times that extra 6KB is going to be uploaded and downloaded every time your plugin or theme is loaded, updated, downloaded, etc. Even if you just have 100 users, that’s already 600KB extra per page visit. What if ONE of your users gets 1,000 visitors a day ? That’s not a huge amount of traffic for a WordPress site at all. But in extra KB that’s 6MB extra a day, times 356 days in a year that’s 2.13GB of extra bandwidth just from the visits to that one user’s site.

Bandwidth environmentalism matters in my opinion.

How to Avoid Making Troubleshooting Difficult

There are a lot of ways to minify files. There’s even online tools for it. But doing it responsibly requires using a pre-processor like Node, Gulp, or Grunt. This is because this is the best way to provide both the minified and un-minified versions of your scripts.

I hear you saying: “Wait a minute!? You just preached about bandwidth environmentalism and you’re including BOTH scripts? That’s waseful!”

It’s true that including both scripts affects the download/upload size of your plugin or theme, but what we’re going to do is make sure only one of those versions is loaded on the site. That is where the vast majority of the size difference really matters.

A common technique for including both the un-minified and minified version of a stylesheet, for example, is to have multiple smaller .scss files which are brought together into one “build” file, and then that file is minified and saved in the root of your theme as your main stylesheet.

That is the technique I use in my Beyond 2016 theme. You’ll notice in the assets folder there’s a “source” sub-folder and a “build” sub-folder. In “build” you’ll see main.css. That’s the unminified version. My Gulp script then minifies that and saves it to the root of my theme folder which is what the theme can then enqueue publicly.

I specifically do it this way so that I can ship the unminified version with the theme rather than including all the .scss files. If you wanted to ship all the .scss files with your theme that’s possible as long as you also include sourcemaps so that Dev Tools can point your users to where the CSS comes from originally. Read more on that from Google here.

Conditionally Loading the Unminified Scripts/Styles

Now that we have all the files included correctly in our theme, we need to provide the user with a way to troubleshoot with the unminified version.

Any WordPress developer worth their salt knows that to properly troubleshoot a WordPress site you need to enable WP_DEBUG. Since that is already common practice for troubleshooting with WordPress we might as well leverage that for triggering loading the unminified version of your scripts. I mean, afterall, the user enabled WP_DEBUG to do some debugging, we might as well assume that our scripts should be ready for them.

Here’s a rather simple function I use in my Beyond 2016 theme to do just that:

You can see it in action in my Beyond 2016 theme here: https://github.com/mathetos/beyond2016/blob/master/functions.php#L24-L34

Let’s break that down a bit.

  1. First we check whether WP_DEBUG is set to TRUE or not. If it is, we want to enqueue the un-minified version.
  2. A common problem with troubleshooting styles/scripts is caching, so while we’re in Debug mode, I’m going to cache-bust this style by adding a randomly generated version number. This ensures that every time the page is loaded the script is loaded afresh in the browser.
  3. If WP_Debug is set to FALSE then we’ll load the minified version. Notice that we add the “.min” in there. This helps make it explicit that this is a minified file, not just for humans, but also for minification plugins. They recognize that as indicating that the file is already minified, so they’ll not waste their resources minifying it further. (Thanks to AdvancedWP member Frank Goossens for that tip)
  4. Also notice that I use a Global for the version number here. We want to bust this cache as well, but only when the theme has a new version number. This ensure that when the user updates their theme they will see the new styles applied correctly to their site.

Naturally, you could add settings into your plugin or theme to minify/de-minify your scripts and styles instead of relying on WP_DEBUG, but I like avoiding adding more options and automating this action based on the users intent.

Put this all together and it’s relatively simple. Enjoy!


Chrome Dev Tools actually has a little tool that can un-minify CSS and JS for you. See the animation below. The one small caveat with this is that if you are providing support for your theme/plugin and refer to a line-number in the stylesheet, it might not be identical using this tool. Still, it’s awesome-sauce for those times when an un-minified version is not available.

Animation of the Chrome Dev Tools de-minify tool

Get the latest from The WP Crowd

Leave a Reply

8 Comments on "Loading Minified Scripts in WordPress Plugins & Themes"

Sort by:   newest | oldest
Robert Gillmer
Robert Gillmer

Thanks for the article and the ideas! I like the idea of enqueueing the full script/stylesheet if WP_DEBUG is on.

And that Chrome Dev Tools un-minification? Mystic sorcery!


Matt have you found good ways to inject JS/CSS only if a shortcode of your plugin is utilized on the page? Do you enqueue as part of add_shortcode? Do you enqueue normally and use the global $post and has_shortcode() ?

Matt Cromwell

Hey Roy. I forget which version of WordPress it is, but WordPress handles that correctly now. Basically, you should first register your JS/CSS with wp_register_script(‘js-name’, js/url, true), then inside your shortcode function use wp_enqueue_script(‘js-name’); WordPress handles the rest and makes sure your JS is only loaded if the shortcode is present.

Thanks for the question!


didn’t think about that! that is a smart way of going about it.


Matt have you found good ways to inject JS/CSS only if a shortcode of your plugin is utilized on the page? Do you enqueue as part of add_shortcode? Do you enqueue normally and use the global $post and has_shortcode() ?


[…] Loading Minified Scripts In WordPress Plugins & Themes […]


didn’t think about that! that is a smart way of going about it.