Building a multi-block plugin

[bph]

Discussed in #289

^{Originally posted by troychaplin July 15, 2024}
Create block is a fantastic to help get you up and running with a new block rather quickly. but what if you plan to build multiple blocks and want to keep them all contained within one plugin?

I was faced with this challenge in a recent project and think sharing my experience and configuration would benefit other developers. This post would include plenty of code examples as well as a repo with a multi-block starter project that I would build during the process of writing the post.

[bph]

... making sure this comment by @zzap doesn't get lost

@troychaplin please ping me when draft is ready for the first review. Thanks

[bph]

Here are a few links to get you started, @troychaplin

Tips and guidelines for writers
How to contribute

and in there you also find Google Doc template to get you started.. Notes on creating and formatting a Google Doc #242

[troychaplin]

Just a quick follow up @bph and @zzap, it's nearly done. Was away for a week on vacation, hoping to have the first draft done in the next couple of days.

[flexseth]

@troychaplin - nice to see you over here, we've chatted on Ryan's livestream a bit. Here are a number of links and resources, and some GitHub issues that this could help to address.

Issue #22 - Block Developer Cookbook

• Creating a plugin that exposes several blocks while using the same wp-scripts package ryanwelcher/block-developer-cookbook#22

Issue #80 - Block Development Examples repo

WordPress/block-development-examples#80

• A plugin containing multiple blocks (showing file structure / build configuration etc.)

Slack discussion:

https://wordpress.slack.com/archives/C03RL47B3S8/p1709818696592279

Specifically for the prerequisites part. Like, you are reading an advanced article. We assume you know about X, Y, Z. Where X would be wp-scripts, Y building a simple plugin, etc.

---

Video resources

• Block Developer’s Cookbook
  • From WC Asia

---

create-block-plugin - Advanced

Can be used to scaffold multiple blocks (via CLI) - maybe a follow-up post.

[troychaplin]

Good to hear from you again @flexseth. Thanks for these links, I'll go over them once I get my first draft written and see how they relate.

[troychaplin]

@zzap The first draft of my article is ready for review -- https://docs.google.com/document/d/1vlCwOmoea4HdqkVlNACNTWuVKFC7KIs3mg4cIIva_JQ/edit?usp=sharing

[zzap]

This is a partial review. I added a bookmark for myself to know where to continue.

First of all, thank you so much for writing this tutorial, @troychaplin. I'm having a lot of fun following it. Here are my suggestions so far:

1. The local environment.
I have doubts about this section. I use Docker on some projects, but not on some other. My default setup is Apache/mySQL/PHP, installed directly in OS because Linux is OS of WordPress hosted servers and I like to have the similar(ish) environment.

Following the tutorial, I went to one of my local installs that I use for testing, fun and break. It's just a regular WordPress inside my Apache. I ran the block scaffolding script inside of it, easy-peasy, all good. Then I saw you want to use wp-env. Oki doki, moved the plugin dir outside of my www folder, ran the env install script and, shoot, my node version is wrong. So I went to install new node version and switch to it. Then I had to shut down Apache and mySQL and run Docker Desktop. And then everything was working.

Now, I am used to this. I do this every time I switch between enterprise and smaller clients. But some people might have never used Docker or wp-env. And, honestly, they probably don't have to. But that's besides the point. The point is that local environment is NOT important for this tutorial. Blocks work in any.

Personally I would lose the whole section about environment. Just mention what you use and why, link to its documentation and say that it doesn't matter what you use to be able to follow the tutorial. Because it doesn't and it's just a roadblock for people who don't use Docker.

2. Render callback
For dynamic block, I'd suggest using the render property for block.json rather than render callback, as it is more clean and up to date.

3. Best practices
I left a couple of comments for applying correct textdomain and function prefixes, as we want to always apply WordPress official best practices in every code example.

The rest of the review will follow soon. Thanks again ❤️

[flexseth]

@troychaplin - I included some suggestions in your draft. Thanks for putting this together.

[troychaplin]

Thanks for the feedback @zzap, I have made all suggested changes. The section about wp-env has been completely removed, your feedback made perfect sense. I've also updated code related to the render property, and have also taken the suggestions from @flexseth into consideration and have added more code examples in all areas of the basic setup section of the article.

I plan on going over the next advanced configuration section this evening to make similar modifications and make sure the way examples are presented is done consistently.

[troychaplin]

@zzap forgot to comment to say I'm finished with additional revisions to the content you haven't reviewed yet. Cheers!

[zzap]

Hey @troychaplin , thank you so much for accepting suggestions.

I completed the review and found it very interesting and informative. It has a nice arch, bringing the reader from a known place to new knowledge. I love the additional settings and custom webpack config section because that's not something you do every day, so when you do it, you become an expert, but tomorrow, that expertise is gone and you're a clueless noobie when you have to do it again in a few months 😂

I'm left with two things on my mind after reading it:

