Creating my first WordPress Block Directory plugin: Donation Form Block for Stripe

Did you know that WordPress has a subsection of the plugin directory called the “Block Directory” that allows you to install single-block plugins? It’s still very new and in order to have your plugin listed on the directory you have to adhere to some semi-strict requirements.

So I figured, let’s build something cool and learn along the way! 🛠 🧠 👍

For the last few weeks, I’ve spent time developing a block plugin for WordPress called Donation Form Block for Stripe by GiveWP. Personally, I think it’s really cool and is the best of its kind. As well, I learned a lot more about how to develop really cool Gutenberg-powered plugins.

Here’s a preview of what the block looks like in the block editor:

As you can see above, the block controls to the right of the editor change the block’s primary color, donation amounts, header image, and nearly all of the content.

There are also a lot more features to come from changing the appearance, more color options, accepting recurring donations, integrating with GiveWP, and more!

Try the block out for yourself

Give the block a try for yourself below! This is using Stripe’s test mode so no actual donations are processed.

To test use 4242 4242 4242 4242 as the test card number, any CVV, and any future expiration date. Enjoy the confetti cannon at the end!

Note: the block above has zero customization. This is the default block you see when you add it to your content. Nice boilerplate, eh?

I hope you like it!

Getting the block plugin launched was a fun learning experience. In the following I’ll do my best to describe the steps I went through so hopefully you can benefit when you develop your first block directory plugin.

First and foremost, the first step is learning how the block directory works and what the requirements are for being listed.

How to get listed in the WordPress Block Directory

There are specific requirements for your plugin to be listed on the block directory, mainly it has to be a single-block plugin and very light on PHP. Thus, GiveWP could never be listed because it includes 10+ blocks and a fair bit of PHP.

However, when a WP-admin user types “donation” or “fundraise” in the block search field we need to be present in the results and have a solid solution for folks.

Block Directory Requirements in a Nutshell

1. Stay on your Block! More specifically, your plugin can’t add anything outside the block editor such as wp-admin settings screens, dashboard widgets, etc.
2. Single Blocks Only! – You can’t bundle a grip of blocks into one plugin and expect to be listed on the block directory. I get why they do this… it’s to maintain a good UX.
3. Name your block after its purpose – The reason the block is title “Donation Block for Stripe” is because that’s exactly what it is and does. It’s not title “ZippyFundFund Block” or anything cutesy like that because that would violate this rule.
4. Include a block.json file – This is the preferred way to handle meta data for blocks nowadays. It took a little bit for me to wrap my head around it, but once I did it made sense and wasn’t hard to work with.
5. Don’t require other plugins or themes – The block you create shouldn’t require another plugin or theme to work. Pretty easy one here.
6. The block should work right away – This rule is to provide users a seamless experience when installing the block. They shouldn’t have to jump through hoops to get started. Examples of violating this rule are asking the user to immediately sign up for a service before being able to use the block, pay for an activation key, or any other gatekeeping.
7. Limit the PHP – It’s a bit hazy what the actual limit is, but I can tell you more than 1-2MBs of PHP and your plugin won’t pass the block validator.
8. Don’t advertise – Hey, I’m not going to lie – I’d love to add a little link or two back to GiveWP in the block, but that’s a no no. What you can do is provide links to documentation and let the user go on their own journey from there. This rule makes sense, though. Imagine a world where every third-party block advertised using a notice or alert. It would really discourage adoption.

Phew! That’s quite a few rules, eh? Thankfully WordPress’ has created a block validator that helps to ensure whatever you develop passes.

After learning the requirements for a block, you should have an idea that fits nicely within those boundaries. The next step is to begin developing the block.

Developing a Gutenberg block, the WordPress way

If you’re just getting started building in WordPress, developing in React is a little different than the traditional way you may be used to. The best way to start is by looking at what other reputable plugins are doing under the hood.

Here are a few good examples of nicely developed single-block plugins:

1. Blocks for Eventbrite
2. Block for Apple Maps
3. Blocks for GitHub (more on this one later)

Tip: when I reference code, I always do it on GitHub. This is because I want to be sure the plugin is being kept up-to-date and isn’t abandoned. You don’t want to reference old or packaged code.

The next step is getting started on the proper foundation.

Use WordPress’ “create block” package to get started… not an outdated boilerplate

When you Google “Gutenberg Plugin Boilerplate” you’ll see lots of results, but nearly all of them are no longer maintained or kept up-to-date.

Let me save you the time…

Use WordPress’ Create Block Package to get started off on the right foot.

Create Block is an officially supported tool for scaffolding WordPress plugins with blocks. It generates PHP, JS, CSS code, and everything you need to start the project. It integrates a modern build setup with no configuration.

– Gutenberg Team

I can’t tell you the amount of time I wasted reviewing and trying out different “boilerplates” that were out of date and no longer maintained. Save yourself time and just do it the WordPress way. Use the create block package.

Actually coding the block

I don’t consider myself a development guru, but I know enough to be pretty dangerous. I’m pretty decent with UI/UX as well. What I’m not that good at is all the intricacies of Gutenberg and interacting with WordPress’ internal APIs the proper way. So, I hit Google hard and found some excellent sites to help me learn.

Here are a few very helpful resources I found along my journey:

1. Block Editor Handbook – Despite being hard to navigate and clearly a work in progress, there is a still ton of excellent content here with good explanations. I really wish some the JS had more examples and it should as time progresses.
2. WordPress Gutenberg Developer’s Guide – A White Pixel has put together some very helpful articles here that explain everything from getting started to creating a Gutenberg powered settings screen.
3. Gutenberg WordPress Components – Kind of like a storybook of the various components you can use when creating your block.
4. Creating a Plugin for the WordPress Editor – This is a nice overview of the steps to create your first plugin with good explanations that’s still relevant as of this writing.
5. Gutenberg Storybook – If you’re familiar with Storybook, this is Gutenberg’s. This helped me discover components I didn’t know existed (like the modal) and helped me to implement them.

Do you have a resource that you think should be included in the list above? Let me know!

Expect more block directory plugins from me… very soon!

There is a decent roadmap in place for the donation form block, but now that it has been released I do have some more time for another block I’m working on to be finished.

It’s called “GitHub Profile Block” or “Blocks for GitHub” – I’m not sure which one yet. This is because I would like to have all GitHub-related blocks contained in one plugin but if it’s more beneficial to separate them into single block plugins then I’ll go that route.

Here’s what the GitHub profile block will look like (or very similar):

As you can see the profile block allows you to show off your development highlights via your GitHub profile. It pulls it in via the API and stores results using a transient. I’m still working out the kinks on some of it before release.

You can see, though, that I’ve caught the block bug.

I encourage all WordPress developers: if you have a block idea, build it.

See you on the block (directory)!

To me, the block directory appears to be a like a blue ocean opportunity. Meaning, there’s not a whole lot of competition right now and with WordPress’ full site editing recently launching things could pick up steam quickly.

Creating blocks is also a lot of fun!

I admit, it’s a bit challenging and the non-seasoned WordPress developer may have some real head-to-desk frustrating experiences. However, it’s only getting better with time.

I remember when the block editor first was released, it was a whole lot hard those few years ago. Ultimately, it’s only going to continue getting better and love it or hate it… it’s here to stay.

So, why not capitalize on the opportunity? I am.