TypeScript support

[devpaul]

I've written ambient declarations for a-frame in order to provide type support for TypeScript. I created a ticket a few months ago (DefinitelyTyped/DefinitelyTyped#11696) to track interest and recently I've been asked to merge these typings in to a standard place for consumption.

It would be great to include TypeScript support w/ A-Frame. This doesn't require any code to be rewritten, just include a .d.ts file like this as part of the release and add some tests to exercise the typings against A-Frame.

Benefits include:

1. IDE support via intellisense and better code completion for A-Frame and it's dependencies (e.g. Three.js) (this is great for new users)
2. Eliminates common errors stemming from typos and misuse
3. Including in A-Frame would keep typings current w/ releases
4. Zero runtime const (ambient declarations are not part of executed code)
5. Better support for Angular and TypeScript users

By including typings w/ A-Frame, TypeScript users will immediately have types available and it would have no effect on non-TypeScript users.

I'm happy to answer any questions. If there's enough interest I'll submit a PR.

[devpaul]

I forgot to mention, if people would like to experiment w/ current ambient declarations there's a boilerplate here: https://github.com/devpaul/ts-dojo-aframe-boilerplate

[ngokevin]

Thanks for filing. I'd rather this be maintained outside since it benefits a smaller number of users but adds more maintenance to the project. A-Frame's API is also primarily through the DOM and already has a type system with component schemas so the benefit seems minimal.

[donmccurdy]

A-Frame's API is also primarily through the DOM and already has a type system with component schemas so the benefit seems minimal.

I think the point is less that A-Frame's API especially needs a type system, and more that A-Frame users may want to use TypeScript in their own applications (for whatever reason), and doing so is extremely painful if your dependencies do not have correct typings. For example, the BabylonJS ecosystem is TS, and it would be nice to accommodate those users coming from that background.

For the question of whether those typings should be in A-Frame's repo or not:

1. If typings were in the repo, how are they served? Is there an entry in package.json like "typings": "typings.d.ts" or something? Or are they bundled into the build explicitly?
2. By adding typings to the repo, do we get any advantage for maintaining them? Specifically, could typings be generated from our JSDoc automatically?

If the .d.ts file will have to be updated by hand regardless, then I think it would be better to maintain it outside of this repo — none of us are using TS here, and it's likely to go stale. If we can automate the typings here in a way that wouldn't be possible in another repo, I'm open to that.

[devpaul]

If the .d.ts file will have to be updated by hand regardless, then I think it would be better to maintain it outside of this repo — none of us are using TS here, and it's likely to go stale.

I think this is the key point. If there's sufficient community support then it's worthwhile to add typings as part of A-Frame. If support and upkeep may be an issue then it's OK as a separate project. The biggest drawback to this is the release of typings wouldn't be tied to A-Frame, which isn't huge if the community isn't yet there.

A-Frame's API is also primarily through the DOM

I love A-Frame's usage of the DOM. Typings would lower the barrier to entry as users start working directly with elements or writing custom components. Having Threejs typings for object3d and the other more complex dependencies of A-Frame has helped me quite a bit.

If typings were in the repo, how are they served?

Bundled typings are indicated via a types entry in package.json that points to a file (e.g. aframe.d.ts) distributed with the package. Docs: https://www.typescriptlang.org/docs/handbook/declaration-files/publishing.html

By adding typings to the repo, do we get any advantage for maintaining them

When we added typings to Dojo we identified a number of bugs in the code and tests that didn't correctly test the code. We did this by writing a script to convert our tests to ESM module format and then used TypeScript to compile the tests against the typings we created by hand.

could typings be generated from our JSDoc automatically?

While there are projects out there that attempt this, I wouldn't recommend it. The main benefit of adding typings to a project like A-Frame is to lower the barrier to intermediate development when users start writing custom entities and components and need to deal w/ threejs or other dependencies. Automated solutions aren't typically very good at linking to external projects (good linkers are hard to write).

If we can automate the typings here in a way that wouldn't be possible in another repo

If typings are published in DefinitelyTyped they'll be available as a separate package. TypeScript users could install it via npm i @types/aframe. The biggest drawbacks here is the release of types will lag A-Frame and since typings are separate their versions are not tightly coupled. A major API change and a lagged release of typings will stall TypeScript users from using the latest A-Frame.

But everything is trade-offs, right? If there's enough community support to warrant adding typings to A-Frame, or there enough of a benefit to A-Frame to include them, then we should. Until there's an overwhelming call for it I'm happy to publish typings in DefinitelyTyped.

[dmarcos]

I'm in favor to keep it separate as well, keep an eye on adoption and reevaluate in the future. I don't know much about TypeScript but for those that want to develop their own components, is there space for ats-aframe-boilerplate? That bundles the t.ds for you with your components? Is there anything actionable in this issue? Can we close / archive? Thanks for giving a Typescript perspective using a-frame.

[ngokevin]

Going to close for now. Thanks!