Introducing BlockBook for WordPress

tl;dr: With BlockBook, you can build, test and showcase your static WordPress (aka Gutenberg) blocks in isolation. It can also be used to test the block styles of your themes. In short, it’s going to change how you develop and style blocks. If you’re a block developer, BlockBook is a must. You can see a working BlockBook here.

Since the initial release of the block editor in WordPress 5.0, the community has adapted rapidly. Hundreds of block plugins have been released.

Also, a dozen scaffolding tools to quickly generate or build your blocks are popping up. This includes the official tool @wordpress/create-block led by my friend Grzegorz Ziółkowski.

Some challenges remain unsolved, though:

1- Creating blocks in the context of WordPress is not straightforward. In addition to requiring a running WordPress environment setup with your plugin’s code, which can be tedious to get right, every time you make a change to your block, you need to refresh your editor, potentially facing invalidation issues, recreate blocks, apply changes and ensure the result is correct. This is hard and takes a lot of time.

2- Another frustrating aspect is theme testing. Blocks are supposed to work with all themes, and themes can style blocks to make them fit the theme identity more closely. For block authors and theme authors alike, this is challenging. There’s a need to install multiple themes, switch between themes, and — if you’re a block developer — ensure your styles are agnostic enough. And, if you’re a theme author, it’s hard to navigate and try out different blocks as you make changes to your stylesheets.

3– For users, it is very hard to discover blocks properly, to try them out and make informed decisions about what plugins to install or not. The Block Directory is a good step in this direction but navigating blocks is still an inconsistent experience across plugins.

Meet BlockBook

How can we solve these issues and make building and sharing blocks easier for developers and users?

If we think about it a little bit, blocks are reusable units that can live on their own outside of any context, they can be edited visually, and they produce markup. They have in fact a lot in common with React Components. They are super-powered React Components.

Well, we already know that, for UI components in React, a tool called Storybook exists which allows developers to solve the kind of issues mentioned above.

That’s where the idea came from: what if take Storybook principles as an inspiration and apply them to build an environment where we are able to build, test, document and share blocks in isolation from any context and in a consistent and very performant way?

That’s what BlockBook is about.

Using BlockBook

BlockBook is available as an npm package, so adding it to your own projects is straightforward. (Read the documentation for more details). Once the setup is done, you can run it locally using a simple command: npm run blockbook:start

And you can host it as a static website on GitHub pages (or any host).

BlockBook and WordPress

There’s a lot we can do with BlockBook in WordPress and, while this is built as a personal project for the moment, my intent is to propose it as an official @wordpress package and use the Core BlockBook as official documentation for the Core blocks.

Also, you can imagine that, with the Block Directory project and its guidelines, it should be possible to automatically build and host a BlockBook per block plugin (or across plugins) on (and potentially even themes).

These are just some of the ideas of where we could take this next.


BlockBook works well with projects using wp-scripts as a build setup. For alternative setups, it may or may not work at the moment. Please feel free to try it, and share feedback.


And as you’d expect, it’s open source, GPL-licensed, and you can help shape the project in the GitHub repository.

One response to “Introducing BlockBook for WordPress”

Leave a Reply

This site uses Akismet to reduce spam. Learn how your comment data is processed.