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.
In this proposal, nothing changes for consumers of Gutenberg packages (like block Block is the abstract term used to describe units of markup that, composed together, form the content or layout of a webpage using the WordPress editor. The idea combines concepts of what in the past may have achieved with shortcodes, custom HTML, and embed discovery into a single consistent API and user experience. developers). JavaScript JavaScript or JS is an object-oriented computer programming language commonly used to create interactive effects within web browsers. WordPress makes extensive use of JS for a better user experience. While PHP is executed on the server, JS executes within a user’s browser. https://www.javascript.com/. remains the primary way of interacting with the API An API or Application Programming Interface is a software intermediary that allows programs to interact with each other and share data in limited, clearly defined ways.. If block developers opt-in to use TypeScript for their own projects, we will gradually improve the tools and typings to make their experience better.
Okay, let’s answer the question: when will TypeScript be used in the repository? To answer this question, we must first keep in mind that we do not refactor without a good reason and certainly not for refactoring’s sake alone: https://developer.wordpress.org/coding-standards/wordpress-coding-standards/javascript/#code-refactoring
“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:
- The default is to use JavaScript
- 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
This, of course, only applies to the places that support native TypeScript anyway which is currently limited to mostly lower level packages, which are the primary initial targets for typing. This falls in line with the original proposal’s statement that “the majority of Gutenberg will probably forever remain as plain old JavaScript.”
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.
Otherwise, new code should follow the the same logic laid out above for existing files, essentially only using TypeScript when absolutely necessary, preferring JSDoc typed JavaScript.
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.
Summary
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.
If this is accepted by the community then I will open a PR to update the JavaScript coding guidelines in the repository to reflect this. The update will include the script set out above.
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.
#javascript
