How to build a multi-block plugin

As a WordPress developer who has mainly focused on enterprise level solutions, the concept of a multi-block made far more sense than having several individual block plugins. Thinking long term, a well-designed enterprise system could easily have dozens of custom blocks and other functionality related to modifying blocks or improving the editor experience.

The concept of a multi-block plugin is something I’ve seen mentioned online a couple of times, but I don’t recall seeing an in-depth tutorial. In this article, I will create a basic multi-block plugin then add advanced functionality to turn it into a robust block plugin that can be extended beyond registering blocks.

By the end of this article you will have gone through the steps to set yourself up with your own multi-block plugin and will be ready to build out and manage any number of blocks in one centralized plugin, along with other block editor related functionality such as variations, registering block styles, adding slot fills, and anything else you may need.

Benefits to a Multi-Block Plugin

• Less maintenance, easier dependency management
• Increase shared code, reduce duplication across plugins
• Potential improvements to security response time (I’m no expert, but a hole in a key dependency is easier to address and contain in 1 plugin than 10)

If you are unfamiliar with creating custom blocks and the system setup, requirements to do so, please read up on creating a Block Development Environment in WordPress.

If you are building along with this tutorial there is an example of the plugin for reference that can be see in this public repo.

Basic Setup

By the end of this section of the tutorial you will have built a single plugin called WP Multi Block that will register two static blocks and a dynamic one. Let’s get started by creating your block plugin.

Creating a Block Plugin

The first step is to get a base plugin setup for blocks. For this, you will use the officially supported `create-block` tool. This tool will take care of scaffolding this plugin, all by running one simple command inside your /plugins folder:

npx @wordpress/create-block@latest wp-multi-block

By default, the @wordpress/create-block generates a static block, but there’s an argument --variant dynamic that can be used if you wish to start with only a dynamic block. If you’re following along you’ll use this argument later in this tutorial.

What’s the difference between a static block and a dynamic block? At a very high level, static blocks use a save() function to store HTML markup for the block into the post_content table in our database. Dynamic blocks use a PHP render callback to render content on the server side when the page or post is viewed, only storing the block’s attributes in the database. For more details you can read here on the Developer Blog Static vs. dynamic blocks: What’s the difference?

For the purposes of this tutorial you will be using the basic command and starting with a static block.

Refactor the Plugin Structure

To better organize multiple blocks in the plugin there are some changes you  can make to the plugin structure.

Create a Master Blocks Directory

Inside the src directory do the following:

• Delete all existing files
• Create a folder called blocks

Why add a blocks directory, it seems unnecessary? We’ll want to be able to add a src/scripts and maybe a src/styles later, so grouping blocks will improve long-term organization and maintenance.

Create a Single Block

There’s a way we can use @wordpress/create-block to set up only what is required for a block by using the --no-plugin option. Inside of the src/blocks directory and run the following:

npx @wordpress/create-block@latest block-one --no-plugin

Here’s what my updated directory structure looks like in VS Code: