Automated Testing: Enforce .tsx for all new React files

[aduth]

What?

Updates ESLint rules to allow enforce react/jsx-filename-extension consistently and limit extensions to only allow .tsx files. Suppresses existing issues through bulk suppressions feature.

Why?

Following these premises that we agree in principle that we want to work toward:

• All JavaScript source code should be written as TypeScript
• All files containing JSX should use a file extension indicating that they contain JSX

This rule provides partial coverage covering React/JSX files, which is better than nothing. It stops the addition of new files (example).

How?

• Configured ESLint rule through project-wide tools/eslint/config.mjs
• Ran npm run lint:js -- --suppress-all to register existing issues in tools/eslint/suppressions.json

Testing Instructions

npm run lint:js passes.

For bonus points, try adding a new .js or .jsx file containing JSX syntax and verify that npm run lint:js fails.

Use of AI Tools

No AI was used.

[github-actions]

The following accounts have interacted with this PR and/or linked issues. I will continue to update these lists as activity occurs. You can also manually ask me to refresh this list by adding the props-bot label.

If you're merging code through a pull request on GitHub, copy and paste the following into the bottom of the merge commit message.

Co-authored-by: aduth <aduth@git.wordpress.org>
Co-authored-by: manzoorwanijk <manzoorwanijk@git.wordpress.org>
Co-authored-by: t-hamano <wildworks@git.wordpress.org>
Co-authored-by: ciampo <mciampini@git.wordpress.org>
Co-authored-by: Mamaduka <mamaduka@git.wordpress.org>
Co-authored-by: jsnajdr <jsnajdr@git.wordpress.org>
Co-authored-by: tyxla <tyxla@git.wordpress.org>
Co-authored-by: youknowriad <youknowriad@git.wordpress.org>

To understand the WordPress project's expectations around crediting contributors, please review the Contributor Attribution page in the Core Handbook.

[github-actions]

Size Change: 0 B

Total Size: 7.92 MB

_{compressed-size-action}

[manzoorwanijk]

Looks good.

[manzoorwanijk]

