Hey Thomas, great article. Being able to develop a d.ts file from JavaScript with JSDoc type comments is an interesting feature for TypeScript. I have lots of node modules using JSDoc comments. So far I haven't really had any show stoppers from just leaving them with JSDoc comments and not providing a d.ts file. As they are with checkjs enabled in VSCode, full intellisense kicks in for them just as if they did have d.ts files. The only issue I've run into is that sometimes, where I have a JSDoc defined in one file and I import it into another file for use. This works fine in the source code. But sometimes, when the module is imported into another project, TypeScript fails to properly understand the imported JSDoc type and converts it to "any". That's not a show stopper, but it is annoying. Sometimes this works, which means it's a bug.
I currently have and issue open on Github for this: github.com/microsoft/TypeScript/is.... It's currently flagged as in the backlog. If you like, feel free to drop a line or a thumbs up to signal that more people are interested in seeing this bug resolved. Heck, ask some of you buddies at Open WC to chime in as well :-).
Personally, I'd rather not have to provide a d.ts file when the JavaScript already has all the types defined via JSDoc comments. The d.ts is then overwriting what's already there in the JavaScript. That seems like a waste. I'd rather just see TypeScript fix the import bug and properly understand a module's types from the information provided by JSDoc comments.
We had the same experience e.g. while working on the open-wc repository everything was super nice (e.g. full type errors and intellisense). However, our users always had problems using those types. We tried various things - e.g. teaching howto to include only our packages into typescript but ignore the rest of node_modules, or setting maxNodeModuleJsDepth[1]. You can read this PR to see the progress github.com/open-wc/open-wc/pull/277. It was a valid solution but it did put the burden of making it work on the user.
Therefore right now if you distribute a library we recommend to ship definition files. You can now (or soon as it is part of the roadmap) auto-generate those typings in a pre-publish step which means no build step or "disturbance" while developing. Another added bonus is not every typing is possible with JSDoc so if you now need to add some complicated handwritten typings it should be possible.
I think that is the best of both worlds 👍
If at some point TypeScript will support a performant way of importing typings directly from JSDoc in node_modules then this will probably be easier and good enough for most cases 💪
[1]: in 2016 it usually worked just fine as maxNodeModuleJsDepth had a default of 2 - meaning it analyzed node_modules 2 levels deep - but for imho valid performance reasons the default depth was changed to 0 via github.com/microsoft/TypeScript/pu....
For further actions, you may consider blocking this person and/or reporting abuse
We're a place where coders share, stay up-to-date and grow their careers.
Hey Thomas, great article. Being able to develop a d.ts file from JavaScript with JSDoc type comments is an interesting feature for TypeScript. I have lots of node modules using JSDoc comments. So far I haven't really had any show stoppers from just leaving them with JSDoc comments and not providing a d.ts file. As they are with checkjs enabled in VSCode, full intellisense kicks in for them just as if they did have d.ts files. The only issue I've run into is that sometimes, where I have a JSDoc defined in one file and I import it into another file for use. This works fine in the source code. But sometimes, when the module is imported into another project, TypeScript fails to properly understand the imported JSDoc type and converts it to "any". That's not a show stopper, but it is annoying. Sometimes this works, which means it's a bug.
I currently have and issue open on Github for this: github.com/microsoft/TypeScript/is.... It's currently flagged as in the backlog. If you like, feel free to drop a line or a thumbs up to signal that more people are interested in seeing this bug resolved. Heck, ask some of you buddies at Open WC to chime in as well :-).
Personally, I'd rather not have to provide a d.ts file when the JavaScript already has all the types defined via JSDoc comments. The d.ts is then overwriting what's already there in the JavaScript. That seems like a waste. I'd rather just see TypeScript fix the import bug and properly understand a module's types from the information provided by JSDoc comments.
hey Robert, thx for the kind words 🤗
We had the same experience e.g. while working on the open-wc repository everything was super nice (e.g. full type errors and intellisense). However, our users always had problems using those types. We tried various things - e.g. teaching howto to include only our packages into typescript but ignore the rest of node_modules, or setting
maxNodeModuleJsDepth[1]. You can read this PR to see the progress github.com/open-wc/open-wc/pull/277. It was a valid solution but it did put the burden of making it work on the user.Therefore right now if you distribute a library we recommend to ship definition files. You can now (or soon as it is part of the roadmap) auto-generate those typings in a pre-publish step which means no build step or "disturbance" while developing. Another added bonus is not every typing is possible with JSDoc so if you now need to add some complicated handwritten typings it should be possible.
I think that is the best of both worlds 👍
If at some point TypeScript will support a performant way of importing typings directly from JSDoc in node_modules then this will probably be easier and good enough for most cases 💪
[1]: in 2016 it usually worked just fine as
maxNodeModuleJsDepthhad a default of 2 - meaning it analyzed node_modules 2 levels deep - but for imho valid performance reasons the default depth was changed to 0 via github.com/microsoft/TypeScript/pu....