When I narrowed my development career focus from the PHP world at large to WordPress land, one of the things I enjoyed was WordPress’ commitment to backwards compatibility. As my fellow Minnesota coworker and pragmatist, Richard Aber, would say, new features are often syntactic sugar. In other words, I’m not going to save the world by typing [] instead of array().
But the compatibility landscape of WordPress 5.0 and beyond is much different. The new WordPress block editor Gutenberg is built upon React, and the development pace of React, Gutenberg, and all things JavaScript, in general, is extremely fast. I’m hoping this can serve as a reference or forewarning to those trying to keep up.
Gutenberg Versions
When you’re trying to build a Gutenberg block that is compatible back to WordPress 5.0, navigating this landscape is tricky. Since the Gutenberg editor is developed as a separate project, they have their own versions that get bundled with the major WordPress releases. Trying to find this historical information can be difficult.
After some research and discussion, Senior Backend Engineer, Sal Ferrarello, and Frontend Engineer, Mike England, started a compatibility matrix, which can be found on GitHub. But that didn’t answer all of the questions and solve all of the issues. The official Gutenberg Handbook itself is based on the latest Gutenberg code, which is ahead of the current version of WordPress. Sal opened an issue highlighting that the blocks API documentation is based off of the master branch of Gutenberg.
Sadly, Sal’s documentation version issue wound up being closed citing:
We’re fixing bugs more than we’re introducing new APIs at this point.
But shortly after the version matrix was created and the version issue filed, a new page showed up in the block editor handbook highlighting the version information:
Still, this “official” table can be a bit confusing. When you look at it, there is a range of Gutenberg versions included in a particular WordPress release:
This is because bug fixes are back-ported into the WordPress release bundle. If you’re using it for an API reference standpoint, always go with the smaller release number.
React Versions
There are several things to think about if you want to provide backwards compatibility to WordPress 5.0. One consideration is the React version included in WordPress.
If you want to create Functional Components instead of Class Components in your Gutenberg block, that requires React version 16.8. WordPress 5.2 is when React 16.8 was included. The easiest way I found to determine which versions of WordPress include which versions of React is to go to the source.
You can find the package.json for WordPress 5.2 here. This includes React 16.8.4. You can replace “5.2” with the version you’d like to investigate.
If you’ve written functional components for distribution in the WordPress.org plugin repository, don’t forget to add the “Requires at least” field to your plugin header:
/** * Plugin Name: My Plugin * Requires at least: 5.2 */
That way, people will not be able to upgrade/install your plugin automatically, unless they’re on WordPress 5.2 or newer.
Block Compatibility
My best advice is to tread lightly and go slowly. React and Gutenberg aren’t great at reporting where your errors are through the browser console. To start, I install the WP-Downgrade plugin so I can easily go back and forth between past and present versions.
If you’ve got something working, test it out and commit your changes. Then, test it for backwards compatibility. When you’re dealing with more than one compatibility error at a time, it’s difficult to hone in on what is going wrong. WordPress might not even load your Guten-block code if there are errors; and it also may not print a message in the console.
The most common issue I’ve encountered is with importing WordPress components. Sometimes things work by importing from a package. Sometimes they’ll only work by destructuring from the global wp object.
You may have to experiment with both to see what works for maximum version compatibility.
Example: ServerSideRender
The documentation says once you include it in your package.json you can either import it:
import ServerSideRender from '@wordpress/server-side-render';
Or destructure it from the wp global:
const { serverSideRender: ServerSideRender } = wp;
But neither of those work in WordPress 5.0 (Gutenberg 4.6.1) because @wordpress/server-side-render wasn’t a package yet. It also isn’t at wp.serverSideRender at that time, it’s at wp.components.ServerSideRender.
If you want it to work in WordPress 5.0, you’ll need to destructure it from the wp global like this:
const { ServerSideRender } = wp.components;
In new versions of WordPress, you’ll get this warning message in the console:
wp.components.ServerSideRender is deprecated. Please use wp.serverSideRender instead.
The user may never see that, and it sure beats them seeing this in the editor:
Deprecation Hunting
Other popular components that have moved since WordPress 5.0 are BlockControls and InspectorControls. I’ve got them working in 5.0 with the following browser warnings:
wp.editor.BlockControls is deprecated. Please use wp.blockEditor.BlockControls instead.
wp.editor.InspectorControls is deprecated. Please use wp.blockEditor.InspectorControls instead.
But how did I find them? Going to the source is always best. Clone the Gutenberg project and check out the tag for the most recent version of WordPress:
git clone git@github.com:WordPress/gutenberg.git cd gutenberg git checkout v8.6.0
You can browse the tags on GitHub or list them with git tag. After checking out the tagged version, start looking for the component that’s not working. For InspectorControls I used grep to find it:
$ grep -r InspectorControls . ... packages/editor/src/components/deprecated.js: 'InspectorControls' ...
There’s a lot of output when searching, but the path of the deprecated.js file gave me a clue: packages/editor. It used to be in wp.editor and is now in wp.blockEditor (which has the path packages/block-editor). Again, the documentation isn’t great, so you have to do some sleuthing and gather context clues.
Good luck out there, and always keep compatibility in mind!