Eslint: adopt @wordpress/use-recommended-components

[simison]

Depends on #53004

Proposed changes

Enables @wordpress/use-recommended-components with allowUseWithCaution: true setting as an error-level ESLint rule monorepo-wide (in tools/js-tools/eslintrc/base.mjs). This encourages migration away from deprecated or experimental @wordpress/components exports toward stable @wordpress/ui components, and allows early-adopting some of the new "use with caution" components.

Existing violations are tracked in tools/eslint-excludelist.json, using the monorepo's existing @automattic/eslint-changed workflow.

Every current usage of @wordpress/ui in Jetpack is on the allowlist.

Allowed @wordpress/ui

The use-recommended-components rule does not allowlist @wordpress/components. Any import from that package is allowed unless it is on the denylist below. The allowlist is @wordpress/ui. These lists are from Gutenberg trunk, which is ahead of the published @wordpress/eslint-plugin 27.0.0.

Allowed @wordpress/ui

These pass with no option set:

Autocomplete, Badge, Calendar, Card, Checkbox, CheckboxControl, CheckboxGroup, Collapsible, CollapsibleCard, ControlWithError, EmptyState, Field, Fieldset, Icon, Input, InputControl, InputLayout, KeyboardShortcutDescription, KeyboardShortcutDisplay, Link, Notice, Progress, Radio, RadioGroup, RadioGroupControl, RangeCalendar, SearchableChipSelect, SearchableChipSelectControl, Select, SelectControl, Skeleton, Spinner, Stack, Switch, SwitchControl, Tabs, Text, Textarea, TextareaControl, Tooltip, ValidatedInputControl, ValidatedTextareaControl, ValidityIndicator, VisuallyHidden, useKeyboardShortcutProps

Allowed due to allowUseWithCaution: true

AlertDialog, Breadcrumb, Button, ButtonLink, Combobox, Dialog, Drawer, IconButton, Menu, Meter, Popover, SearchableSelect, SearchableSelectControl

Disallowed @wordpress/components

Disallowed	Recommended instead
ExternalLink	Link from @wordpress/ui, with openInNewTab
__experimentalDivider	A separator subcomponent such as Menu.Separator from @wordpress/ui, or custom CSS using @wordpress/theme tokens
__experimentalElevation	Elevation tokens from @wordpress/base-styles
__experimentalGrid	Custom CSS
__experimentalHeading	Text from @wordpress/ui
__experimentalHStack	Stack from @wordpress/ui
__experimentalInputControl	InputControl from @wordpress/ui
__experimentalScrollable	Custom CSS
__experimentalSpacer	None named; planned for deprecation
__experimentalSurface	Custom CSS using @wordpress/theme tokens
__experimentalText	Text from @wordpress/ui
__experimentalView	None named; planned for deprecation
__experimentalVStack	Stack from @wordpress/ui
__experimentalZStack	Custom CSS
Animate	Custom CSS animations using @wordpress/theme motion tokens
Badge	Badge from @wordpress/ui
BaseControl	Field from @wordpress/ui. Visual label: Field.VisualLabel. Group legend: Fieldset and Fieldset.Legend
Card	Card.Root from @wordpress/ui
CardBody	Card.Content from @wordpress/ui
CardDivider	None; a divider is no longer a standard card pattern
CardFooter	None; a footer is no longer a standard card pattern
CardHeader	Card.Header from @wordpress/ui, optionally Card.Title
CardMedia	Card.FullBleed from @wordpress/ui
CheckboxControl	CheckboxControl from @wordpress/ui
Flex	Stack from @wordpress/ui where it fits; otherwise custom CSS
FlexBlock	Stack from @wordpress/ui where it fits; otherwise custom CSS
FlexItem	Stack from @wordpress/ui where it fits; otherwise custom CSS
FormToggle	Switch from @wordpress/ui
Notice	Notice from @wordpress/ui
ProgressBar	Progress from @wordpress/ui
RadioControl	RadioGroupControl from @wordpress/ui
ResponsiveWrapper	CSS aspect-ratio
TabPanel	Tabs from @wordpress/ui
TabbableContainer	None named; planned for deprecation
Tabs	Tabs from @wordpress/ui
TextControl	InputControl from @wordpress/ui
TextareaControl	TextareaControl from @wordpress/ui
ToggleControl	SwitchControl from @wordpress/ui
Tooltip	Tooltip from @wordpress/ui
VisuallyHidden	VisuallyHidden from @wordpress/ui

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-excludelist.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.

pnpm run lint

[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!

---

Jetpack plugin:

No scheduled milestone found for this plugin.

If you have any questions about the release process, please ask in the #jetpack-releases channel on Slack.

---

Boost plugin:

No scheduled milestone found for this plugin.

If you have any questions about the release process, please ask in the #jetpack-releases channel on Slack.

---

Starter Plugin plugin:

No scheduled milestone found for this plugin.

If you have any questions about the release process, please ask in the #jetpack-releases channel on Slack.

---

Protect plugin:

No scheduled milestone found for this plugin.

If you have any questions about the release process, please ask in the #jetpack-releases channel on Slack.

---

Videopress plugin:

No scheduled milestone found for this plugin.

If you have any questions about the release process, please ask in the #jetpack-releases channel on Slack.

---

Automattic For agencies client plugin:

No scheduled milestone found for this plugin.

If you have any questions about the release process, please ask in the #jetpack-releases channel on Slack.

---

Classic Theme helper plugin plugin:

No scheduled milestone found for this plugin.

If you have any questions about the release process, please ask in the #jetpack-releases channel on Slack.

---

Paypal Payment buttons plugin:

No scheduled milestone found for this plugin.

If you have any questions about the release process, please ask in the #jetpack-releases channel on Slack.

[jp-launch-control]

Code Coverage Summary

No summary data is available for parent commit eb06e12, so cannot calculate coverage changes. 😴

If that commit is a feature branch rather than a trunk commit, this is expected. Otherwise, this should be updated once coverage for eb06e12 is available.

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.

[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

[simison]

@anomiex I've updated the PR to use the existing custom tools/eslint-excludelist.json.

FYI, current failures in the lint job are known and described in the PR description. I'm still working on those aspects.

Can you clarify a couple of developer experience nuances just so that I understand correctly how the custom Jetpack Eslint workflow works, vs the regular Eslint functionality:

• If folks modify files on the exclusion list and changes are unrelated to components, what happens? Will they need to fix the whole file if the old violations are now on new line numbers?
  • (That would be unfortunate and not exactly the goal of the component lint; it's fine to keep using the old components, we just want to avoid using them in new work going forward.)
• If I understand right, new lint violations on these exclusion files will continue getting flagged?
• Once we update upstream Eslint configs (will likely be each version bump now with work actively going to both @wordpress/components and @wordpress/ui); the files on the excluded files might become clean and existing files "dirty"; the current setup won't notice the changes on excluded list but it does notice changed lint requirements on other files?

[simison]

The new allowUseWithCaution option and also stable/recommended components list updates have brought us to a point where enabling this Eslint rule is now again reasonable in the repo to direct AI to use recommended components intead of legacy ones. Depends on WP deps update (#53004) and this branch is targets that branch but I'm planning to merge only after the WP deps one is merged first.

Good for a review! @anomiex @tbradsha

[anomiex]

Looks like it could use a rebase onto the current version of #53004.

Beyond that, my earlier comment still holds for me:

Otherwise it seems reasonable, with the hope that someone is going to work through the backlog of files needing fixing.

[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