As web developers we are not constrained by the exacting requirements of safety critical systems such as those used on airliners or in nuclear power stations.
We web developers are accustomed to taking a more casual approach when creating our back-end applications and front-end browser-side JavaScript. Sure, we’ll take a glance at the documentation, maybe read through a tutorial blog post or two, or search StackOverflow for a solution to the problem we’re currently stuck on, but generally we don’t need to take the rigidly strict approach needed in safety critical systems.
This “hacking” mindset may serve us well in most instances but when it comes to developing for the WordPress block editor (also known as Gutenberg) it serves us less well. This is for a number of reasons. The block editor is a large and complex piece of software. It also has a unique API. In addition it uses technologies that we WordPress developers who are more accustomed to working with PHP find somewhat alien and forbidding, if not downright scary – e.g. node, React, JSX, ES6, etc…
It therefore behooves us as web developers seeking to dip our toes in the murky waters of block development to take a more systematic approach and do our homework in order to learn about the API properly, to learn about the processes and techniques involved, and to ensure that we’re following best practice.
This in itself is a daunting prospect. You may well be asking yourself the following questions. What do I need to know? How do I get started? What resources are available to help me learn? What resources are available to help me when I get stuck? It’s true, there’s much to learn, and the resources to help you learn are not always easy to find.
This post is intended to guide you through the murkiness and emerge blinking into the clear light of day. It has been written by someone who has followed the same path. Before learning about block development I was a PHP developer who started by creating custom themes and went on to develop plugins to implement custom functionality on WordPress/WooCommerce sites. More recently I had the need to learn JavaScript in order to create client side interactivity and work with the WordPress REST-API in web applications for my clients.
So, allow me to guide you through some possible answers to the four questions posed earlier, namely:
- What do I need to know?
- How do I get started?
- What resources are available to help me learn?
- What resources are available to help me when I get stuck?
What do I need to know?
You’ll find that the procedural programming skills that you may have as a seasoned PHP developer aren’t needed much when it comes to block development. Instead an understanding of functional programming will help you a lot, and in particular React.
React is a framework built on JavaScript that has become enormously popular in recent years. The block editor is built almost entirely in React and creating custom blocks requires an understanding of React. If you’re unfamiliar with React seek out a good tutorial. There are plenty available, both free and paid, but the official tutorial is a great place to start to get the fundamental concepts down.
It of course goes without saying that you should already know JavaScript, and in particular you should be familiar with ES6.
React applications generally use JSX to render components, and the block editor is no exception, so you should ensure that you’re familiar with JSX.
You will need to have NodeJs installed on your development machine in order to do block development, but you don’t really need to learn too much about node itself or about any of the configuration options, as you’ll see in the next section.
How do I get started?
As already mentioned, you need to have node installed on your development machine. You’ll also need to have a local WordPress installation. If you don’t already have an environment for setting up a local WordPress installation then there are a variety of options. You can learn more and choose the one best for your needs on the Installing a Local Server page.
You’ll also obviously need a code editor, such as VS Code, Sublime Text, or Brackets. In addition you’ll need a terminal application – most computer operating systems already have one and some code editors also incorporate a terminal.
Though useful to know you won’t actually need to know about configuring node. You can get a basic block application scaffolded together with a complete and fully configured build environment by using the following command in your terminal:
npx @wordpress/create-block my-projectwhere my-project is the name that you choose for your project.
The @wordpress/create-block utility gives you everything you need to get up and running and you can do interactive development on your block by running this command in your terminal after your block has been scaffolded:
npm startWhat resources are available to help me learn?
Your first port of call should be the Block Editor Handbook. This is the definitive resource when it comes to block development.
Admittedly it’s not perfect, for example it could be better structured and so it can be quite difficult to navigate, but that’s what this post is here for – to help you with that. The Handbook is constantly being updated and improved, so any shortcomings will get better over time.
There are some important nuggets in the Handbook that will help you get started and, although they can sometimes be a bit tricky to find, I’m here to point you to the most salient information.
Firstly there’s the Create a Block Tutorial in the Getting Started section. This will get you up and running with a basic block and teach you the essentials of block development.
Once you’ve worked through that then there’s another useful tutorial to help you build on that knowledge.
Once you’ve got a basic understanding of building blocks then it’s worth your while spending some time to understand the architecture of the block editor and you’ll almost certainly need to refer to the various Reference Guides once you get started properly on a block development project.
You’ll almost certainly find the How-to Guides section useful as your knowledge and understanding progresses despite this being one of the messier sections structurally, and in particular the chapter on Creating dynamic blocks should certainly be on your radar. Even if you don’t intend to build a dynamic block it’s important to know how static and dynamic blocks differ from each other.
If your JavaScript is a little rusty there’s a whole section on How to use JavaScript with the Block Editor.
There’s no better way to understand how something works than to look at some source code. All the source code for the block editor is contained in the Gutenberg GitHub repository. The source code for individual core blocks, i.e. the ones that are built into the block editor such as paragraph, heading, button, and gallery, etc… are contained in the /packages/block-library/src/ directory. This is a great place to see how the core developers have created particular blocks.
Further useful and interesting examples, that also illustrate best practice, can be found in the gutenberg-examples Github repository. This repository is also regularly being updated with fresh and up-to-date examples.
You build your block using components and, when browsing through the Component Reference in the Handbook in order to decide which components to use in your block development project, you might think that it would be useful to be able to try them out to see how they work before adding the code for them to your project. Well you can! There’s a Storybook tool that allows you to browse through the available components and try them out interactively.
Finally, if all the above is a bit overwhelming and all you want is a nice gentle introductory step-by-step tutorial on creating a block then the course that was recently published on learn.wordpress.org, namely Introduction to Block Development: Build your first custom block, has you covered.
What resources are available to help me when I get stuck?
Your journey in learning block development will not be problem free – trust me on that, I’ve been there!
The good news is that debugging JavaScript and React is a lot easier than debugging PHP. With PHP you need to log errors to a log file and then go and inspect the log file. Whereas with JavaScript and React errors appear in the terminal and in the browser’s console. The Handbook has a useful troubleshooting guide that covers the use of the console.
One thing you’ll encounter very early on is this error:
It’s one that you’ll encounter frequently. In fact it will pop up in the editor every time you make a change to the save() function. The save() function is the function that saves the content of the block to the database.
Usually this is not a problem and all you have to do is hit the blue button and all will be well again.
This error occurs because when you change the save() function the content that is retrieved from the database no longer matches what the save() function specifies should be saved, and it will occur however minor or inconsequential the change is. As already mentioned, you’ll find it occurs pretty often and you’ll get used to seeing it.
Whenever you encounter this, or any other problem that shows up in the editor, you can look in the browser’s console for more information on the error. In fact the browser console is one of your best friends when it comes to block development. You can sprinkle any of the console methods, such as console.log(), liberally in your code to get information about the state of the application. Handy tip: you’ll be working with objects extensively when developing a block and console.table() is a great way of inspecting objects such as the attributes object.
console.table in the browser consoleYou can also use the browser’s built-in debugger which enables you to use breakpoints in your code. Visit the respective websites to learn more about debugging in Chrome and in Firefox.
Something that you’ll find well worth installing is the React DevTools, available as an extension for both Chrome and Firefox. As you dig deeper into block development you may also find the Redux DevTools useful. This is also available for both Chrome and Firefox. The React and Redux DevTools give you insights into your application’s state that the standard browser debugging tools don’t.
Browser based tools are useful so long as your application reaches the stage where it will run in the browser. Sometimes you’ll get compile time errors, so make sure to keep an eye on the terminal too as that is where compile time errors will show up.
There will be times when you are stuck on a problem and the browser tools and compile errors are not helping you to solve the problem. It’s at times like these when you will find it useful to turn to the online developer community.
Here’s a couple of places where you can ask questions and where the community has proved to be both friendly and helpful:
You can also use the Gutenberg repo to get help. For example, you can create an issue with the “[Type] Help Request” label or ask your question on the Discussions board.
When asking technical questions online remember to be polite. You should state what the problem is as clearly and as completely as possible. You should also explain what you’ve already tried and outline the research you’ve already done to try to resolve the problem.
In conclusion
I hope that this post has helped to give you the confidence to dive into the resources available and get started with block development. As mentioned earlier you should take the time to learn about the block editor using a systematic approach and I hope that I’ve been able to guide you onto the path that is right for you.
I conclude by wishing you all the best on your journey as you tackle block development. It’s not as hard as it may initially appear and with the right approach you can be confident that you will ultimately succeed.
With thanks to @bph, @juanmaguitar and @webcommsat for reviewing this article
Leave a Reply