React 19 Punted Beyond WordPress 7.1: How to Test Your Plugins in Gutenberg

Why WordPress 7.1 is Staying on React 18.3

The transition to React 19 represents a major milestone for the modern WordPress block editor and the broader JavaScript ecosystem. However, maintaining backward compatibility across tens of thousands of plugins is a monumental task. During active development and testing, the WordPress core team briefly enabled React 19 within the Gutenberg plugin. This real-world experiment quickly exposed critical runtime conflicts, particularly in how older and newer versions of React interact on the same page, as well as how third-party plugins consume the library.

To prevent widespread site breakage, the core team decided to postpone the React 19 upgrade. WordPress 7.1 will continue to ship with React 18.3. This delay provides a necessary runway for plugin developers to audit their codebases and for core contributors to refine a robust compatibility layer that ensures a seamless transition when the upgrade eventually lands in a future release.

The Gutenberg Experiment: How to Safely Test React 19

To facilitate comprehensive ecosystem testing without risking production environments, the core team introduced an experimental flag in the Gutenberg plugin. Starting with Gutenberg version 23.4, developers can force WordPress to load React 19 instead of the default React 18.3.

To enable this testing environment, follow these steps in a local development or staging site:

• Install and activate the Gutenberg plugin (version 23.4 or higher).
• Navigate to Settings › Gutenberg in your WordPress admin dashboard.
• Click on the Experiments tab.
• Locate the React 19 experiment checkbox, enable it, and save your changes.

Once active, your WordPress site will run on the React 19 runtime, allowing you to thoroughly test blocks, custom WP Admin pages, and editor extensions.

Failure Mode 1: The Danger of Bundling react/jsx-runtime

One of the most common and disruptive failure modes discovered during Gutenberg testing is the practice of bundling react/jsx-runtime directly inside plugin JavaScript builds.

WordPress relies on a system of “externalized” scripts. When a plugin is built correctly, it does not package React’s core code into its own compiled files. Instead, it references the global React instance provided by the WordPress core environment. However, if a plugin’s build configuration (such as Webpack, Rollup, or Vite) is misconfigured, it may bundle its own copy of React 18’s JSX runtime directly into its production assets.

When this happens on a site running React 19, a dangerous hybrid state occurs:

• The plugin’s bundled React 18 code executes alongside WordPress’s global React 19 runtime.
• The plugin passes internal React 18 data structures and virtual DOM nodes directly to the React 19 reconciler.
• Because the internal fiber structures and APIs differ between versions, this mixture causes silent rendering failures, UI crashes, or console errors.

If developers correctly externalize their dependencies, the vast majority of these compatibility issues are completely avoided.

Failure Mode 2: Legacy React APIs Removed in React 19

React 19 completely removes several legacy APIs that have been deprecated for years (in some cases, over six years). Plugins relying on outdated code patterns will break immediately under the new runtime. The primary culprits include:

1. String Refs

Using string literals as refs is no longer supported in React 19. If your code looks like this, it will fail:

// Broken in React 19
<input ref="myInput" />

Instead, you must update your components to use callback refs or the useRef hook:

// Correct pattern
const myInput = useRef(null);
<input ref={myInput} />

2. Default Props on Function Components

Defining defaultProps on a function component is deprecated and removed in React 19. For example, this pattern is obsolete:

// Broken in React 19
function MyButton({ label }) {
  return <button>{label}</button>;
}
MyButton.defaultProps = {
  label: 'Click me'
};

The modern, standard JavaScript approach is to use ES6 default parameters directly in the function signature:

// Correct pattern
function MyButton({ label = 'Click me' }) {
  return <button>{label}</button>;
}

3. Legacy Context

Old context APIs like contextTypes and childContextTypes are fully deprecated. Modern plugins must migrate to the standard React.createContext() API or the useContext hook.

How to Audit Your Plugins for React 19 Compatibility

Auditing your plugin requires a systematic approach to ensure that both the user interface and background scripts behave correctly under the new runtime. Follow this workflow to verify compatibility:

1. Set up a clean local environment: Use a tool like wp-env to spin up a local WordPress site. Ensure you have the Gutenberg plugin (v23.4+) installed and the React 19 experiment enabled.
2. Open Browser Developer Tools: Keep the browser console open at all times during testing. Look for warnings, deprecation notices, or unhandled runtime exceptions.
3. Exercise all React-powered UIs: Interact with every part of your plugin that utilizes React. This includes custom Gutenberg blocks, block sidebar panels, settings pages built with @wordpress/components, and custom dashboard screens.
4. Verify block saving and rendering: Ensure that blocks render correctly in both the editor and the frontend, and that saving a post does not trigger block validation errors.

The Role of the WordPress Compatibility Layer and Plugin Check

To ease the transition, the WordPress core team is actively developing and fine-tuning a compatibility layer. This layer acts as a safety net, polyfilling some of the removed React APIs so that older plugins do not immediately crash. However, this compatibility layer is not a permanent solution and cannot resolve fundamental structural issues like bundled JSX runtimes.

To help developers identify these issues programmatically, work is underway to integrate React 19 compatibility checks into the official Plugin Check tool. This tool will automatically scan plugin codebases for deprecated React APIs and improper dependency bundling, providing clear feedback before plugins are submitted or updated in the WordPress.org directory.

Best Practices for WordPress Block and Plugin Developers

To ensure your plugins remain robust and compatible with both current and future versions of WordPress, adhere to the following development standards:

• Use official build tools: Build your blocks using the @wordpress/scripts package. This package comes pre-configured with the correct Webpack rules to automatically externalize React, React DOM, and their respective JSX runtimes, mapping them to WordPress’s global wp.element and external scripts.
• Avoid custom Webpack overrides unless necessary: If you must write a custom Webpack configuration, ensure that you explicitly mark react, react-dom, and react/jsx-runtime as externals.
• Proactively refactor legacy code: Do not wait for the official React 19 release to remove string refs, legacy context, and defaultProps. Refactoring these to modern React patterns now is fully backward-compatible with React 18.3.
• Report issues early: If you encounter bugs or unexpected behaviors while running the Gutenberg React 19 experiment, report them directly to the Gutenberg GitHub repository. Your feedback is vital to shaping a stable compatibility layer for the entire WordPress ecosystem.

Primary reference: Review the original announcement for exact release details. This article is an independent explanation and does not reproduce the source text.