What Is the Vendor Directory?

With the rise of package managers, build tools, and other similar software being brought to WordPress, we’re seeing more advanced directory structures in both our themes and our plugins.

Some of these tools have been around a long time – at least in one form or another – as it relates to software development, but it’s still relatively new with respect to WordPress.

If you’re new to WordPress development or you’re new to some of the various tools we have at our disposal for working on these types of projects, then it’s easy to get overwhelmed with some of the organizational choices of said projects.

Relax: that’s normal. It’s a natural part of the learning curve.

Though there’s a lot that can be talked about with respect to all of this, I thought it might be worth tackling just one aspect of it in this particular article.

The Vendor Directory?

When it comes to working on projects, most of them are going to include some type of third-party libraries.

The vendor Directory

Perhaps it’ll be a CSS framework, maybe it will be a JavaScript library, or maybe it will be something else completely. Whatever the case, I think it’s safe to say that we’re all used to seeing the word library tossed around in programming vernacular.

To that end, we’re likely used to seeing a lib directory in our projects – maybe we’ve created it, maybe someone else has. So before we talk about a vendor directory, it might be worth clarifying what a lib directory contains and then how a vendor directory differs.

Library

Perhaps the best way to define the lib directory is understanding what a library is and how it relates to the overall project:

Normally, a library refers to third party-code.

Simple, right? As mentioned, this may be something that’s basic as CSS or something as complex as an involved PHP library that works with the file system.

Whatever the case, we often think of a library as a black box – we import it into our project and use its APIs or its features as needed in order to help make our work.

Ultimately, we’re trying to leverage the work of someone else who’s provided a specialized solution for a problem that we’re currently facing.

Vendor

This is where it gets a little bit more confusing (because why would anything in programming need to be as clear as possible?).

The vendor directory might be treated the same way as a lib directory. That is, you may end up seeing it used in place of lib, but that’s not the only way it may be used.

One way to think of the vendor directory is as a more generic form of lib.

Whereas a library is usually third-party code, vendor might be third-party assets. It may not be CSS, JavaScript, or so on. Instead, it might be images, fonts, and other resources that you use that is not explicitly code.

There are also other ways in which the directory may be used, as well.

vendor is also used as a way to track code that’s supplied by the vendor – or the author – of the framework in question.

When it comes to WordPress, we won’t really see this since we’re building things on top of WordPress.

If, however, you’re working in the context of another framework and it includes a number of different assets and other tools that are made available to us, as the developers, then this code would rely in the vendor directory, too.

But This Raises More Questions

Though the above points seek to make it a little easier to understand how files are organized when working with web applications, each foundation, framework, or other device will have its own idiosyncrasies.

Although I’ve attempted to provide a basic rule of thumb for each that tends to be the most common case, it’s not a hard and fast rule. It’s more of a guideline than anything else.

Even still, this should help to clarify some of the organizational structures that we see throughout a code base when working with or writing a project.

But maybe not. Maybe it actually raises more questions:

  • 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?

All of these are normal questions and I think I’ll offer a follow-up post that includes more details (especially with respect to an assets directory and an inc or include directory).

Before I do that, though, I’m also curious to hear your take on lib and vendor as it relates to WordPress themes and plugins so don’t hesitate to share your use of the directories in the comments.

