React 19 out of WordPress 7.1; Gutenberg experiment added

WordPress 7.1 continues to use React 18.3

React 19 upgrade won’t be a part of WordPress 7.1. After briefly enabling it in Gutenberg we discovered unexpected incompatibilities in how old and new version of React interact with each other, and in the ways how plugins use React, and we were forced to revert the change. We’ll need a considerable testing period where we improve and fine-tune the compatibility layer that allows the existing plugins to run seamlessly.

Experimental flag in Gutenberg

Instead, there is a new experiment in the Gutenberg plugin (since version 23.4) that enables React 19 on your WordPress site, intended for testing plugin compatibility. To enable the experiment, install the Gutenberg plugin and check a checkbox on the Gutenberg Experiments page (under Settings › Gutenberg):

Testing plugins

Testing a plugin compatibility generally means trying to use all parts of the plugin that uses React, typically Gutenberg blocks and extensions, and also custom WP Admin pages, and verifying that the UI is not broken and there are no errors logged in the browser console.

What kind of errors to look for

Typical failure modes for plugins are:

1. Bundling the react/jsx-runtime code directly in the plugin JavaScript code instead of using the “externalized” react-jsx-runtime script provided by WordPress itself. Such bundling leads to a mixture of React 18 (bundled) and React 19 (provided by WordPress) running together and passing data structures created by the old version to the new runtime. If everyone was bundling their JavaScript correctly, the majority of compat issues wouldn’t happen at all.
2. Using really old React features that were removed in React 19, after being deprecated for a long time (at least 6 years). String refs, default props on function components, legacy ways of defining context, … Some of them we’re polyfilling in the compat layer. A more detailed overview can be found in the “Removed APIs” section of an earlier post about the React 19 upgrade.

There is also work in progress to automatically detect these issues as part of the Plugin Check plugin.

Everyone is invited to test and update their plugins, and report issues in the Gutenberg GitHub repo.

---

Props to @tyxla, @aduth, @simison, @wildworks and @mamaduka for contributions, feedback and code reviews.

Props to @tyxla and @aduth for reviewing a draft of this post.

#7-1, #dev-notes, #dev-notes-7-1