The proposal to intentionally integrate native TypeScript into the Gutenberg The Gutenberg project is the new Editor Interface for WordPress. The editor improves the process and experience of creating new content, making writing rich content much simpler. It uses ‘blocks’ to add richness rather than shortcodes, custom HTML etc. https://wordpress.org/gutenberg/ repository has garnered overwhelmingly positive feedback so far. However there have been some responses that express concerns over introducing a new technology that will be difficult for contributors to understand. This follow up will hopefully address some of those concerns by refining and clarifying some of the ideas in the original proposal.
“Code refactoring should not be done just because we can”
Let’s remember why it’s important to introduce TypeScript and strongly typed functions:
- A better developer experience via automatic code completion (like Intellisense) and other related tools
- More confidence in our code through better static analysis of function internals and their usages
When to use TypeScript for existing code
So, with that in mind, I’d like to propose @gziolo’s method for approaching when to use TypeScript for existing files:
- When it is possible to type something simply with JSDoc, use JSDoc
- If there are complex types, but JSDoc is still sufficient generally for consuming those types, you may extract the complex types into a types-only
types.ts file to be imported into the JSDoc
- If it is not possible to express the types using JSDoc or if the JSDoc will vastly over-complicate the ability to type a function, convert it to TypeScript
It does not cover the case for fully new code in existing packages or new code in the form of completely new packages.
When to use TypeScript for new code
Therefore, for the now rare occasion when a fully new package is added, if all the dependencies are typed, I would like to propose that these should be added in native TypeScript. Likewise, packages that are fully typed or are currently being worked on towards full typing (see #18838 for the list of typed and in-progress packages) and fall into the category The 'category' taxonomy lets you group posts / content together that share a common bond. Categories are pre-defined and broad ranging. of “lower level packages” as described here and in the next section should have new code added in TypeScript.
Lower level packages
A note about “lower level packages.” We can refine this definition slightly by stating that a low level package is a package that:
- Provides a public API; and
- Is not frequently contributed to.
In summary, I’d like to propose the following:
- When refactoring existing code to add types, follow the script above.
- For new packages, use native TypeScript when a) all the packages dependencies are typed and b) when they fall into the category of “lower level packages” as defined above.
- For new code in existing packages, follow the same script above as for refactoring existing code.
When will a decision be made?
I’d like to aim for making a decision 2 weeks from the date of publication of this follow up post. That should give ample time for discussion and questions.