@mrdoob@Mugen87@sunag@donmccurdy@gkjohnson
three.js is full of JSDoc annotations but there are many missing pieces, especially with TSL and the @abstract prototype chains for meshes and materials. For example, extending the different node material types does not work out of the box (related to the setupLightingModel covariant return type) and requires maintaining a fork of three.js to pass TypeScript checks.
What is the best way to approach three.js when wanting to have proper typing? What are your thoughts on @types/three? Will three.js itself ever include accurate .d.ts files?
No. We have made the decision years ago to not support TypeScript in the repository.
If you have a feature request or a general question regarding TS type declarations, it’s best to create an issue at the @types/three GitHub repository.
I looked at the source recently though, and with the JSDocs it actually feels like it went back to TS? All of the methods seem covered by annotations, along with much of what goes on inside. The internet says that it is basically typescript underneath, except the syntax is such that it can easily be ignored.
I too find this a bit confusing and feel that some clarification would make sense. I always saw @types/three as a different project, one that has to lag a bit behind three, by design. Now there is a chance that @types and JSDoc annotations may even be at odds?
It’s similar with three’s “react support”. I never thought that react had anything to do with three, but it may very well be that nowadays more people are interacting with three through three-react fiber.
To be pedantic, I am actually still using plain JavaScript in my three.js project. I just have JSDoc type checking enforced with checkJs: true in tsconfig.json.
JSDoc syntax found in three.js comments (e.g. /** @someTag someValue */) was originally designed to document JavaScript, hence the name. It is not, on its own, a useable type definition syntax. There are a couple “flavors” of JSDoc created later to support type checking. In particular Closure Compiler and TypeScript (the compiler, not the language) each have a somewhat customized JSDoc syntax to support their type checking on JavaScript source code.
It is possible to generate TypeScript’s .d.ts files from JSDoc annotations, but creating type definitions at the same level of quality as those generated from TypeScript source files, or from hand-written .d.ts files, would involve writing considerably more JSDoc comments than three.js source currently includes… I think if @types/three’s current maintainers would like to propose some reasonably-scoped changes to the JSDoc comments in the the three.js codebase, in order to support their maintenance of the type definitions, that could be a good conversation. The Svelte.js project currently uses JSDoc to generate type definitions, that’s the main example of this approach that I’m aware of.
Disclaimer on that approach: It can be difficult to generate accurate .d.ts files from JSDoc in JavaScript source files, if you are not also using the TypeScript compiler to run type checks when maintaining that codebase.
***
Independently of all that … I suspect that strict and easy-to-use types for TSL specifically is not trivial, just given how dynamic TSL is, almost regardless of whether you’re writing TypeScript source or .d.ts declarations or JSDoc. Someone would need to spend some time investigating a path forward on that one, and to make a proposal.
