The Block Directory, and a new type of plugin

The plugin directory already has a block section, and there has been some fragmented discussion about expanding or improving it. I’d like to share some thoughts on this and propose a more expansive solution. First I’ll outline some of the main problems that need solving.


  • Many plugins already register blocks, but often the plugin name and description doesn’t give a good indication of what those blocks are.
  • There is no way to search by block name.
  • Installation of plugins is far removed from the business of using blocks.
  • Developing blocks is a steep learning curve for new and experienced plugin developers alike.

A proposed solution:

Put briefly, I’d like to propose a new type of WordPress plugin that provides blocks and nothing else: Single Block Plugins. These will be hosted in a separate Block Directory section of the Plugin Directory. They will be JavaScript-based, and each plugin will register a single Block. And they will be searchable and installable from within the Gutenberg editor itself.

Let me break that down with some more detail.

A Single Block Plugin is intended to be a relatively small, simple plugin that provides a single Gutenberg block. The plugin is the block, essentially.

Single Block Plugins are WordPress plugins that conform to a few rules, including:

  • They register a Gutenberg block.
  • They’re written in JavaScript, and are front-end only.
  • They have no UI outside of the editor.
  • They use a block.json file with metadata as per the Block Registration RFC
  • They include readme.txt and header metadata as required.

This is not set in stone; we’ll work out the exact rules in collaboration with plugin developers and the community on Make WordPress Plugins.

The Block Directory will be a section within the Plugin Directory, that contains only Single Block Plugins.

  • It will be separate from the main plugin directory: you’re either browsing regular WordPress Plugins, or Single Block Plugins.
  • Single Block Plugins will be searchable by block name and description, as per the Block Registration RFC.
  • The Block Directory will probably use a simplified version of the plugin page layout for Single Block Plugins.
  • There will be an API endpoint for searching blocks by name and description.
  • Inclusion in the Block Directory requires following the rules for Single Block Plugins.

Regular WordPress plugins in the main Plugin Directory can continue to register Gutenberg Blocks.

  • Regular plugins will also be searchable by block name and description.
  • Regular plugins can register as many blocks as they like, and are not required to follow the same rules as for Single Block Plugins.
  • Regular plugins can continue to do all the amazing things they can now, including back-end code, wp-admin UI, and so on.

In other words, Single Block Plugins are for blocks; Regular WordPress Plugins are for anything at all.

Single Block Plugins will be JavaScript-based.

  • The block code will be entirely written in JavaScript.
  • The plugin can contain other assets like images and css.
  • To begin with, Single Block Plugins will contain a single PHP file containing plugin headers and initialization code only. Eventually, this should become unnecessary.
  • They won’t have any back-end code.
  • Any UI will be contained within the editor.
  • We’ll help onboard new (and new-to JS) developers with templates, samples, and other tools.

Single Block Plugins will be searchable and installable from within the Gutenberg editor.

  • The Block Inserter will use the above-mentioned search API to discover and display relevant Single Block Plugins from the Block Directory.
  • Installation will (eventually) be seamless, without leaving the editor.
  • We’ll make use of and improve the block management features that are already on their way into core.
  • Obviously this will entail plenty of design, UX, and accessibility work, which will start over on Make Design.
An artist’s impression of what inline installation might look like (thanks Mark!)

This post is intended as a starting point for discussion and new ideas. We’ll post more details on the Plugins, Meta, and Design Make sites in the coming days to focus on those particular areas.