This file scares the hell out of me. I had set myself as the code owner for tools/* to keep an eye on it, but this file results in my inbox being slammed with emails because this file seems to be changed more often 😄

[aduth]

This is definitely a stress-test of the suppressions feature, given how this touches so many files. But as far as I can understand, it's the entire purpose of the feature, and is designed to support exactly the kind of large-scale "we want this rule but have lots of existing issues" cases like this one. I would definitely encourage adding an exclusion pattern for that code-ownership of yours 😅

I've also got a lot of other ideas for things we could do here that would likely be similar in scale, like converting our "strict" config (which is the same idea as suppressions is solving) and widening dependency-group never rule to apply everywhere (🌶️ ).

[manzoorwanijk]

Excluding this file in #80125

[github-actions]

Flaky tests detected in a2334a5.
Some tests passed with failed attempts. The failures may not be related to this commit but are still reported for visibility. See the documentation for more information.

🔍 Workflow run URL: https://github.com/WordPress/gutenberg/actions/runs/29114692474
📝 Reported issues:

• [Flaky Test] should insert media, convert to blocks, and undo in one step #36123 in /test/e2e/specs/editor/blocks/classic.spec.js

[t-hamano]

What do you think about scheduling the release of this PR for 7.1 Beta1 or later? Final development for Beta1 is currently in full swing, and merging this PR now would force them to switch to TypeScript. Forcing a conversion to TypeScript as an additional task might place a burden on them.

[aduth]

What do you think about scheduling the release of this PR for 7.1 Beta1 or later? Final development for Beta1 is currently in full swing, and merging this PR now would force them to switch to TypeScript. Forcing a conversion to TypeScript as an additional task might place a burden on them.

Sure, it can wait 👍

[t-hamano]

Sorry for the late reply. As the 7.1 release cycle is nearing its end, it might be a good time to reopen this PR. Perhaps we should announce this in the #core-editor channel.

[aduth]

Sure, I'll plan to freshen this up on Monday and merge. I'll likely just rebase, reset suppressions.json to trunk, and re-run npm run lint:js -- --suppress-all. Happily invite anyone else to do that if we'd rather land this before I can get to it.

I'll share a message in Core Slack as well. We could probably tie this with some other high-visibility lint changes like @ciampo 's recent work to eliminate dependency group comments, and perhaps a general note about how ESLint's Bulk Suppressions feature and AI-assisted mechanical changes allow us to do some of these overdue, high-touch lint changes.

[ciampo]

When rebasing we could also "force cancel" every other CI task, to give priority to this PR and land it quickly before potential new conflicts are added?

@aduth , do you also plan to follow-up and migrate the repo in a few passes?

Finally, this is also kind of related with this PR which is part of the "Jest => Vitest" migration stack

[aduth]

When rebasing we could also "force cancel" every other CI task, to give priority to this PR and land it quickly before potential new conflicts are added?

I don't think we're landing new non-.tsx React files with enough frequency that this should be a concern, but I'll at least plan to keep an eye on how this lands on trunk and whatever other changes might land first. I can also do a scan of open pull requests to see what might be affected by these changes.

@aduth , do you also plan to follow-up and migrate the repo in a few passes?

I wasn't necessarily planning to, no. The issue with these is that they're all .js and .jsx files, so it's not just a matter of renaming, but also fixing up existing TypeScript issues and adapting JSDoc-based syntax typing to TypeScript syntax. If there were instances of incorrect .ts file extensions, those would be easy to fix, but there are none.

It's all do-able of course, and AI automation could help, but the bigger concern here was to prevent ongoing introduction of new issues. And I wouldn't want to set the general expectation that someone wanting to prevent new issues should also be encumbered with fixing all existing issues.

Finally, this is also kind of related with this PR which is part of the "Jest => Vitest" migration stack

Yeah, I expect these would still be issues and we'd have to update the filepaths in suppressions to .jsx once that's situated.

I also recall that same issue coming up in #74396 (comment) and needing to create a Storybook plugin to handle those .js files. I wonder if your pull request would allow us to remove that?

[aduth]

I don't think we're landing new non-.tsx React files with enough frequency that this should be a concern, but I'll at least plan to keep an eye on how this lands on trunk and whatever other changes might land first. I can also do a scan of open pull requests to see what might be affected by these changes.

Okay, after checking open pull requests, there's.... a lot 😅 I only went back to PRs with activity since July 27, but found these:

PRs that add JSX in a .js/.jsx file:

• Storybook: Add Story for NavigableToolbar component #68474
• Storybook: Add Story for BlockEdit #68677
• StoryBook: Add story for BlockSettingsMenuControls #68729
• Editor: Add notes display modes to the Options menu #76024
• Notes: Show content summary and block icon #77091
• Fix: Support replace navigation to prevent extra history entries in site editor #77150
• Notes: Open a full searchable emoji picker from the add-reaction button (stacked on #76767) #78176
• Notes: Promote "Add note" to a dedicated block toolbar button #78205
• Add template creation for post format archives #78872
• Try: Linting notes #78880
• Suggest mode: combined feature branch for Playground testing (draft) #78994
• Client-side media: Add video transcoding to web-safe formats #79375
• Client Side Media: Optimize previously uploaded media #79509
• Add textShadow typography support and UI #79584
• Notes: overlay floating notes on space reserved inside the canvas #79864
• Suggest mode 1/9: editor intent (edit/suggest/view) and experiment gate #80427
• Suggest mode 2/9: suggestion storage, REST controller, and provider #80428
• Suggest mode 3/9: block-level capture (attribute and structural) #80429
• Suggest mode 6/9: review UI (Apply / Reject sidebar and summary) #80432
• Suggest mode 7/9: inline live wiring #80433
• Add slider block #80562
• Global Styles: Switch the revisions screen to the DataViews pickerActivity layout #80856
• Global Styles: explore a cascade popover for inherited-value overrides #80993
• Test: Run rendered browser behavior in Vitest Browser Mode #80995
• Show Responsive viewport/state indicator in save confirmation dialog #81027
• Test: Port shared Vitest test environment #81038
• Test: Add Vitest React, Emotion compilation, console, and snapshot parity #81039
• Global Styles: explore the inheritance cascade in the style panels' options menu #81044
• Block Editor: Add text styles for mixed selections #81118
• Block Editor: Refactor withFontSizes to a function component #81126
• Block editor: Surface responsive style status #81368
• [WIP] Media Experiment: Try adding media folders support #81416
• Add the captureControls block support and opt in the quote block #81464
• Editor: Guard taxonomy selectors with REST assign actions #81496
• Post Featured Image: show the Scale control when only a height is set #81524
• Allow removing styles when their controls are disabled #81540
• Style Book: support notes on Style Book examples. #81554
• Editor: Refactor the Options menu to use the Menu component #81564
• POC: Table block with inner blocks #81593
• Block Fields: make the link field control configurable #81636
• refactor MediaUploadModalWrapper to a functional component. #81652
• Move the appender into the block toolbar #81668
• Notes: Leave an already-closed sidebar closed when a suggestion note appears #81671
• Suggest mode: reveal a selected suggestion's marker, and stop unplaced note cards eating clicks #81674
• Suggest mode: explain why formatting is refused across a multi-block selection #81691
• Suggest mode: register the intent shortcuts only where they can be used #81695
• Add extensibility points to Visual Revisions for 3rd party devs - pave the way for experimentation with Future and Public revisions #81710
• Block Library: Add Description List block #81728

PRs that delete or rename a suppressed file:

• Build: Normalize JSX file extensions #80990
• Enable notes spanning multiple blocks #80009
• Notes: Promote "Add note" to a dedicated block toolbar button #78205
• Global Styles: Show a local-override diamond indicator for inherited values and ship them to Core #80649
• Global Styles: Show the inherited-from breadcrumb in the override indicator tooltip #80757

[aduth]

As I've been thinking about how to communicate this, it occurs to me that we don't really consistently document the premises I claimed in the original pull request message. I think most of us could conceptually agree that we should be writing new components as TypeScript, but our documentation doesn't reflect this. And that mismatch might also explain why contributors and agents continue to write non-.tsx files.

Examples:

• packages/README.md claims "Gutenberg does not use the TypeScript language"
• docs/contributors/code/coding-guidelines.md has an entire section on JSDoc-based typing
• docs/contributors/code/getting-started-with-code-contribution.md claims "The Gutenberg project uses TypeScript via JSDoc to type check JavaScript files"

So in parallel to (or prerequisite to?) this work, I'll plan to propose updates to this documentation to better reflect current recommendations. I think this would be important to have as context for sharing in affected pull requests and in Core Slack about why this linting is being added.

[ciampo]

On top of the (much needed) docs refresh, could we use an agent to drop a message in each PR to ask to refactor to tsx instead?

[aduth]

On top of the (much needed) docs refresh, could we use an agent to drop a message in each PR to ask to refactor to tsx instead?

Yeah, my plan is to:

1. Push updated documentation
2. Merge this
3. Communicate the effect in both:
   1. Slack #core-editor message
   2. As a comment in every affected pull request with activity in the past 3 weeks

Step 1 is here: #81763

[t-hamano]

I recall there was a discussion about TypeScript previously. @youknowriad and @jsnajdr might also have some ideas.

• WordPress and Typescript #67781

[Mamaduka]

There was a proposal for this TS adoption - https://make.wordpress.org/core/2021/03/18/proposal-native-typescript-support-in-gutenberg, which received mixed feedback. Might be worth another shot. Lots has changed since 2021 :)

[jsnajdr]

There was a proposal for this TS adoption - https://make.wordpress.org/core/2021/03/18/proposal-native-typescript-support-in-gutenberg, which received mixed feedback.

It's interesting to read these old discussions from 2021, and also the #67781 one from 2024. I don't know if it happened "officially", but today in 2026 TypeScript is fully adopted and there is no pushback about it. It became completely "normal".

Gutenberg has for a long time rejected the .jsx extensions and insisted on using only .js. For unclear reasons, and this conventions might also be obsolete today. I found this discussion from 2020: #21009 (comment). There are pointers to Make Core chat transcripts and old Slack conversations, without any clear conclusions.

Today, there is tooling that gets confused when seeing JSX markup in .js files, most notably esbuild which needs to be specially configured with the loader: { '.js': 'jsx' } to recognize this.

[tyxla]

I agree with this change, and I must say it's been coming for a long time. We've been using TS in the repo for years, so it's time to finally move on. Especially as many of us have been using LLMs for coding, and any tools that have made static analysis easier provide lots of value for agents. It's also cheap enough to maybe temporarily exclude from this rule a package or two that are still not typed.

[youknowriad]

I shared my thoughts on a related PR #81763 (comment)

Overall, I'm in total agreement that we should move fully to TS at this point. A small note on the agents how to keep the nuance in place.

[aduth]

The comments on affected pull requests can be seen in the "referenced" mentions above this comment.

Also, I realized that I merged without copying in the props attributions. Sorry about that y'all 😞 I appreciate everyone's engagement here.

[aduth]

Something to consider for follow-up: The default is to allow .tsx for any file whether it includes JSX syntax or not, but this can be configured to "as-needed" to inversely forbid .tsx if the file doesn't contain any of the syntax. This could be an improvement to clarity, since it would allow someone to use the extension as a clear indicator of whether the file contains JSX syntax.

[Mamaduka]

Maybe we should relax the rules a bit for packages that haven't even started migration to TS?

If you've the ESLint extension enabled in the editor, working on .jsx files isn't great. Most of the entire return statement is red.

While I'm in favor of the effort, this change made DX worse, at least in my case.

Screenshot

[aduth]

@Mamaduka Yeah, that looks pretty bad. And we risk getting to a point where people just start to ignore the noise of the ESLint errors rather than working to treat it with significance of something that should be addressed. It's unfortunate that the rule highlights the entire block rather than e.g. just the opening tag name.

Always up to iterate here, but do you have a specific suggestion on what it means for "packages that haven't even started migration to TS" ? The example you gave is a code snippet in @wordpress/editor, which is TypeScript-enabled and has several .tsx files already. And we should want all new files to be written as .tsx there.

A few specific ideas I could think to explore:

• Some way of overriding the rule to change the nodes that it flags, or even replacing it with something custom.
• Leaning into "new files" as the primary target by more broadly exempting existing .jsx files, perhaps by using ignores file patterns rather than suppressing with suppressions.json. This obviously does a lot less to push people toward updating existing files.

[Mamaduka]

Always up to iterate here, but do you have a specific suggestion on what it means for "packages that haven't even started migration to TS" ?

Maybe packages where TS files are less than X percent? It could be 30, 40 or even 50%.

Reducing the surface of flagged nodes would be great. Though I'm not sure if that's possible from the consumer side.

[aduth]

Maybe packages where TS files are less than X percent? It could be 30, 40 or even 50%.

My concern with this is that it's self-perpetuating. JavaScript files continue to be added because the package is already largely JavaScript, and so exempting on that basis does nothing to help move us toward TypeScript-first. The idea with using suppressions is to prevent new issues immediately because we can't trust that we'll ever get around to a dedicated effort to migrate these packages.

Looking at the data, we're continuing to add JavaScript files to @wordpress/editor at almost double the pace of TypeScript files, even in 2026 (90 new JavaScript files vs. 50 new TypeScript files).

Looking more at the alternative solutions, I actually discovered another solution, which is that the official ESLint extension for VSCode has settings specifically around how suppressions are surfaced, and we could improve the experience with a few lines in a .vscode/settings.json:

	"eslint.bulkSuppression.enable": true,
	"eslint.bulkSuppression.location": "tools/eslint/suppressions.json",
	"eslint.bulkSuppression.severity": "hint"

As a hint, it ends up looking a lot more pleasant, with just a couple dots under the opening tag:

We don't commit .vscode/settings.json to source control currently (I forget where we landed on this last time it was discussed), but as of #77913 we do have setup instructions and even a recommend configuration that could be a starting point for this.

[aduth]

Also, I recognize that guidance is tailored toward VSCode and its derivatives, and not everyone will be following the setup instructions or using VSCode. But the broader point being that bulk suppressions are now a key feature of ESLint and editor integrations surface options around how they're presented, so we shouldn't necessarily assume it'll always be shown as a red squiggly mess.

[Mamaduka]

Thanks for sharing the ESLint extension config; that would definitely fix the issue on my end. Should we also include it in the recommendation config docs?

[aduth]

Should we also include it in the recommendation config docs?

Yep, that feels like a natural place to document it. Updating in #82303