Software Engineering in WordPress and Musings on the Deep Life

Debugging Minified Files in WordPress

As much as I’m a proponent of concatenating and minifying dependencies, it’s not without challenges. Sure, this is includes both stylesheets and JavaScript, but I’m specifically talking about debugging minified files in WordPress.

Debugging Minified Files in WordPress

A minified bug. Get it?

It’s one thing to have your JavaScript files separated and organized in your Development. But when it’s time to deploy to Production, you should be aiming for a few minified files.

For example, say a client contacts you claiming something on their site isn’t working? You load up the site, you check the browser console and see there’s an error in the JavaScript.

Wait. You’ve minified all the files.

So what now?

Debugging Minified Files in WordPress

First, make sure Development is in sync with Production. Don’t edit files live on the server. This should go without saying. Then again, we’re still saying it and people are still doing it.

So there’s that.

Ideally, you need to be able to toggle a flag that will load the un-minified files making it easier to trace code.

The trouble with doing this in WordPress is that people may have their own ways of doing this. That is, other themes and plugins may have their own flags and you may end up causing erratic results when trying to debug those files.

Some ways that developers make it easy to toggle values are:

  • Passing a value in the query string
  • Retrieving a value defined in a plugin
  • Setting a value in an XML file
  • Reading a value from the database
  • …and many, many more.

The problem with doing this is that you never know what side effects you may trigger when toggling your flag. What if the theme or another plugin has opted to use the same flag? Wouldn’t this result in potentially causing something to happen that you didn’t expect?


So what’s the standard way to go about doing this?

If you look through the WordPress source code, you’ll find references to a constant: SCRIPT_DEBUG.

For example, wp-includes/default-constants.php has this code in Lines 69-79 (at the time of this post):

In short, the code is doing the following:

  1. Check to see if the `SCRIPT_DEBUG` constant has a definition
  2. If not, check to see if the `$GLOBALS` collection as `-src` defined in the `wp_version` value.
    1. If so, then set `$develop_src` to `true`
    2. Otherwise, set `$develop_src` to `false`
  3. Set the value of `SCRIPT_DEBUG`

But there’s another key to the code that’s left in the comments:

// Add define(‘SCRIPT_DEBUG’, true); to wp-config.php to enable loading of non-minified, non-concatenated scripts and stylesheets.

This means that we can go into wp-config.php and define the constant ourselves. And if we do that, then we can use code like the following:

Your code may vary from this particular implementation, but you get the point:

Check to see if a value common to WordPress has been set. If so, then load the un-minified files; otherwise, use the minified files.

Although this may avoid any collisions with other theme files, plugins, and so on, it will load anything that’s toggled via this flag. So, as mentioned earlier, use it with caution.



  1. Bob Senoff

    Very helpful Tom. Especially about building a toggle to load the unminified files.



  2. Kostas Nicolacopoulos

    Hi Tom, I understand the importance of minifying and concatenating the stylesheet and javascript files and I still do it too. However I’ve being thinking if it is best to deploy with the expanded and separate files and let the caching plugin do the minifying and concatenating.

    Obviously this won’t work on static sites but WordPress caching plugins can minify and concatenate the enqueued scripts and stylesheets anyway.

    Far too many times I have had a client make changes to the minified CSS file and then I had to track down the changes (git diff doesn’t help much when everything is in one line) and apply them to the SCSS files, so I won’t overwrite them on the next update.

    What do you think of this approach? Do you see any potential downfalls?

    • Tom

      What do you think of this approach? Do you see any potential downfalls?

      When it comes to deploying a project into production, I’m generally not a fan of sending the unminified, uncompressed files to the server.

      Oftentimes, people will claim the “bloat” argument here or something like that. Honestly, that’s not what bothers me — these are generally small files, you know?

      What gets me, though, is that someone who’s knows just enough to be dangerous – or knows someone like that – could end up poking around the source code to see how things are put together and then ultimately change the code so that it’s using the unminified versions.

      From there, they can then start updating the files on their own and ultimately changing the product against what was built to specification. But when something starts breaking, it’s up to you to go in and fix it when, in some sense, you’re having to fix something that you never built or never changed.

      It gets really messy at this point.

      So when it comes to handing code off in it’s final form, I usually make sure:

      • Only minified and/or compressed files are shared
      • There’s a clear understanding that any changes made upon delivery are outside of what was agreed on
      • The final project should be treated as ‘black box’ in terms of how it works and how they use it

      If they opt to go in and change things, that’s fine, but much like we have warranties with our physical products, once that’s done, the warranty is void.

    • James DiGioia

      Obviously this won’t work on static sites but WordPress caching plugins can minify and concatenate the enqueued scripts and stylesheets anyway.

      I don’t know what your experience has been, but I have not had a great time letting WordPress plugins do the minification/concatenation for me. Often, it breaks the JS, or combines them in weird ways. I’d much prefer to do the whole thing manually, though that process itself could be tedious.

      • Tom


        I don’t let WordPress plugins or other WordPress-specific tools do any type of minification or work for me. It’s never been a good experience. I use Grunt or CodeKit.

  3. Donna

    Tom, I think there’s an easier way – source maps. You inspired me to blog about it –


    • Tom

      Thanks Donna – this is a great alternative. Happy to share via Twitter earlier today, too! Hoping others pick up on this :).

Leave a Reply

This site uses Akismet to reduce spam. Learn how your comment data is processed.

© 2023 Tom McFarlin

Theme by Anders NorenUp ↑