Practical WordPress Development

What Is the Assets Directory?

Last week, I wrote a short post asking What Is the Vendor Directory? which yielded a number of great responses, but it also resulted in a number of different questions, all of which were related, but none of which could be covered in that specific post.

For example, the article asked?

  • When do I know when to use a lib directory versus a vendor directory?
  • Should the vendor directory sit in the root of the project or should it exist in the root of, say, the JavaScript directory?
  • What about an assets directory?
  • Can lib and vendor co-exist?

And though some of these were answered in the comments and some of these answers can be found elsewhere, it did result in another question about the assets directory.

The Assets Directory

Regardless of what package manager you use or how you opt to organize your files, you’re likely familiar with having an assets directory. How you opt to use this directory is likely different than how someone else uses it, though.

An assets Directory

In other words, vendor and lib usually have slightly stricter guidelines or are generally used in the same way than something like assets.

I mean, to some degree, couldn’t we make a case that everything we include in our project – CSS, JavaScript, custom PHP libraries, images, fonts, and so on – are all assets?

And if that’s the case, then how do we come up with any type of rule of thumb to follow when we want to use assets especially in conjunction with vendor and lib?

Assets Defined

Before looking at a way to actually organize our assets, I think it’s worth trying to come up with a working definition of what a project asset actually is. In our case, we’re going to be talking about WordPress-specific projects (so this will vary if you’re working in another environment).

First, the official definition of asset is:

a useful or valuable thing, person, or quality.

So using this as a guideline for our work can help. As previously mentioned, CSS, JavaScript, images, fonts, and so on can all be considered assets. Therefore, would it not make sense to have a top-level assets directory into which all of the above would live?

Alternatively, couldn’t a case be made that a given library has its own set of assets? For example, think of a front-end framework that includes glyphs, fonts, images, and CSS. Would an assets subdirectory make since under a lib directory?

I think a case can be made for that, as well.

My Perspective

Given the previous discussion on vendor and lib, I tend to approach assets in the following way:

  • I’ll create a top-level directory in the root of my project and call it `assets`
  • Within that particular directory, I’ll have `css`, `js`, `img`, `fonts`, and more as seen in the image above.
  • Within each of those directories, I may have something like `scss`, `dev`, and so on to represent my unminified, development-based files.

When I’m using a third-party library, then it depends. Say, for example, I’m using a third-party JavaScript library. In that case:

  • I’ll have my `js` directory then I’ll have a `lib` subdirectory
  • In the `lib` subdirectory, I’ll include any third-party dependency, say, `acme` and then I leave it intact in whatever way the author built it

Sure, this may result within a nested assets directory, but the point is to keep the packages as organized, as cohesive, and as self-contained as possible. I don’t want my files mixing with other files.

Secondly, if I write my own library then I will treat it the same way as another developer would and organize the files as such as then drop it in its respective directory.

And finally, since vendor tends to be something included as a dependency via a package manage, I also treat it like a black box – however it’s organized is how it stays.

Organizing Your Assets

Ultimately, I think for your own work, having a top-level assets directory in the root of the project makes sense, and then leaving the organizing of lib and vendor intact is the easiest way to maintain the code based on how your code and other third-party code is written.

But I’m also curious how the rest of you opt to approach this. So, as with the vendor directory conversation, feel free to share your thoughts in the comments.


  1. Alain Schlesser

    Hey Tom,

    Love these articles, as it is very interesting to see the different ways of how to organize and interpret code structure.

    For my code, I always consider that the assets directory is an abbreviation for ‘static assets’.

    As I already mentioned in your ‘vendor’ post, my top-level folders are separated based on their functional requirements, as far as version control and dependency management is concerned.

    My assets folder contains the “source” versions of all the static assets that are specific to that project and need to go into the git repository.

    I say “source” versions, because most of these will be compiled and/or optimized by my build system.

    When I include a third-party JS library, it goes into vendor|node_modules|bower_components and I don’t want to have it in my git repo. The build system might however pull the JS files out of there and concatenate and optimize them together with my assets/js files. But this is purely at build time, it has nothing to do with the source in git.

    Bower is especially useful in this regard, as it contains a list of required front-end files that are needed at run-time inside its package description. This list is automatically processed by my build system to optimize things like JS files.

    • Tom

      For my code, I always consider that the assets directory is an abbreviation for ‘static assets’.

      Yeah – I think that’s a pretty good way to consider it, too.

      But this is purely at build time, it has nothing to do with the source in git.

      So when you do a local build, what happens then? Do you have those files under gitignore or do you do a build and deploy and just not worry about checking things in after a build?

      • Alain Schlesser

        My git repo only contains the source files. For everything but the most basic plugins, this cannot be executed/used as is.

        Everything that can either be downloaded through a package manager or built automatically by the build system is in .gitignore (that’s what the top-level folder structure is for, so that the .gitignore has a very simple structure).

        Depending on what the project is about, the built files will either go in a separate directory (app, build, …) or have different extensions (*.min.js).

        The goal is to have a structure that can be automatically fetched, built, tested and deployed through a CI system.

        • Tom

          The goal is to have a structure that can be automatically fetched, built, tested and deployed through a CI system.

          Makes sense – generally what I was expecting to hear, but I’d rather ask questions to hear how other people are doing this kind of stuff rather than assume and then point myself (and/or others) in the wrong direction :).

Leave a Reply

© 2020 Tom McFarlin

Theme by Anders NorenUp ↑