DEV Community

Generating TypeScript Definition Files from JavaScript

Thomas Allmer on September 04, 2019

At open-wc, we are big fans of buildless development setups. We have a post or two about it 😄. We believe that the future is all about coming back ...

Read full post

Evan Plaice • Sep 24 '19

TSC seems to be blocking typings creation on vanilla JS now

The error:

error TS5053: Option 'allowJs' cannot be specified with option 'declaration'.

My config:

  "compilerOptions": {
    "target": "esnext",
    "noEmit": false,
    "declaration": true,
    "allowJs": true,
    "checkJs": true,
    "emitDeclarationOnly": true
  }

Here's the issue on GH:
github.com/microsoft/TypeScript/is...

Thomas Allmer Open Web Components • Sep 25 '19

yes totally correct - it's written here dev.to/open-wc/generating-typescri...

Basically that means that currently there is an official TypeScript branch that allows it but might still take some time (as far as I can tell 3.7 still looks like the goal - but you know how plans sometimes change 😅)

So if you want to use it now you will need to either use a forked version or somehow make this branches code available to your project.

Evan Plaice • Oct 3 '19

Thank you so much. I dug a bit on my own but didn't see any reference about a fix being worked on.

Also, saw your post on Twitter saying this has been officially released now. Awesome!

Robert Biggs • Sep 5 '19

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.

Thomas Allmer Open Web Components • Sep 8 '19 • Edited

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 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....

Abinash Patra • Oct 9 '19

Just wondering, if instead of jsDoc, we can use only *.d.ts files for the type-checking purposes same as the jsDoc comment

This will allow my code to be lightly coupled with type-system at the same time, allowing me the benefits of type-safety

To summarize: Idea is to have .ts / .js files without any typescript specific language construct, with only .d.ts files accompanying them

Anyone used it like this or any thoughts on this ?

Thomas Allmer Open Web Components • Oct 11 '19

this is actually typescripts main use case it gets compiled to .js + d.ts files which you then publish.
e.g. even full typescript project have "only" js in their node_modules folder.

often these .js files are accompanied by d.ts files or there is a dedicated package @types/packageName.

So in short yes manually writing js and declaration files for it certainly works as well :)