How to build WordPress block plugins

While I’ve long been a fan of block collections, most notably with CoBlocks, I do see immense value in block plugins for use within the WordPress Block Directory. Quickly searching for and installing a block right from within the Block Library is quite a clever and empowering experience — one that I believe will eventually become the de facto way to discover blocks. 

So let’s jump into what makes a Gutenberg block plugin different, and how they will change the landscape of WordPress editing as we know it today. 

What are Block Plugins? 

If you’ve built blocks before, you may be asking what’s the big deal about block plugins. For the most part, you can think of block plugins as one block, registered and compiled completely in JavaScript, that serves a singular function. These plugins exist solely to distribute a block — and nothing more… and these plugins are meant to be included within the Block Directory.

There are a few additional technical and experience guidelines, but nothing out of left field. Ah, and there is one big caveat — there is minimal PHP. I actually recently developed a block plugin for adding markdown comments within the editor — but not on the frontend — to gain some real world experience publishing block plugins to the Block Directory. 

Block Plugin Guidelines

There’s an exhaustive list of block plugin guidelines published on, but I wanted to call out a number of big hitters:

1. Blocks will work seamlessly without intrusive advertisements or upselling

This one is big, as I imagine folks building for the future of WordPress would want to figure out how to capitalize on their investment. I suspect this deters a lot of folks from submitting blocks. 

2. Block plugins are intended to be single purpose, separate, independent blocks, not bundles of blocks

There are a ton of block collections in the wild today, many of which I doubt will be broken apart and added to the Block Directory. This is an important guideline, but again — one that is probably deterring submissions.

3. Plugins that only extend or provide styles for other pre-existing blocks are currently not eligible

Registering block styles and block variations is a great way to enhance the editor, but those editor enhancements will not be a part of the Block Directory. Perhaps one day we’ll have an editor extensions directory. 🤔

4. Avoid plugin and block titles (like plugin brands) unrelated to the block itself, or that cannot be easily distinguished from core blocks

This means that “PluginCo Hero block” is discouraged, and should be named “Hero block” instead. This makes sense on the block side of things, but not for the plugin. Having an identity adds value to the block plugin – whereas naming the plugin “Hero block” is essentially white-labeling the plugin. No brand awareness.

5. Block Plugins must function by themselves without requiring any external dependencies such as another WordPress plugin or theme

Blocks should not require a theme, or another plugin, to function properly anyhow — not a big deal in my book.

6. Block Plugins must not include code that displays alerts, dashboard notifications, or similar obtrusive messages unrelated to the purpose of the block.

Feels like this guideline will get abused in its current wording. Just about any notification/alert generated by a plugin could be justified as related. I suspect the real intention behind this guideline is to prevent authors from recommending parent block collections (which certainly hold more potential profitability-wise from a business standpoint than a single block plugin). 

Adding to the WordPress Block Directory

Once you’ve created a block plugin, it’s relatively easy to get it added to the official WordPress Block Directory. At the core of this is the official Block Plugin Checker.

Here’s a top-level list of todos — but if you’re looking for a deep dive, I wrote all about building and publishing block plugins

1. Check your block with the official Block Plugin Checker to ensure it is a proper block plugin. 

2. Did it pass? If so, submit your block as a WordPress plugin to be hosted on the WordPress Plugins Directory.

3. Once approved, upload the plugin via the provided SVN repository like normal.

4. Head back to the Block Plugin Checker, add your plugin slug and click the “Add” button to add your new block plugin to the WordPress Block Directory. In a few minutes, your block will be installable on any WordPress site running Gutenberg. Awesome.

So why should I add my blocks?

Block plugins empower WordPress users to publish with blocks on demand. This new paradigm of block availability will absolutely change how we create and publish within WordPress. For example, if you are looking to add a progress bar block to your page, just search in the Block Library. You are instantly served with results from both your local directory of installed blocks (from plugins or collections you have activated) and from the Block Directory. Odds are, you will probably find a progress bar that fits the bill quite nicely. Click install and that block is ready to be added to the page.

In time I suspect this blocks on demand experience will eventually become the de facto method of finding and installing new blocks… but for now, there are not many blocks available. At the time of publishing this article, there are only about 140 blocks available, which honestly seems quite low to me. The Block Directory is relatively new — about a year old now — but I’m bummed we haven’t seen higher enthusiasm for block plugins or the Block Directory.

Anyhow, I am positive that block plugins will have an impactful role of empowering WordPress users in the future. For example, there’s a discussion on how patterns will likely side-load uninstalled blocks from the Block Directory when added to a page. That further empowers patterns to not be limited by core blocks, and more open to creative third-party solutions. In all, I firmly believe that patterns will be a huge part, if not the primary way that pages are created in Gutenberg. Block plugins will certainly amp up patterns, which will in turn amp up creativity. 

So have you added a block to the directory? Let me know in the comments — I’d love to check it out.


  1. Ian Markind Avatar

    So much potential with Gutenberg. I wonder how much this will advance over the next 5 years

    1. Deepak K Avatar

      That’s right. I believe, page builders like Elementor are going to be dead in the next 5 years.

  2. Matt Avatar

    It really is a shame that the block directory is stopping upsell opportunity. It’s the reason why developers will not adopt the block library toolset. Not being able to extend existing blocks is also restrictive. For me, until a clear path to commercialize block is made here, this area is not going to get the required attention.

    For most commercial sites it’s also going to remain a disabled feature so people don’t install 300 plugins that are single blocks. I can see that causing slow sites too.

    Not a well thought out feature.

Leave a Reply

Your email address will not be published. Required fields are marked *