1. Interactivity API and view.js (as I mention in the document's comment), and
2. the copy/pasta method works great when we have just scaffolded blocks, but what happens when these files get populated with the block's specific code? Getting the new block into the "ready to code" state is going to take much more effort than editing the block.json file. Personally, I would scaffold a new block in some other folder (or the folder for the new block) and then copy the src content into the block's folder.

This is not a request or suggestion, but if you have an opinion on the second item, I'd love to hear it, and maybe include it in one sentence in the article.

Thank you again.

@bph this is ready for second review.

[troychaplin]

Thanks @zzap

I am not familiar with the Interactivity API just yet, I did not know it leverages view.js. I do have a very simple work around for this, but it's not idea so I didn't want to put it out there in the article, but I do it for a couple of project. In the register_block_type function you can point to the block.json file in the src folder. The issue with the view.js is that when you add webpack and compile it this way no individual JS files get placed in each block folder in the build directory which is needed with the way the view.js file is referenced in the block.json.

I would be interested in hearing if you do dive in to this one and find a solution. I may have a look at some point too, I've never had the need to this point.

As for the copy paste, I think there's an addition I could make here. Just a little side note about being able to run npx @wordpress/create-block@latest block-two --no-plugin directly in the src folder. Or maybe I'll do a quick revision and have the reader run that command and just get rid of the larger instructions with more manual work to get setup.

@bph could you please give me until tomorrow to make a few updates before the doc gets a second review?

[bph]

@troychaplin I just got back from vacation and I am almost through my backlog. I put the review of your post on my to-do list for Monday (9/2) Have a great weekend!

For what it's worth, I like your npx @wordpress/create-block@latest block-two --no-plugin approach.

[troychaplin]

Hey @bph and @zzap, I've updated the basic setup section of the docs to change the approach creating blocks, added a little note about how this change impact text-domain in each block.json.

[bph]

@troychaplin I started the 2nd review, but ran out of steam. I will continue it tomorrow. I already left a few comments following along with your code example and had opinions.
I also would urge you to read through the Tips and guidelines for writers, especially the part about avoiding the "we" and replacing it with "You" as that where most of my edits are coming from.

Ignore my bookmark to find the spot where I stopped. More tomorrow.

[troychaplin]

Thank you @bph, I just went through all of your feedback. I also went through the content after your bookmark to change the we's to you's, etc

[bph]

I finished my review. You are almost there! 🎉

• Most corrections are coming from the need to have the code examples adhere to the WordPress Coding Standards.

• I also offered suggestions for linking to other dev blog articles, and some rewording.

• somewhere I went astray and I didn't get to see the updated changes, so a few more screenshot for a set of instructions, would be wonderful.

• It also would be helpful if you could provide the finished plugin on GitHub on the /wptrainingteam organization. I just sent you an invitation so you can upload your example plugin there. (upload it as a public repo, pls.)

Once you are through this round of updates, you can start moving it to the dev blog. I also sent you and invite to your wp.org email address. You would need to click on the link to accept the invitation. I'll share the pre- and post publish checklist in the next comment.

[bph]

Pre-publishing checklist:

• Post Title and subheaders in sentence case
• Are Category or Categories selected?
• Are Tags identifies?
• Is there an explicit Excerpt?
• Are all images files uploaded to the media library
• Do all images have an alt-text?
• For TOC us the Pattern under Developer Blog > Table of contents
• Assign or upload a featured image
• Props added? (See Guidelines)
• add copy for a social post as comment to this issue (example)
  🙌 Publish! 📗 as this is your first blog post here, please "Enable public Preview" and share the link in a comment.

Post-publishing checklist

• add Props for reviews to #props channel in WP Slack (Example) (use Slack handles)
• Add the label "post to social" to the issue
• close the issue with a comment to link to the published post
• close the accompanying discussion with the link to the published post.

[troychaplin]

Thanks @bph, I've gone through the checklist and have everything ready.

Here's some copy for a social post:

Learn how to build a multi-block plugin by registering several static and dynamic blocks all in one plugin

The public preview URL is https://developer.wordpress.org/news/?p=4208&preview=1&_ppp=4fd288d9fe

[bph]

@troychaplin I went through the post on the blog and made quite a few adjustments.

(Don't take this as criticism of your work, that I publish my changes here. I am logging my changes so we can create formatting standards for the blog and future new writers have it a bit easier. )

I modified your headers and subheaders. We only use two-level heading (h2 and h3). That way we can avoid duplicate subheaders and too deep leveling.

This shortened the Table of Contents quite a bit and is less intimidating. I also move the TOC below your introductory remarked. They then don't need any headers either.

One sentence doesn't need a sub header.

Where it was necessary for readability to leave them I converted them to paragraphs with large and bold fonts so they stand out.

Featured image:
I also uploaded a different feature image. It will be pulled into all the social sharing later.

We don't have standard instructions for what a good feature image would make either. But we have been working on it.

I also changed your note about text domain to a notice block, so it wouldn't need a sub header either.

The post is now scheduled for September 17 at 2:45 am UTC

[troychaplin]

Thanks for all the feedback and help @bph, much appreciated. I don't see this as criticism, but rather guidance on how to follow the process which I need to learn.

[bph]

We are all on a learning path to get better and better. Thanks for your great work on this article!

[troychaplin]

Article has been published at https://developer.wordpress.org/news/2024/09/17/how-to-build-a-multi-block-plugin/#comment-12125

[bph]

Schedule for Oct 2