20 Replies to “What Is the Vendor Directory?”

  1. Hi,

    This subject is really hard to apprehend since WordPress does not use natively a dependency manager and doesn’t allow to natively use composer or npm etc.

    In CSS/JS I’ve been using something like this, vendor is for external files and libs are the private components used in several projects or custom object that can be reused. Like one View object from Backbone, the perfect example is the WP API backbone component. This will go to the vendor folder but if i need new methods I will use the lib folder to add them. Then my application will have an src folder with the project specific code.

    The assets directory is in my case the root of all css/js/images/font files and then the subdirectories src/vendor/lib in each one if needed.

    The compiler brunch.io is really good for creating websites and compiling ressources have a good folder structure.

    1. This subject is really hard to apprehend since WordPress does not use natively a dependency manager and doesn’t allow to natively use composer or npm etc.

      Core doesn’t, you’re right, but I’m seeing more and more advanced developers beginning to use these types of things hence the reason I brought it up.

      Even still, it’s clear that there’s on real standard to follow so the ultimate point really has more to do with, say, picking something that logically make sense given the organization of your project and going from there.

      This will go to the vendor folder but if i need new methods I will use the lib folder to add them. Then my application will have an src folder with the project specific code.

      Makes sense to me – I like it :). Thanks for sharing it.

      The compiler brunch.io is really good for creating websites and compiling ressources have a good folder structure.

      Ah, I’ll have to check it out – I think I remember seeing it some time ago, but I’ll have to revisit it and check it out especially now that I’m getting more and more into this type of stuff (along with other developers).

  2. Hi Tom,

    That’s an interesting debate, and one you’ll probably find a lot of diverging answers.

    I normally make a clear distinction between lib/ and vendor/ based on how they are treated in terms of version control.

    In the lib/ folder, I include library functionality that is not directly project-specific, but is nevertheless included in the git repository of that particular project, whereas my vendor/ folder contains library functionality that is NOT included in the git repository.

    So the vendor/ folder is normally populated through a package manager (composer usually) or through scripts. I assume that the vendor/ folder can be deleted at any point and simply rebuilt automatically without losing any data, while this is not true for the lib/ folder.

    I tend to use the lib/ folder less and less, though, as I’m better at keeping my own library functionality 100% reusable, so I also include my private git repositories with the library functionality via composer.

    When dealing with other package managers, you’ll also come across other folders, that are practically synonyms of the vendor folder (like node_modules for npm or bower_components for bower). Although I tried to consolidate these in the past (I like to keep everything neat and tidy), I now prefer to keep them as individual folders with the standard naming, as this avoids confusing new developers. When they see the name of such a folder, they immediately know where the contents come from and how to deal with them.

    All three of these examples should be left out of version control and are normally enumerated in the project’s .gitignore.

    I’d be interested in hearing how other people deal with these, and if they have another understanding of the lib/ folder in particular…

    Thanks for another great post!

    Alain

    1. I completely failed to mention how I deal with assets/.

      I use the vendor/ and the lib/ folder in my project’s root. The vendor/ folder normally contains complete packages, so each of these contains its own JS/CSS assets somewhere in a subfolder.

      I have an assets/ folder in my project, too, but this only cover project-specific assets, not the ones from the libraries.

      This assets/ folder is also included in the git repository, and in my case it contains everything that results in static files. They share a manifest file in the assets/ root which contains the handles and the filenames to each static resource. This manifest is generated automatically through gulp, and the filenames contain a hash of their contents, like for example assets/css/style-h4f2aa5f.css, which automates cache-busting. As soon as the generated content changes, the filenames will change, too.

      Sorry for replying to my own comment, just found it necessary to add my take on the assets/ folder.

      Alain

      1. These are great points, and I think for beginners it’s worth highlighting the various package managers:

        /vendor is a sign that Composer is likely in use, look for a composer.json file

        /node_modules indicates that NPM is in use, look for package.json

        /bower_components indicates that bower is in use, look for bower.json

        In the case where there is a /vendor directory but no composer.json file, only then would I assume one of the uses outlined in the article.

        1. These are great points, and I think for beginners it’s worth highlighting the various package managers:

          This is a good point especially since each deals with them differently.

          Thanks for outlining them here.

      2. I use the vendor/ and the lib/ folder in my project’s root. The vendor/ folder normally contains complete packages, so each of these contains its own JS/CSS assets somewhere in a subfolder.

        I’ve typically done something similar: So let’s say I have a JavaScript library I’m using.

        Then I have a top-level assets directory, then in that directory I have js and in that directory I have dev which is where my unminified files go (the minified files are in the js root).

        For libraries, I’ll then have js/lib/foo where foo is the name of the library in question. I do a similar thing with my CSS and other things, as well.

        assets may also include things like fonts, too.

        This assets/ folder is also included in the git repository, and in my case it contains everything that results in static files.

        Yep – bingo.

        Sorry for replying to my own comment, just found it necessary to add my take on the assets/ folder.

        No way – refine away :).

      3. That’s pretty much how I treat those as well.

        vendor/ for external sourced managed with a dependency manager or generic submodules and so forth.

        lib/ for source code that isn’t that generic, or is built on top of the vendors’ dependencies, or internal components for reusability.

        assets/ for media related to lib/ and the rest of the project.

    2. I normally make a clear distinction between lib/ and vendor/ based on how they are treated in terms of version control.

      Ah, now that’s an interesting idea. Haven’t thought about it that way before.

      So the vendor/ folder is normally populated through a package manager (composer usually) or through scripts. I assume that the vendor/ folder can be deleted at any point and simply rebuilt automatically without losing any data, while this is not true for the lib/ folder.

      Makes total sense since the lib directory includes actual dependencies.

      I’d be interested in hearing how other people deal with these, and if they have another understanding of the lib/ folder in particular…

      Same here! So far, the comments have been really good :).

    1. It’s a common convention to put files coming from various third party sources (the “vendors”) in a folder named that way.

      Oh definitely — but there’s also the challenge of dealing with code from vendors that can be included via any package manager and then libraries which serve as dependencies for your project (hence the need for distinction, IMHO).

  3. This is an interesting post, Tom.

    I follow a bit unconventional approach towards the architecture of WordPress themes. Let me explain a bit of it. Actually, after I wrote about one of my Gulp workflows last week, some people commented about the architectural pattern I follow.

    For me, everything except for the default template files in the root directory is an asset. So, I create an asset directory and put everything inside it. Some front-end related stuff E.g. node_modules, sass_cache etc. still stays in the root but never bugs me a lot, since everything related to the project at hand sits inside assets folder.

    Then inside assets folder, there are different folders based on their purpose. Let’s say there is a js folder. Inside js folder there are directories called vendor (for third party scripts), custom (for custom scripts I write) and in the root of js folder are built (minified, concatenated) files of js.

    You get the idea. It’s def. an interesting debate.

    1. Then inside assets folder, there are different folders based on their purpose. Let’s say there is a js folder. Inside js folder there are directories called vendor (for third party scripts), custom (for custom scripts I write) and in the root of js folder are built (minified, concatenated) files of js.

      Yep – I get the idea.

      Depending on how you manage your assets and your various libraries and other packages, it makes sense.

      I think that it ultimately comes down to what works best for you, your team, and your workflow, though I do think there’s a little bit more common approaches right now, we’ve yet to see anything standard emerge.

      1. I think standards architecture might not be a good thing.

        While it can help a lot but it’s like telling someone to use PhpStorm instead of Sublime — since that’s the standard practice and it helps you learn the core — which may not be perceived well.

        1. I think standards architecture might not be a good thing.

          Depending on the nature of what the standards apply to, I disagree. When it comes to coding standards, I absolutely think they are a good thing. When it comes to ways to organize a certain type of solution to a problem (like a design pattern), I absolutely think they are a good thing.

          When it comes to how to best organize your files, that’s more of a gray area for me.

          While it can help a lot but it’s like telling someone to use PhpStorm instead of Sublime — since that’s the standard practice and it helps you learn the core — which may not be perceived well.

          That’s a little bit different because that’s not so much of a standard as it is an enforcement of a particular piece of software on a person to get their work done rather than a convention for how to best create maintainable code.

  4. Hello Tom,

    As you can see, there are different approaches. Here is how I use the file organization as it relates to assets.

    I view assets as anything external, which includes vendor packages, css, Sass, javascript, images, and fonts. I then organize it as such:

    • assets
      . build
      . css
      . fonts
      . images
      . js
      . scss
      . vendor

    The css, scss, and js folders are individual, single-responsibility files which are then gathered into a single js and css file, minified, and then stored in the build folder.

    To me the “vendor” folder is a container to hold packages that I’ve installed through packagist.org or some other package manager. For PHP packages, I use Composer to pull each dependency into my application, which gets stored into the assets/vendor folder. If I need a client-side package, then I use Bower. By doing so, I’ve now created a local repository from which I can utilize those packages directly within my application.

    Alain mentioned this own libraries. I tend to package up modules and then submit them to Packagist, thereby allowing me (and others) to pull what is needed into the next project’s application.

    Some may ask what a “package” is. We should be writing modular code. In doing so, we create our own libraries of modules, which can then be packaged up for reuse, over and over again from project-to-project. These modules or “packages” can then be pulled into a project without modification and then wired up to work for whatever you are doing. These are packages or modules.

    Again this is how I organize my files. The key is to set an architecture that makes sense to you, one that keeps your modules and packages organized.

    Happy coding,

    Tonya

    1. The css, scss, and js folders are individual, single-responsibility files which are then gathered into a single js and css file, minified, and then stored in the build folder.

      I like this approach.

      Right now, I don’t concatenate a lot of my JavaScript files – I use the WordPress API to conditionally enqueue them based on the which page is loaded (specifically in the dashboard, that is).

      As far as the front-end is concerned, it’s a little bit different. I’d prefer to have a single file for CSS and a single file for JavaScript loaded on the front-end if for no other reason than fewer requests.

      Again this is how I organize my files. The key is to set an architecture that makes sense to you, one that keeps your modules and packages organized.

      Agreed – it’s less about being legalistic about it and more about having something that works, that’s maintainable, and that can be used from project to project.

      1. One of the great things about using package managers is that they provide one piece of the puzzle to construct a real build automation system, using a task runner like gulp or grunt.

        With such a system, you can create a build pipeline for each of type of assets, depending on how they should be optimized.

        In my case, my JS files all get concatenated and optimized through browserify into two final files: frontend.js and backend.js (well, actually the filename contains a hash, too).

        So, on the frontend, I only load the one frontend.js file, while I load both on the backend.

        Same goes for things like SVG symbols that get compiled into a single spritesheet, or sass files that get optimized into a single style.css.

        You can achieve all of this without package managers, too, but files like composer.json, package.json or bower.json actually contain some vital information to pass on to the build system, like what files are needed on the production machine vs dev dependencies only. So you don’t need to do anything by hand, the people managing the package can actually tell your build system how to deal with the files.

Leave a Reply

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