@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.
the thing is you generally don’t develop open language specific framework, to merge with third party with strong commercial bias ( typescript is basically owned by Microsoft ).
So yes if you want to become Microsoft bitch. You can make a three.js version integrating their baby. But I wish this could stay in another repo.
You do know that mrdoob works for google? I’m not sure about other maintainers but i think they’re also paid by google, perhaps on a contract basis. I think this was one of the big reasons why three made a huge push towards VR at one point, a long time ago.
TS is microsoft as much as three is google. They are both opensource.
Yes, that’s also why we get these regular crazy updates.
But google never enforced their tool inside the source. You don’t need google chrome to run three.js.
TS is a whole other beast, this is basically code poisoning. If you are not a TS user.
Also LLM would probably start to push it. Because they often consult three source (like all the time)
I don’t understand the analogy. Everyone who uses typescript can still use @types/three . You don’t need to use edge to run typescript, in fact, you don’t even run typescript. Furthermore, even though its not the goal, there is a chance that you do have some typescript via these JSDoc annotations.
Typescript is a tool that helps you write type safe javascript.
The output of TSC is type safe JavaScript compliant to whichever standard you want it to be.
Nobody needs to rewrite threejs to make it work with TypeScript.
The OP was probably questioning why the type definitions/declarations aren’t included with each new release of Threejs.
The reason is likely because it takes time to write/update *.d.ts files, and it would delay each next revision of Threejs.
However, there is a separate project, that everyone is familiar with called @types/three
npm install @types/three
And if you are using these type definitions/declarations with TypeScript, then it can help you from scratching your head over making silly mistakes like this.
const material = new THREE.MeshNormalMaterial({})
material.color.set(0x00ff00)
TypeScript isn’t your enemy. You know you’re part of a cult when you feel eternally attacked by supplementary ideas.
