Software, Development, and WordPress

The State of the WordPress Plugin Boilerplate

One of the projects that I love working on the most is the WordPress Plugin Boilerplate.

I dig it because it’s been a resource that has helped other people, and there are a number of other contributors that are constantly working to make it even better.

Earlier this year, I had plans to begin releasing more frequent updates, but – as with the nature of employment and side projects that are done for free – the updates didn’t happen as fast as I would like.

Additionally, it was becoming clear to me that the Boilerplate was headed in a direction that was going to be more intimidating for beginners, harder to grasp for those migrating their plugins to that format, and that it was not using some of the best principles in place.

So after talking with a number of notable developers, I’ve opted to delay the release of `2.7.0` until we have something significantly better than what’s in place.

In fact, it’s going to be a near total rewrite.

A Rewrite of the WordPress Plugin Boilerplate?

In a sense, yes.

This doesn’t mean that we’re completely starting from scratch. Instead, we’re talking a lot of the best ideas that are already there and building them in.

Then, we’re taking some of the ideas that are more complex from the average plugin development standpoint, pulling them out, and then making notes to provide documentation on a forthcoming web page.

Ultimately, this should result in a significantly more useful, easy-to-understand, and easier-to-implement Boilerplate for those who are getting started in plugin development.

Who is This “We” You’re Talking About?

A little while ago, I put a call out in the WordPress Plugin Developer mailing list for those who were interested to join in a back channel to hash out ideas about the direction of where the project should go.

The WordPress Plugin Boilerplate Backchannel

The WordPress Plugin Boilerplate Backchannel (Say it Three Times Fast)

So far, this has been a really good place for a handful of us to chat and work through some of the initial issues that we have with the Boilerplate, and begin planning the future state of where we’re headed.

Where Are You Headed?

In short, we’re looking to include the following (in no particular order):

  • An official website for the WordPress Plugin Boilerplate complete with code examples, documentation, and more.
  • A rewrite of the core Boilerplate
  • Better object-oriented practices
  • Cleaner code, clearer DocBlocks, and generally easier ways for developers to pick up the Boilerplate and run with it
  • Official documentation for users and developers alike
  • …and more

Obviously, there’s a lot to hash out and we’re really excited about it.

If you’re someone who uses the project (regardless of if you like it or not), please feel free to share your thoughts in the comments and we’ll be sure to take these into consideration, as well!

