Documentation: Outline third-party developer resources (TypeScript definitions)

[aduth]

Previously: #14308

Related:

• https://make.wordpress.org/core/2019/03/13/javascript-chat-summary-march-12th-2019/
• https://make.wordpress.org/core/2019/04/17/javascript-chat-summary-april-16th-2019/

In the course of above-linked meetings and subsequent feedback windows, it was decided that TypeScript definitions will not be maintained in this repository at this time, due to a combination of the fact that the project is not a TypeScript project, and the concern of the maintenance overhead in assuring and implementing accurate definitions as code changes over time.

That being said, we should be mindful that these definitions could provide an improved developer experience for those who choose to implement TypeScript in their own projects. For that reason, we should be willing to assist these developers in directing them to qualified third-party resources.

Action item: Include in documentation a reference(s) to reputable and well-maintained third-party resources (projects, repositories, blog posts) which could aide a developer who might be in pursuit of or benefit from TypeScript definitions. Ideally, the resources would require minimal maintenance (i.e. would remain reputable and valid over time, so as to avoid the need to continuously reevaluate).

Possible candidates:

• https://github.com/DefinitelyTyped/DefinitelyTyped
  • A canonical third-party resource for TypeScript definitions, including definitions already for @wordpress/scripts
• https://github.com/dsifford/academic-bloggers-toolkit/tree/master/types
  • Includes definitions for a number more @wordpress packages
  • Edit: These have since been migrated to DefinitelyTyped.

[Ciantic]

could provide an improved developer experience for those who choose to implement TypeScript in their own projects

It's not just TypeScript developers. It provides much better experience for JavaScript developers too. Because editors such as VSCode can read type definitions when editing JavaScript and give errors and warnings.

Secondly having official TypeScript definitions would allow to do static analysis on existing blocks. Magnitude of WordPress user base would allow for example WordPress GUI to highlight or give warnings on incorrect usage of function etc. even for those developers who don't care.

TypeScript is not about forcing anyone else to use it, it's about providing great libraries and self documenting code for everyone.

P.S. there is no WordPress definitions in https://github.com/dsifford/academic-bloggers-toolkit/tree/master/types ?

[aduth]

@Ciantic It's my understanding that the types previously located at that link have been merged into the DefinitelyTyped repository.

Having since integrated TypeScript tooling into many of my recent JavaScript (non-TypeScript) projects, I totally agree with you that this can benefit JavaScript developers as well. And to that end, I would very much encourage that any documentation of these resources not frame it as only benefiting TypeScript projects (in contrast with remarks of my original comment).

Worth noting, this issue isn't meant to debate whether those types should exist, but rather to ensure the available options are sufficiently documented.

Separately, I'd actually be interested to revisit the topic of first-party types, though more from the angle of how we can surface good type details from our existing JSDoc, given its interoperability with TypeScript tooling (some recent related work at #17014).

[mikeselander]

Adding my support here for first-party types; the DefinitelyTyped repository is quite out of date and the rate of churn on adding new packages and moving components is way too much to keep up with as a third-party. Keeping these types internally would significantly improve developer experience.

(hopefully this is an appropriate place to flag this; sorry if it's not 😬)

[jameslnewell]

With Typescript 3.7 adding support for the use of --declaration with --allowJs we could generate first-party types from JSDoc!

[ntwb]

I'm also +1'ing this, adding to the #core-js agenda

[aduth]

Noting that this issue is mostly satisfied by the work in #18942, which implements both first-party types output from packages as well as relevant documentation for how TypeScript is used in the project.

The only other thing I'd consider as an optional part of the scope of this issue is to improve documentation concerning how third-party developers can best leverage those types. That said, outside of general awareness of those types existing, and assuming a developer wanting to use these types may already have some familiarity with the general process involved in using types from dependencies, there's ideally not much more to it at that point than it "just working".

[aduth]

WordPress NPM packages will now ship with first-party TypeScript types as of the changes in #18942.