WordPress and Typescript

[youknowriad]

We've introduced Typescript in WordPress packages for over 3 years now. Core contributors are now more familiar with the language and have formed a better opinion on it, our last official statement on Typescript usage in WordPress is now a bit outdated. It is time to consider our usage of TypeScript again, better document our approach to TypeScript, any guidelines... Hopefully, after we discuss this a little bit, we make an update to our documentation and publish a make/core P2 post summarizing the decisions.

State of packages:

• A number of low level packages embraced typescript: Components, DataViews, Compose, Fields...
• Some packages started to partially adopt TypeScript: Editor (in relation to DataViews), CoreData
• Most new TypeScript code is written today in *.ts files and some old code style rely on TS in JSDocs.
• Some complex and important low level packages are still not typed properly: blocks, rich-text, block-editor.

Personal perspective:

I've long been very reticent towards TypeScript, I've always seen its value when it comes to define structures (think DataViews API, Block API...) but less when it comes to components props (especially when there's multiple level of component abstractions: spreading props down multiple levels).

That said, as I started to get more and more familiar and embrace it more in the project per the previous proposals, I've changed my mind a lot. I know think that it's actually valuable for any package and would encourage its usage more broadly.

Proposal

Based on this, I would like to propose that we start thinking about our next steps here with the goal of: Increasing our typescript coverage at a higher pace.

The approach I'm proposing is the following:

• Encourage the contributors to use TS for all/most new files when possible, even within packages that are not typed yet.
• How? By embracing that *.ts files should be typed and checked in these packages while *.js shouldn't. We can achieve this simply by setting "checkJs": false in tsconfig.json. This allows a slow but consistent migration to typescript as we iterate on existing packages.
• Developers doing the former will face situations where they'll import JS files from TS files. Our approach there should be sensible: If it's just a single JS import, it should be ok to rely on @ts-expect-error. If it's a high number of untyped imports, it's probably not the right moment to type the file we're working on.
• Avoid big scale migration of all packages: This is going to create a lot of noise in open PRs... instead focus on typing as we fix bugs and implement features. Some targeted package migrations can be beneficial though: Especially the low level ones (blocks, rich-text)

In parallel to that proposal, there's some work to be done to better guide developers writing TypeScript for WordPress. Better Typescript documentation in the context of the project. Things like: Any or unknown, interface or type, Centralized types.ts file per package or not.

(I don't think this last part of the proposal, the documentation aspect, deserves a lot of discussion, this discussion can happen directly in the PR adding the docs. We just need a champion there to lead the documentation efforts)

cc @WordPress/gutenberg-core

[ramonjd]

This would be the perfect opportunity to ask for a review of:

• Edit Site: Add tsconfig.json validation for package #67406

😄

By embracing that *.ts files should be typed and checked in these packages while *.js shouldn't. We can achieve this simply by setting "checkJs": false in tsconfig.json. This allows a slow but consistent migration to typescript as we iterate on existing packages..

Wondering if there's a non-complex way to exclude existing JS dirs while including new *.ts, *.tsx files in tsconfig.json , e.g., some funky globs in "includes/excludes" and/or paths in "files"? Maybe it's overthinking. At least we could guide folks in the docs to ensure the compiler knows about new files.

[youknowriad]

Wondering if there's a non-complex way to exclude existing JS dirs while including new *.ts, *.tsx files in tsconfig.json , e.g., some funky globs in "includes/excludes" and/or paths in "files"?

This is what the "checkJs": false I suggested is about.

[ramonjd]

I was only asking as I noticed TypeScript will still perform some level of type checking on imported JavaScript files in TypeScript files, even if checkJs is set to false. I could have been doing things wrong in the early commits of #67406, as the compiler was attempting to create a basic type definitions for
imported js files modules. Maybe because they weren't 100% es6 modules. 🤷🏻

Anyway, all good! We have plenty of TS masters 👍🏻

[youknowriad]

Yes, I'm not sure about the details of why it's not consistently working but I know that I've used it in both "dataviews" and "editor" in the past to do the incremental support. cc @sirreal would know best :)

[sirreal]

What you described in #67781 (reply in thread) is how it should work, JS can be excluded from type checking by disabling checkJs.

I see in the linked PR is usage of an untyped import from another package in TypeScript files which is causing problems because the TypeScript file has no way to understand what it's importing.

Even if checkJs is disabled, when a TypeScript file imports from a JavaScript file it needs to be able to access types somehow (possibly depending on other strictness configuration). I believe it will disable checks on the JS file and just try to understand the types it needs.

For example, I'd expect it to allow /** @type {number} */ export const s = "string"; from a JS file, where a TypeScript file could use that "number" value without any errors.

[justlevine]

Love and agree with practically everything here.

To add: I was also initially in the anti-ts camp, but have come around in the last year or so. My primary original concerns were about the additional barriers of entry to contributing on a project that's already significantly disjoined from the rest of the WP project. I believe these concerns are mostly tempered as:

• TS has seen huge adoption,
• IDEs, Linters have become much more helpful, and even free chat LLMs are very capable at explaining and providing guidance on even the more complex TS syntax issues.
• PHP itself (and WP by extension) is becoming more explicitly type-safe, so even if the syntax is unique the concepts (like avoiding mixed/any, differentiating between undefined/void/null, typing iterables) are not.

(I don't think this last part of the proposal, the documentation aspect, deserves a lot of discussion, this discussion can happen directly in the PR adding the docs. We just need a champion there to lead the documentation efforts)

Disagree here - or rather I'd made a distinction between establishing best patterns and documenting them. E.g. changing any to unknown is a breaking change, and better to start off using ComponentProps<typeof SourceOfTruth> than to be saddled with a bunch of export types we gotta keep around for back-compat reasons.

[youknowriad]

Disagree here - or rather I'd made a distinction between establishing best patterns and documenting them. E.g. changing any to unknown is a breaking change, and better to start off using ComponentProps than to be saddled with a bunch of export types we gotta keep around for back-compat reasons.

It's definitely a discussion worth having. I just didn't want it to be the main thing discussed here. It's a bit less important in the global scheme of things :)

[matiasbenedetto]

I've long been very reticent towards TypeScript, I've always seen its value when it comes to define structures (think DataViews API, Block API...) but less when it comes to components props.

Could you please explain the reasons that made you change your mind, @youknowriad ? I think that would enrich the conversation around the proposal.

[matiasbenedetto]

Thanks for adding more rationale about the proposal's upsides 👍. Everything has trade-offs. What are, from your perspective, the downsides of converting/expanding the Gutenberg codebase to TypeScript?

[youknowriad]

Everything has trade-offs. What are, from your perspective, the downsides of converting/expanding the Gutenberg codebase to TypeScript?

• A small learning curve for people that are new to the language.
• Having to deal with untyped dependencies (rare these days)

[jsnajdr]

One thing is that I realized the difficulty we have right now in the components package is not because it's using typescript, it's because it's over-engineered IMO.

There is a lot of JavaScript code that when untyped, is very simple and intuitive. But adding types to it is a nightmare. It's almost like TypeScript is a different language, not just a JavaScript extension. In the sense that what is easy to say in JS, can be very hard to say in TS.

One example is Redux. Try to type the dispatch function correctly. Every middleware modifies the type! Or try to type your state when it's composed from tens of subreducers, and to have perfect types for all selectors. Also very hard. We have and will have a lot of trouble typing @wordpress/data correctly.

Another example are higher-order components in React. A simple concept when not typed, but reliably typing a withSomething function that accepts a component and returns another is hard. You have a type transformation that transforms a type A into an "augmented" type B. By adding props or removing props. What if the outer component has a prop of the same name as one injected by the HOC and their types conflict? What if the components are generic, with a type parameter T? Then you're transforming a generic type into another generic type. It gets very meta.

Then you can have an as prop on a component, telling it what low-level element it should use. Like <Box as="div" className="foo" bar="baz" />. Such a Box component has its native props (bar) but also the props of the as component (className). Again, this is very convenient and intuitive and uncomplicated without types, but very hard to type.

If you write something in TypeScript from scratch, you will naturally avoid all these complications and will write your code in a completely different style. While in an existing JS codebase, it's easy to fall into the trap thinking that it must be easy to "just add types". And blame the original authors when it's not easy. But it's not necessarily that the code is inherently bad, it's just written in a different, untyped language.

[adamziel]

Or try to type your state when it's composed from tens of subreducers, and to have perfect types for all selectors. Also very hard. We have and will have a lot of trouble typing @wordpress/data correctly.

While that's true, using jsdoc for expressing these types as Gutenberg did for years is much harder than using TypeScript.

[youknowriad]

@jsnajdr Agreed some code patterns are harder to type than others, specially if the code was not thought for TS from the start. but I don't think that prevents from being critical about our code base, not blaming anyone. We all at one point or another participated in creating bloated code, or over-engineered code, that doesn't always mean that it was the wrong decision at the time but as time pass, we should be capable to take a step back and analyze what patterns are working, what others are not and are making maintainability and clarity worse. We should be able to adapt. (Btw, on a personal note, I think we should all take inspiration from the work you're doing on Slot/Fill and related things and be able to balance shipping features and improving code quality)

That said, I think we're derailing a bit from the purpose of this discussion :) .

[Mayank-Tripathi32]

I really appreciate the idea of having everything typed. It simplifies learning the codebase, clarifies expectations, and helps identify potential issues faster. When I started working with Gutenberg, I found Dataviews the easiest to understand because there was no guesswork when examining a small portion of the code. The types made it clear what functions or components expected, making navigation and comprehension much smoother.

Regarding the trade-off "A small learning curve for people that are new to the language,” I have a slightly different perspective. In my opinion, having a learning curve is beneficial because anyone interested in contributing will first need to understand the codebase and learn the basics, rather than submitting PRs without a solid grasp of best practices. This approach helps prevent code issues, and make code reviews much easier.

As a new developer, I believe most people will get comfortable with TypeScript fairly quickly and appreciate the time it saves when diagnosing issues. Given the growing popularity of TypeScript and its widespread adoption alongside frameworks like Next.js, there is ample support and extensive documentation available to help developers understand the codebase and overcome any learning challenges.

Lastly,
I’m very interested in helping with a gradual migration of current codebase to TypeScript. If anyone is willing to review my work and provide feedback, I’d be excited to contribute!