Adopt @wordpress/use-recommended-components

[simison]

Likely best done after #48405 and #48404 land (which updates UI and Eslint libraries)

Proposed changes

• Upgrade @wordpress/eslint-plugin from 25.0.0 → 25.1.0. The new version ships a more complete use-recommended-components rule that flags additional deprecated @wordpress/components exports (__experimentalHStack, __experimentalVStack, __experimentalText, Card, VisuallyHidden, ExternalLink, etc.) and recommends @wordpress/ui alternatives.

• Enable @wordpress/use-recommended-components as an error-level ESLint rule monorepo-wide (in tools/js-tools/eslintrc/base.mjs). This encourages migration away from deprecated/experimental @wordpress/components exports toward stable @wordpress/ui components.

• Introduce a bulk-suppressions workflow (adapted from WordPress/gutenberg) to avoid scattering hundreds of // eslint-disable comments across existing files:

  • tools/eslint/lint-js.cjs — ESLint wrapper that auto-injects --suppressions-location tools/eslint/suppressions.json into every lint run. It also detects when suppressions become stale and prints a hint to run pnpm run lint:js:prune-suppressions.
  • tools/eslint/suppressions.json — Central file cataloguing all pre-existing violations by file path and count. New violations are caught as errors; existing ones are suppressed here.
  • Updated lint-file script to use the wrapper.
  • Added lint:js:update-suppressions and lint:js:prune-suppressions helper scripts.

• Fix ESLint config: .cjs files now correctly receive globals.node (adds process, Buffer, etc.) in addition to the existing globals.commonjs. Previously Node.js globals were missing for CommonJS scripts outside of config-file patterns.

Related product discussion/links

Does this pull request change what data or activity we track or use?

No.

Testing instructions

Verify the rule is active:

1. Open any JS/TS file that imports ExternalLink from @wordpress/components — ESLint should report an error: "Use Link from @wordpress/ui with the openInNewTab prop instead."
2. Open any file listed in tools/eslint/suppressions.json (e.g. projects/js-packages/components/components/admin-page/index.tsx) — the existing violation should be silently suppressed and pnpm run lint-file <file> should exit 0.

Verify the suppression workflow:

# Full lint pass — should exit 0 (all violations suppressed or clean)
pnpm run lint .

# After fixing a violation in a suppressed file, prune stale entries:
pnpm run lint:js:prune-suppressions

# To suppress a new batch of violations (e.g. after a rule update):
pnpm run lint:js:update-suppressions

[github-actions]

Are you an Automattician? Please test your changes on all WordPress.com environments to help mitigate accidental explosions.

• To test on WoA, go to the Plugins menu on a WoA dev site. Click on the "Upload" button and follow the upgrade flow to be able to upload, install, and activate the Jetpack Beta plugin. Once the plugin is active, go to Jetpack > Jetpack Beta, select your plugin (Jetpack or WordPress.com Site Helper), and enable the update/use-recommended-components branch.
• To test on Simple, run the following command on your sandbox:

bin/jetpack-downloader test jetpack update/use-recommended-components

bin/jetpack-downloader test jetpack-mu-wpcom-plugin update/use-recommended-components

Interested in more tips and information?

• In your local development environment, use the jetpack rsync command to sync your changes to a WoA dev blog.
• Read more about our development workflow here: PCYsg-eg0-p2
• Figure out when your changes will be shipped to customers here: PCYsg-eg5-p2

[github-actions]

Thank you for your PR!

When contributing to Jetpack, we have a few suggestions that can help us test and review your patch:

• ✅ Include a description of your PR changes.
  
• ✅ Add a "[Status]" label (In Progress, Needs Review, ...).
  
• ✅ Add testing instructions.
  
• ✅ Specify whether this PR includes any changes to data or privacy.
  
• ✅ Add changelog entries to affected projects
  

This comment will be updated as you work on your PR and make changes. If you think that some of those checks are not needed for your PR, please explain why you think so. Thanks for cooperation 🤖

---

Follow this PR Review Process:

1. Ensure all required checks appearing at the bottom of this PR are passing.
2. Make sure to test your changes on all platforms that it applies to. You're responsible for the quality of the code you ship.
3. You can use GitHub's Reviewers functionality to request a review.
4. When it's reviewed and merged, you will be pinged in Slack to deploy the changes to WordPress.com simple once the build is done.

If you have questions about anything, reach out in #jetpack-developers for guidance!

