Practical WordPress Development

Source and Distribution Directories in WordPress Development

When organizing assets in a project, it’s common to see source and distribution directories. Sometimes these are organized a little different, but they generally serve the same purpose.

Overtime, I’ve moved from one form of organization to another. And I’ve found it to be easier to handle during deployment and maintenance of a project after release.

So here’s a rundown of how I used to organize my files and how I’m currently doing so now.

Source and Distribution (And Variations)

As with anything, none of this is a statement on why mine method is the best. It’s just what I’ve found to be easier to manage.

If you dig it, great. If not, that’s cool, too. In fact, I’m even interested in how you manage your files – I’m always open to changing mine up.

Old School

JavaScript Development

The way that I previous handled assets – that is, CSS and JavaScript, was like this:

  • I’d have a top level `assets` directory
  • Within that directory, there would then be a `js` directory and a `css` directory

For JavaScript:

  • The unminified JavaScript files would live in a subdirectory of the `js` directory called `dev`.
  • The minified versions of the JavaScript files then reside in the root of `js` with a `.min.js` suffix to the file.

For the stylesheets:

  • The Sass files reside in a `sass` directory which is a subdirectory of `css`.
  • The compiled version of the files would then live in the root of `css`

This works out okay if you understand the rationale behind it, but if you’re someone who’s just jumping into the project I think that it requires a little bit more of a learning curve.

No, it’s nothing terribly hard, but I think there’s room for improvement. To that end, I’ve started adopted what others have admittedly been doing for sometime now.

New School-ish

I still maintain an assets directory as I believe that generally keeps the project’s dependencies easily identifiable. But the way in which I organize the JavaScript and CSS is different.

JavaScript Source Directory

For JavaScript:

  • I still maintain `js` directory, but it has two subdirectories: `src` and `dist`.
  • These names should be clear enough, but `src` are the unminified, raw JavaScript files.
  • `dist` includes the files for deployment. These are the minified, processed JavaScript files.

For CSS:

  • I still maintain a `css` directory, but it has a `src` subdirectory and a `dist` subdirectory.
  • `src` contains the pre-processed Sass files
  • `dist` includes compiled CSS files

There’s obvious consistency between this type of organization with each language. Furthermore, I’ve found that it makes it easier to more quickly hop in and begin contributing to a project.

It’s clearer, it’s less of a learning curve, it’s more inline with what people have been doing for a while, and it’s easier to script for a build process and for deployments.


No, this doesn’t cover build processes or tooling around that. That’s reserved for another course.

Anyway, as I mentioned earlier in the post, I’m also interested in how you handle the organization of your files. This is especially true as it relates to scripting your build process and deploying the project.

So that’s where I am now.

Just as this has changed over time, maybe it will change in the future. Maybe not. If does, I’ll likely share it here. I tend to do that with everything else, right?


  1. Javier Villanueva

    I used to do something similar to this but then realised that there were too many assets coming from plugins that I had no control over, so minifying theme-related assets didn’t make much of an impact at least performance wise.

    I just keep everything unminified and separated and handle optimisation with a plugin, that way I make sure that all (sometimes not all but most) assets are optimised. It didn’t make much sense for me to have 4-5 minified scripts if I was going to have a plugin enqueuing 5 more un-optimised scripts.

    • Anton Zaroutski

      Javier, what you said sounds familiar. However, is this the approach that is common? I came to similar conclusions about plugin assets too however would like to know about other ways to manage and minify/compile assets including the ones coming from plugins.

    • Tom

      I used to do something similar to this but then realised that there were too many assets coming from plugins

      This is true — depending on your setup and/or the type of solutions you’re building, this is something that can become really tough to deal with.

      What I’ve laid out won’t necessarily work for everyone or even many situations, but if you have complete control over a solution that you are working on, then I think it goes a long way.

      I just keep everything unminified and separated and handle optimisation with a plugin, that way I make sure that all (sometimes not all but most) assets are optimised.

      This makes sense to me. You optimize and improve where you can. If optimization ends up breaking things or causing more problems, then you’ve basically over-optimized and that obviously ends up with less than stellar results.

      • Javier Villanueva

        Yes it’s still not ideal I think because you rely on an extra layer of processing to minify your assets and I’m not sure how big of an impact that’d make but it’s worked fine so far at least for my use cases.

        • Rich Tabor

          I use Grunt to minify and compile JS resources upon build – though I still include the separate assets in the directory and when the wp-config WP_DEBUG mode is turned on, the theme loads the original assets.

          • Tom

            Yep – this is another good strategy.

    • Toby

      By doing it this way you’re leaving optimisation at HTTP level. It makes way more sense to package up your application in an optimised state.

      For my own projects I make sure that my build script includes plugins assets and they are not enqueued by the plugin themselves. So I always only ever load one css/js file.

Leave a Reply

© 2020 Tom McFarlin

Theme by Anders NorenUp ↑