On to `2.7.0`!


  1. Nick Haskins

    “Then, we’re taking some of the ideas that are more complex from the average plugin development standpoint, pulling them out… ”

    As someone who uses your boilerplate daily, I’m a bit disappointed in the notion of code being removed. Why not start a new one for beginners and leave this one for advanced developers?

    Beginners do not typically write with an object oriented approach so to me it makes sense to start a separate, newbie version.

    Just my 2 cents.

    • Tom

      This is great feedback, Nick and I appreciate it. I’m going to be sure to take this back to the team.

      Let me be clear: The idea of complexities that I’m talking about are introducing things like Gruntfiles or some other dependency manager. Those aren’t needed for beginners because they likely don’t use them (or they will confuse them), plus not everyone reads them.

      Secondly, advanced developers will be easily able to add those into the existing Boilerplate without problem.

      This is but one example, but hopefully it helps you rest assured we’re not going to be stripped away, you know, import core principles of a plugin. Just rejecting and removing suggestions from things that are “nice-to-haves” or that aren’t leveraged by the masses.

      I hope this make sense – don’t hesitate to continue this conversation, though. I’m all ears!

      • Gabe Shackle

        It wouldn’t be that hard as well to maintain forked versions that includes the Gruntfiles and/or Composer support and just have the core boilerplate as a submodule. I’ve been using my own local fork of the boilerplate that uses the grunt-init plugin similar to Eric Mann’s approach here:

        • Tom


          But forked versions are beyond the ability of many beginners which is why I trust that keeping it as lean and focused for the target audience is key. The rest of you geeks and brach your branches ;).

      • Nick Haskins

        Sweet! Ok thanks for clearing that up. Makes better sense now. And nice on Grunt, I started using Grunt about 2 months ago in everything I do now and just love it.

        • Tom

          Yeah – Grunt’s making major waves in the community right now. I’ve used it when committing to Core but still stick with CodeKit for many of my personal projects.

  2. Aaron Eaton

    What are your thoughts about possibly using Composer, especially for the autoloader? I know it adds a bit of complexity.

    I’ve been using it in my plugins and themes lately. Couldn’t be happier with how easy it is. Bringing in PHPUnit and other packages makes development a breeze.

    • Tom

      This is a perfect example of what falls in line with what I was talkoing to Nicknot because I don’t advocate for them personally, but for specifically the reasons that you mention — complexity.

      The ultimate goal of the Boilerplate is to provide a foundation for plugin developers to get started with best practices (which unit testing tows that line, obviously). Advanced developers should have no problem implementing that stuff.

      BUT! I do want to add that the team talking is talking about this kind of stuff. At the very least, we’re thinking of having an advanced area of the website that walks users through how to do certain tasks that are exactly like this so newer users can add neater, more organization type material without needing to remove it from the core.

      Ultimately, I don’t want people to have to remove something from the Boilerplate core — I’d rather they add things as they need it (if that makes sense).

      Fantastic questions, Aaron. Thanks so much.

  3. Josh Levinson

    Thanks for keeping it lean! I’ve used your boilerplate for all of my recent projects, and I’m glad to see it will be keeping its focus clear going forward.

    • Tom

      That’s great to hear – excited :) – and it’s exactly what we’re going for!

  4. Ajay

    I strongly support the keeping it lean initiative. I’m looking forward for the Official Documentation part as well. It would be good to have a small step guide for developers starting off with this.

    What’s the timeline you’re thinking on this?

    • Tom

      What’s the timeline you’re thinking on this?

      There’s no official timeline – we’re all working on this as fast as we can, but we want to make sure we’re doing it right, and we’re also doing it in our free (read: non-paid :) time, so we’re working on it as we can.

  5. Bowo

    Hi Tom,

    I fall in the “completely newb” category and was excited to discover the boilerplate just days ago as I’m just beginning to create a basic, site-specific plugin and figures the boilerplate to be a future trajectory to follow.

    Now that I read this and how the core will be newb-friendly yet extensible for advanced developers, I’m even more excited. Grunt is on my list of “to learn” as well, so this is perfect.

    Keep up the great work guys!!!


    • Tom

      Thanks for the support, Bowo – super stoked for this :).

  6. Andres Hermosilla

    I don’t know if you’ve checked out Laravel but a big part of its success is accessibility, easy of use all while remaining hugely robust. I would say the challenge is how do you make it easy for beginners and yet maintain its usefulness for advanced developers.

    I find for beginners “auto-magic” can be helpful – for example automatically hooked up actions and filters ie.

    • Tom

      I don’t know if you’ve checked out Laravel but a big part of its success is accessibility

      I’ve heard lots of good things about it, but haven’t actually used it in any projects.

      I would say the challenge is how do you make it easy for beginners and yet maintain its usefulness for advanced developers.


      I find for beginners “auto-magic” can be helpful – for example automatically hooked up actions and filters.

      I have mixed feelings about this – I am a fan of abstractions, but at some level I think that it can hinder programmers from learning more about what’s going on behind the scenes such that they end up using certain things as a crutch.

      I think that’s okay, at first, but I don’t want to create something that becomes a dependency, you know? People can use the boilerplate to start off, or it can be used as a teaching tool.

      Ideally, I’d love for it to be both, but there’s a balance to be struck which I’m still working to figure out.

  7. Tunbosun Ayinla

    Hi Tom,
    Is it still possible for me to join the back channel.

    • Tom

      Hey Tunbosun — right now, I’ve closed off participation since so much time has passed; however, I’ll likely open it up again in the future when we begin a second round of major changes coming down the pipeline.

  8. Chris

    Great news on the rewrite, the plans sound excellent.

    As every plugin could have vastly different requirements is there scope for creating a customised builder of some kind? Whether that’s done through the website (in the same way you can download customised jQuery UI builds) or through a set of Grunt parameters doesn’t really matter, but having a few questions up-front to configure the boilerplate might be useful. For example:

    – Do you need admin pages?
    – Do you need a settings page?
    – Do you need public pages?
    – Do you need widgets?
    – Do you need shortcodes?

    I had an idea to make a plugin that would offer these kind of questions in a simple UI (along with the more basic details such as plugin name etc) which would then produce a customised boilerplate. But if there’s going to be a rewrite perhaps I can offer my help with that?

    • Mauro

      I think that is a fantastic idea! I am totally newbie and this would help people in my situation a lot.

      Looking forward here!


    • Tom

      Everything that you’ve mentioned here is going into the documentation for the new Boilerplate – it’s just going to take us time to get the core written and the new site built :).

      But if there’s going to be a rewrite perhaps I can offer my help with that?

      Absolutely. Shoot me an email and let’s talk :).

  9. John Armstrong

    We love the plugin and built a generic tutorial framework around it. Would that be something you might want to put into the base? It allows the plugin author to create little pop-up box trails of instructions that are initiated per user and go away when the user is finished.

    Its a nice to have but one that plugin users really appreciate.

    Let me know if you are and I can try to formalize it a bit.

  10. Vasik

    I’m a beginner with OOP development in general (I have quite some experiences with developing plugins using procedural code), and while I find the boilerplate very useful, I would really need some real life examples on how to use it. What I’m struggling is ie.:

    if creating a custom post type, what file should it be in?
    where are the new classes initialized?

    Having some kind real life examples would help A LOT, so I’m happy to see you working on this. Are there any updates? Thanks

Leave a Reply

© 2020 Tom McFarlin

Theme by Anders NorenUp ↑