Using a scaffold to build Gutenberg blocks for the WordPress editor (part 1 of 4)

Block scaffolds are being created, updated or going out of date at a regular rate these days as developers figure out what works best for them. So instead of making a recommendation on which one you should use, I’m going to tell you what I looked for – what was important to *me at the time* – when choosing a block plugin and then which one fit my needs.

The reason I’m using a block scaffold is because I’m not confident that I’ll do it correctly myself. The entire point of it for me is to have something I can make work and do what I want without being an expert at webpack config.

This will almost certainly change in the future and the one strong recommendation I do have is to take a bit of time and run through some to see which might work for you.

A quick overview of @wordpress/scripts

WordPress offers a set of reusable scripts packaged up as a node package for use in development. This makes it easier to set up the necessary configurations to build projects and provides a single point for updating scripts. The @wordpress/scripts documentation says it best:

Fortunately, there is a pattern that can simplify maintainers life – reusable scripts. The idea boils down to moving all the necessary configurations and scripts to one single tool dependency. In most cases, it should be possible to accomplish all tasks using the default settings, but some customization is allowed, too. With all that in place, updating all projects should become a very straightforward task.
@wordpress/scripts documentation

Most of the scaffolds will use @wordpress/scripts and extend / modify as necessary. This is a good thing as it’s tied tightly (from what I understand) to Gutenberg development and should stay updated.

It did take me a while to come to terms with the fact that it’s not possible to eject from wp-scripts (the command from @wordpress/scripts which runs things). I like to see the setup and how things work and I can’t easily set up a test project, eject, and do this. It feels a bit paternalistic that I can’t do that but it’s not a dealbreaker.

What I’m looking for in a block plugin scaffold

It uses @wordpress/scripts

For all the reasons above! Mainly the fact that it should, in theory, stay up with Gutenberg development.

Multiple blocks are built out of the box and use React components

This is a bit of a file structure preference. I want to easily add in new blocks, both dynamic and regular blocks, and have the file structure and entry scripts already be set up for more than one block.

Ideally Browsersync or another live reloading script is set up for development

Having pages reload automatically when I’ve updated something is super helpful. Yes, there’s a bit of setup and filling in of which pages should reload, but it’s worth it for me. This has the added benefit of extending the webpack config so I have something to add to when I want to change things rather than needing to remember how to do it myself.

Testing?

I should be more concerned about testing. @wordpress/scripts is set up for testing and it looks good but that’s about all I can say.

WP Block Builder

I settled on WordPress Gutenberg Block Plugin Builder which is available as a package here and installs from the command line.

The only thing I’m not sure of is the inclusion of the toml rule, but maybe that’s as an example? I don’t really know.

Here’s what my plugin looks like immediately after installation. I’m including the build but leaving out node modules because that would be a bit much I think. 😬

Setting up BrowserSync

BrowserSync will use the host given in the local.json file as a proxy for the localhost site and will live reload the the page there.

The steps I take to set it up on my local development site:

Make a test post in wp-admin as normal and publish.
Activate the plugin created by the scaffold. (This is the step I forget the most.)
Take the url of the edit page and replace the iceberg.test one in local.json .
In webpack.config.js replace the localEnv fallback with my local dev site.
Replace the port number in the BrowserSync plugin config at the bottom of webpack.config.js. This isn’t necessary unless port 3000 is already in use.
Run npm start on the command line to start up the development.
This will fire up Browsersync and open the page. The first time and every couple of weeks I need to log in to get to the page.
Log in.
Navigate to the post I’m using for development.
Develop!

Browsersync will reload the localhost site with every saved update so it’s not strictly necessary to make one post for development. You can use more than one or whatever. But I find it easier to make one and stick with it.

There’s also a UI for the Browsersync settings at https://localhost:3001 for me – the url for you will be shown in the terminal when you run npm start

Screengrab showing the Browsersync output after running the command. Includes UI: http://localhost:3001.

I’m already regretting keeping the build in the git repo. At any rate, here is the diff with the updates made to Browsersync. And here is the repo at this point in time.

Add in a new block

That’s the setup but I’m going to add in a new block now as an example. It won’t show up correctly (yet!) on the front end but we’ll get there. 😊 Because it should be cheap and cheerful but still, y’know, *do* something I want it to:

allow the post author to customise the wording or something of whatever is shown
have the ability to add more than one block to the post without getting confused
do or save something in the user’s browser (as a stand in for sending it off somewhere)

I’m going to make a stupid idle game. It’ll be a coloured circle with a timer set by the post author. The user has to click it as close to the time as possible and the post author can set the range for winning.

I think I’ll save the adding in of the new block for the next post as this one is rather long already!