[jp-launch-control]

Code Coverage Summary

This PR did not change code coverage!

That could be good or bad, depending on the situation. Everything covered before, and still is? Great! Nothing was covered before? Not so great. 🤷

Full summary · PHP report · JS report

[anomiex]

Likely best done after #48405 and #48404 land (which updates UI and Eslint libraries)

Agreed. That would save some of the noise in pnpm-lock.yaml in this PR.

[anomiex]

This seems redundant to the setup we already have with tools/eslint-excludelist.json and use of @automattic/eslint-changed.

OTOH, even better is to actually fix problems when introducing a new sniff. 😉

[anomiex]

It would probably make more sense to move this down to the base rules section, near

jetpack/tools/js-tools/eslintrc/base.mjs

Lines 283 to 292 in 482b6b5

	rules: {
	// Set domain from opts, with a bogus default in case it's omitted.
	'@wordpress/i18n-text-domain': [
	'error',
	{
	allowedTextDomain:
	opts.textdomain ??
	"no text domain is set in this in this project's eslint.config.mjs or composer.json",
	},
	],

[anomiex]

Untrue.

[tbradsha]

I haven't done a deep code review, but any reason we're not just cleaning these up directly? Looks like ~250 instances in the suppressions file, and I suspect many of them are the same or similar instances. Could one throw AI at it?

I'd at least recommend trying a cleanup of violations/merge into trunk before adding this.

Also, if I'm skimming correctly, it seems that once a file has suppressed errors of the given type, it won't prevent additional such errors from being added to a file.

My fear is that we'll end up with an additional layer of complexity that only serves to suppress issues we haven't properly fixed.

[simison]

any reason we're not just cleaning these up directly? Looks like ~250 instances in the suppressions file, and I suspect many of them are the same or similar instances. Could one throw AI at it?

That's not trivial as these aren't mere code-formatting lints; code change would be simple'ish, but each component swap usually needs some design decisions and, of course, lots of testing that things continue working, which is a lot of work.

There are four folks replacing old components right now with @wordpress/ui ones. I've observed is a bunch of new PRs adding code with old components, and I've been going around commenting to use the new ones instead. This lint will hopefully guide both humans and agents to use the right ones without oversight.

Note that Gutenberg is using an identical strategy to change their components.

[tbradsha]

I've observed is a bunch of new PRs adding code with old components, and I've been going around commenting to use the new ones instead. This lint will hopefully guide both humans and agents to use the right ones without oversight.

We definitely appreciate the cleanup/modernization efforts! I totally get this, having dealt with Phan cleanup (which uses baselines) and Stylelint (no baselines but rule-by-rule cleanup). We have the same goal, so let's see if we can align on implementation. :^)

Some thoughts:

• @wordpress/use-recommended-components is generally okay. It's good to have rules that prod people to use the proper things.
• The rule currently doesn't have any config options (e.g. it will always throw warnings about experimental components, and those will require suppressions).
• Baselines can easily become a crutch and hide real problems. Along with the added complexity, if a file has one violation, there's nothing preventing someone from adding an additional one, which defeats the goal (people can continue to use bad rules).
• If we instead use eslint-changed, it would prevent the introduction of new violations (checking only changed lines) while ignoring old ones during the cleanup process.
• It'd also be good if the ESLint plugin was modified with some config overrides:
  • disable warnings on specific components
  • allow one to extend the ALLOWLIST so we can use experimental components as desired.
  • allow one to extend the DENYLIST so we can incrementally tighten the set of components we need to replace during a transition period.
  • anything else?

[tbradsha]

As an aside, it seems <Link openInNewTab /> is largely a drop-in replacement for <ExternalLink />, and that makes up over half of the current violations. If it helps, I put up a draft PR that addresses those: #48529

If it's noise/interfering with your current work, feel free to close it. 😄 I also notice you put up a similar PR targeting just Forms here: #48407

[simison]

It'd also be good if the ESLint plugin was modified with some config overrides:

FYI @mirka @ciampo @aduth, some good feedback here from a monorepo maintainer about the component swapover ESLint helper. :-)

[ciampo]

Feel free to open an issue in Gutenberg to discuss / agree on improvements to @wordpress/use-recommended-components, we're happy to collaborate and gather feedback from usage outside of Gutenberg 🙏

[tbradsha]

Feel free to open an issue in Gutenberg to discuss / agree on improvements

Added here: WordPress/gutenberg#78062