How I Organize My Files When Developing WordPress Themes

I recently shared how I organize my files when developing WordPress plugins, but since I also work with themes and have recently been building two applications using WordPress, I thought I’d also share my thoughts on organizing WordPress theme files.

For what it’s worth, I think that some developers – especially beginners – often try to make the plugin model fit the theme model or vice versa, and although both types of projects are aimed specifically at WordPress, they require different approaches.

Simply put, theme file organization differs from plugin file organization. With that said, here’s how I organize my files when developing WordPress themes.

A Word About WordPress, A Note About CodeKit

Before going too far into this, I highly recommend reading the Codex articles on Theme Development especially on Template Files. They define the foundation off of which all themes should be built.

Secondly, I’ve mentioned that I use CodeKit for all of my WordPress development. Because I’m such a fan of this application and the benefits that it provides, some of my organization is based strictly around this application.

CodeKit

To that end, I’ll give a high-level overview of how to organize files without CodeKit and then cover how I actually organize my files when using CodeKit.

The Foundation of WordPress Theme Files

Prior to using CodeKit, I organized my files using the following schema. The truth is, I still do this but just in a slightly more elaborate manner which I’ll discuss in a bit.

Basic Theme Directory

  • Files. All of the basic template files as mentioned in the Codex reside in the root directory. Because of post formats, I also include the various loops for each format, as well as the README, changelog, and any attribute credits in the root of the theme directory.
  • Directories. I normally have five directories;
    • css. Include any third-party stylesheets or any styles that are outside of the theme core. That is, they don’t necessarily belong in style.css.
    • js. I keep all JavaScript dependencies in this directory. I typically have two files – admin.js and theme.js – each of which are meant specifically for the dashboard and for the public-facing aspects of the theme.
    • lang. This is where I leave the PO and MO files for translators to localize the theme.
    • lib. These include third-party scripts, classes, or other PHP-based files that may add functionality to the theme; however, if I end up including, say, a jQuery plugin then that file would reside in a javascript/lib directory since it’s a JavaScript library.
    • img. This should be self-explanatory, but all images that I use throughout a theme are kept in this directory.
  • Templates. Generally speaking, I keep all of my custom templates in the root of the theme directory, but I’ve been keeping them in a templates subdirectory as of late. Eventually, this is coming to WordPress core and, for now, you can still take advantage of them using get_template_part.
Though there’s no single way to organize WordPress theme files, and I’m certainly not advocating that this is the way to organize files, I’ve found it to work well in most of my projects especially in maintaining them over time.

Using CodeKit To Organize WordPress Theme Files

When it comes to using CodeKit, I take the organization that I’ve provided above and I elaborate on it.

Two of the greatest strengths of CodeKit are its ability to covert LESS to CSS and bless said CSS file and lint and minify JavaScript. Because of that, I like to keep my development-based files in a subdirectory and have the minified and linted versions of the files kept in their respective directories.

Generally speaking, this requires two additional subdirectories to be added to the theme directory structure:

  • css. I introduce a less directory in the existing css directory. Here, I write all of my LESS-based CSS files. CodeKit will then output the minified and blessed versions of the files in the root of the css directory.
  • js. I also add a dev directory to the existing js directory out of which I write all of my JavaScript code. I use JSLint (as opposed to JSHint) in CodeKit and once the files are error free and minified, they are written out to the root of the js directory with the .min suffix.

Here’s an example of what one of my CodeKit-based WordPress Theme may look like:

CodeKit-Based Theme Development

The advantage of doing this is that it allows me to keep my directory structure clean, and it allows me to ship my work without the actual development files should I opt to do so.

Requests and File Sizes

If you manage your dependencies will within CodeKit then you can technically get away with importing a single CSS file and a single JavaScript source file thus decreasing the number of HTTP requests your theme makes when loading in the browser.

Of course, there’s always a tradeoff: you may have fewer HTTP requests but the files may be significantly larger depending on how much code it’s loading. This is a call that you have to make when shipping the final version of your theme.

I’ve shared before that I think organization is key in building and maintaing both themes and plugins so I’m always curious to hear how others do it. If you’ve got other strategies you employ or critiques on the above organization, let me know.

I’m always looking to optimize this stuff.

6 Replies to “How I Organize My Files When Developing WordPress Themes”

  1. Do you still think it’s beneficial to use CodeKit for theme development if you’re not developing using Sass or LESS?

    Also, in regards to organising template files, even with them in a templates directory and using get_template_part, wouldn’t you need the same number of files in the core of the theme?

    1. This depends, but I’d say probably not. I enjoy using CodeKit because it handles both LESS, JSLint, and image optimization.

      If you’re only worried about one of those, then you can use another external tool to take care of it.

      And for organizing template parts, you’d still need the same number of files, but it keeps the root a bit more organized to have them in a subdirectory, IMHO.

  2. re: “Of course, there’s always a tradeoff: you may have fewer HTTP requests but the files may be significantly larger depending on how much code it’s loading.”

    My understanding is, typically requests are slower than file size. Mind you, I’m sure there are limits to that. But as a general rule it’s better to have, say, one larger file, instead of two+ small ones that are only enqueued as necessary.

    1. My understanding is, typically requests are slower than file size. Mind you, I’m sure there are limits to that. But as a general rule it’s better to have, say, one larger file, instead of two+ small ones that are only enqueued as necessary.

      There are other factors that contribute into this (minification, compression, gzipping, etc.) so it depends on how far you really go with it.

      Plus, requests are sequential so the site blocks until one request has finished and it moves on to the next.

  3. p.s. I prefer to put the above “stuff” under a folder called assets and then that gets split further into src and dist, and then each of those has css, js, etc.

    This way I know that’s the more active (?) stuff outside the core theme / plugin “code”. Anything that gets pre-processed / post-processed, etc. via Grunt, Bower, Composer, etc. ends up under assets.

    On one hand it might feel like a slightly heavy-handed personal preference, but I believe it’s just more logical, structured and easier to hand off to someone else.

    FWIW, this approach mainly grew out of having to pick up the (sprawling) code of others – often mid-project – and too often thinking “WTF is going on here? Is there any method of to this messy madness? Why is the CSS structured one way? But the js another? WTF?!!” :)

    1. I prefer to put the above “stuff” under a folder called assets and then that gets split further into src and dist, and then each of those has css, js, etc.

      This is more or less the way the industry does it and it’s smart, imho. It’s great for development and it’s great for production.

      Some things have changed sine I originally wrote this post, but not enough to warrant a brand new post. The point still remains: Pick a structure and go with what works.

      This way I know that’s the more active (?) stuff outside the core theme / plugin “code”. Anything that gets pre-processed / post-processed, etc. via Grunt, Bower, Composer, etc. ends up under assets.

      :thumbsup: Spot on, man.

      On one hand it might feel like a slightly heavy-handed personal preference, but I believe it’s just more logical, structured and easier to hand off to someone else.

      I don’t think it’s heavy handed. It makes maintenance easier, too IMHO.

      FWIW, this approach mainly grew out of having to pick up the (sprawling) code of others – often mid-project – and too often thinking “WTF is going on here? Is there any method of to this messy madness? Why is the CSS structured one way? But the js another? WTF?!!” :)

      Yeah – work enough with disorganized code and you begin to appreciate standards :).

Leave a Reply

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