Importing React modules directly instead of using @wordpress/element

[tyxla]

Background

For a long time, we've been importing any react and react-dom utilities and functions from the @wordpress/element, which essentially re-exports them.

Back in the day, we introduced @wordpress/element as an abstraction layer, which could theoretically allow us to use a different technology under the hood if needed at some point.

However, a few years later, it's easy to see that React is a first-class citizen in the Gutenberg codebase, and we can't just remove it because everything depends on the intricate way React works under the hood.

That being said, @wordpress/element feels more and more like an unnecessary wrapper that only adds a redundant abstraction layer. On the contrary - in some 3rd party projects that rely on @wordpress packages, it's caused trouble since it required keeping react and react-dom versions up to date with the underlying versions in @wordpress/element in order to prevent duplication.

Proposal

I'd like to propose that we start importing react directly in the Gutenberg codebase. Essentially, this means we'll migrate all existing usages in the Gutenberg codebase. It also means we'll inverse this existing ESLint rule:

'@typescript-eslint/no-restricted-imports': [
	'error',
	{
		paths: [
			{
				name: 'react',
				message:
					'Please use React API through `@wordpress/element` instead.',
				allowTypeImports: true,
			},
		],
	},
],

so across Gutenberg, we will not be allowed to import from @wordpress/element, but will rather import modules directly from react and react-dom.

At that point, we'll be able to soft-deprecate @wordpress/element, encouraging 3rd party developers to also import from react and react-dom.

Of course, for backward compatibility, for the long-term we'll continue to maintain @wordpress/element which will still re-export the React utilities, and will continue to allow 3rd party plugins to use the React APIs in wp-admin.

Rationale

At this point you're probably asking why we want to do it, and why NOW. Let's dive into that.

Previously, we didn't really have a good motivation to move forward with this project-wide change. However, with the upcoming React 19, we might have to do it.

React Compiler, an essential React 19 feature, will not recognize any react/react-dom modules that are re-exported. That means that some of the React Compiler rules can't really be followed. For example, React Compiler won't know that useRef() from @wordpress/element is the one coming from react, and as a result it won't be able to treat it accordingly with the expected special exceptions.

We'd like to leverage React Compiler for Gutenberg, as it promises to optimize the app at build time and promises to have a positive impact on runtime performance. We're experimenting with React Compiler in #61788 and are incrementally addressing all the blockers, aiming to enable it as soon as it's considered ready for production.

I've been exploring whether it's possible to extend the React Compiler to recognize external modules as known ones, but the chance of actually having support for that is low. See facebook/react#31138 for more information.

Luckily, this won't be a problem if we use react and react-dom directly.

Proposed approach

Since changing all @wordpress/element imports is a repository-wide change that will affect everyone's code, I'd suggest that we:

• Do it early in the WP 6.8 cycle (meaning ~now is a good time)
• Prepare a codemod to modify all the imports
• Over the weekend, when there's little activity in the repo:
  • Run the codemod and spin up a PR
  • Get the changes tested and reviewed
  • Merge
  • Announce in Slack, nudging everyone to rebase their PRs
• Write up a dev note
• Write up an announcement in make.wordpress.org/core

Feedback

I'd love to hear everyone's feedback and hear if anyone has concerns or ideas to consider in the meantime.

Thanks, everyone!

[youknowriad]

As discussed with you, I think this proposal and the reasoning make sense but let's bring some more eyes on this proposal. @WordPress/gutenberg-core

Noting that ideally this is done in a single commit that we can add to the .git-blame-ignore-revs file.

[gziolo]

Replacing all occurrences of @wordpress/element to react and react-dom in a single commit in the Gutenberg codebase makes perfect sense.

How to invite the 3rd party code to join these is a separate story as there are a lot of teaching materials based on the existence of @wordpress/element. It probably should be tackled independently.

[widoz]

Assuming third parties would use @wordpress/scripts, what about an eslint rule? JSDoc does also have the possibility to specify the @deprecated rule.

[tyxla]

Yes, once we migrate the codebase internally, the move away for the rest of the 3rd party code will be gradual, and will include https://make.wordpress.org/ posts, documentation updates, and and ESLint rule that defaults to a "warning" can also be added at a later time. I wouldn't rush too much with an ESLint rule though, because we'll likely have to support @wordpress/element forever anyway - why wouldn't we?

[adamziel]

Fully agreed. If we ever need to backtrack, an import map could achieve the same result.

[cbravobernal]

Fully agree and embrace React!

[michalczaplinski]

I want to note that the Interactivity API uses Preact, so keeping @wordpress/element might have a small potential to make compatibility easier if we ever considered switching to Preact in the editor.

However, this possibility seems very minuscule to me, and importing React modules directly has clear benefits so I'm also in favor of importing react & react-dom directly.

[Mamaduka]

I agree with the proposal. It might be worth sharing in the #core channel for additional feedback, not sure if this warrants a proposal post on the make blog.

[tyxla]

Given that this will be an internal change for Gutenberg, I believe it doesn't really need to involve the broader core group.