Documentation: Update coding guidelines to recommend TypeScript

[aduth]

What?

Updates documented coding guidelines to explicitly recommend TypeScript syntax.

Related: #80123

Why?

So that contributors and their AI agents understand how new code is expected to be written.

The common convention in new Gutenberg code is to author as TypeScript, and we've spent considerable energy converting code to TypeScript (e.g. #67691). And yet, we continue to have documentation that literally says "Gutenberg does not use the TypeScript language". It's no surprise then that ~50 open pull requests with activity in the last 3 weeks are introducing new .js or .jsx files.

The changes here would be expected to accompany messaging around #80123, so that we have a place to link someone to learn more about how the project uses TypeScript.

Testing Instructions

Review updated documentation for accuracy.

Use of AI Tools

Claude Code + Opus 5 were used in identifying outdated documentation and reviewing content revisions, but the content revisions themselves were written by me.

[aduth]

I recognize that the project doesn't yet use v22.18.0, but this was written intentionally to be both presently accurate and future-proofed with imminent update in to v24 in #72973, with the expressed goal of hopefully encouraging adoption of TypeScript in our own Node scripts as much as possible. (Continued exception being downstream support for environments that are less than this version of Node)

[manzoorwanijk]

I think this one needs some thought. We cannot rely on such .ts yet even if we upgrade to v24 because older release branches still use older versions of Node until they are migrated and they check the latest trunk for such things like CLI. It means that if the CLI adds a .ts file and an older release branch tries to run it, it will fail.

I know if feels like a burden, but we should migrate all the release branches to Node 24 onces we migrate trunk.

Once that happens, we can revisit this section here and explictly recommend writing everything in TS.

[aduth]

It means that if the CLI adds a .ts file and an older release branch tries to run it, it will fail.

I think this is covered by what I mentioned in my comment in #81763 (comment) by "Continued exception being downstream support for environments that are less than this version of Node", where what you're describing is a downstream environment using an older version of Node that doesn't support running TypeScript directly. We would only publish raw TypeScript once we're comfortable setting downstream engines requirement to >=22.18.0, which probably won't be for a while, and yes should probably account for old release branches.

What I'm more focused on here are instances where we have internal (non-published) scripts that we author today as JavaScript that could be TypeScript instead. One example where we've worked ahead here is @wordpress/theme scripts using esbuild-esm-loader to run TypeScript. These are examples where I think we can get rid of esbuild-esm-loader and just run the TypeScript directly.

[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: ciampo <mciampini@git.wordpress.org>
Co-authored-by: manzoorwanijk <manzoorwanijk@git.wordpress.org>
Co-authored-by: jsnajdr <jsnajdr@git.wordpress.org>
Co-authored-by: sirreal <jonsurrell@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.

[aduth]

I considered updating this title to something like "JavaScript (TypeScript)", "JavaScript / TypeScript", or just "TypeScript", but I also don't want to break any existing links to this section of the documentation. GitHub allows renaming an anchor via <a name> so we could preserve existing anchor, but I'm not sure this would work in how the documentation is mirrored into the developer site.

And frankly, I don't think it's wrong to continue titling the section "JavaScript", as ultimately JavaScript continues to be the basis of the language we write (TypeScript being a superset). And who knows, maybe some day this will be JavaScript syntax 🤷

[github-actions]

Flaky tests detected in 0a7c2a1.
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/32061883582
📝 Reported tests:

pre-publish panel does not dirty the default category record in /test/e2e/specs/editor/collaboration/http-only/collaboration-taxonomy-record-dirty.spec.ts, passed after 1 failed attempt.

Error: expect(received).toBe(expected) // Object.is equality

Expected: false
Received: true
    at /home/runner/work/gutenberg/gutenberg/test/e2e/specs/editor/collaboration/http-only/collaboration-taxonomy-record-dirty.spec.ts:112:26

[ciampo]

We may want to update the folder structure in this file, since it mentions creating index.js files?

[aduth]

We may want to update the folder structure in this file, since it mentions creating index.js files?

I updated .js file extensions to .ts in 425a55c. Interestingly many of the folder structure examples were already .ts and .tsx, so these remaining few address the inconsistency.

[manzoorwanijk]

Looks great. Thank you for doing this.

[manzoorwanijk]

I think this one needs some thought. We cannot rely on such .ts yet even if we upgrade to v24 because older release branches still use older versions of Node until they are migrated and they check the latest trunk for such things like CLI. It means that if the CLI adds a .ts file and an older release branch tries to run it, it will fail.

I know if feels like a burden, but we should migrate all the release branches to Node 24 onces we migrate trunk.

Once that happens, we can revisit this section here and explictly recommend writing everything in TS.

[jsnajdr]

All new code in Gutenberg is expected to be written...

Just a little nit: let's write this as:

All new code in Gutenberg should be written

Reading the discussion about possible exception reminded me of how RFC standards specify mandatory and recommended behavior: using the MUST, SHOULD and MAY verbs as defined in RFC 2119.

SHOULD is defined as:

This word, or the adjective "RECOMMENDED", mean that there may exist valid reasons in particular circumstances to ignore a particular item, but the full implications must be understood and carefully weighed before choosing a different course.

That's what we want to say here: you are expected to write new source files as .ts, unless you have a specific, well-understood reason not to. If you want to use .js, ok, but you must have good reasons for that.

[aduth]

Just a little nit: let's write this as:

All new code in Gutenberg should be written

Updated to "should" language in c1d1dde.

[sirreal]

Happy to see this direction.

[sirreal]

🗑️

[youknowriad]

I'm in support of this direction.

One small caveat that I'm wondering about is that sometimes Agents are too literal. So for instance in a heavy JS package that is yet to be typed, it's sometimes not a reasonable ask to have a new file being a TS file and full of TS ignore (all the imports). Do you think agents would be smart enough to continue using JS in these cases?

Something similar happened to me recently about CSS imports for instance where the nuance was hard to grasp for the agent.

[tyxla]

"All new code" can be a bit tricky if that new code is in a js/jsx file. Does that mean we need to refactor the file to ts/tsx? We might want to cover that case.

[jsnajdr]

What we want to say is that the default way to write new code is TypeScript, but there are many exceptions. You should always apply your own judgment.

• many packages are still overwhelmingly JavaScript and they shared data structures are not well-typed. block-editor, block-library, editor. Adding a new TS file can result in many type errors caused by the imported code. It might be better to keep the new file as JS.
• while adding new code to an existing JS file, consider migrating it to TS first. Sometimes it will be trivial and an easy win, sometimes a massive distraction not worth doing.
• there can be tooling scripts (Node scripts, bundler or Babel plugins) that either need to run as plain JS, or are not worth typing, for example, the libraries they import are not well-typed anyway.

The general expectation is that the new code being TypeScript is not expected to cause some big trouble. It should feel natural and smooth. If it doesn't, it means that some bigger migration or framework adjustment needs to happen first.

[youknowriad]

I think this nuance about applying judgement should be mentioned in the guidelines, otherwise agents will be too literal and do all sort of hacks to avoid JS.

[aduth]

I updated in e69b841 to incorporate two additional exceptions in addition to the one that already existed:

• If authoring new code in an existing .js or .jsx file. Migrating existing files to the equivalent .ts or .tsx is encouraged if it is trivial to do so.
• If authoring new files in a package which is largely untyped, such that the new file would not have reasonable access to existing package typings.