First: no, didn’t create a new framework, so no worries. (JSDocScript isn’t really a thing, I think). Second: just use Typescript! But when you can’t… then read on!
There are a bunch of benefits to using Typescript, everyone knows that.
The problem is that this isn’t true for the people of the past (poor them), so you will probably still find a lot of legacy projects in Vanilla JS.
So, before you start crying, again, because the IDE doesn’t help you with anything and rage over hours wasted because of a typo that the framework just said “hey there’s an error” and then you in vain kept asking the screen with “yes, I know there’s an error, but WHERE?” and then the framework just like “¯_(ツ)_/¯”. (If this is based on real events? I won’t confirm nor deny.)
Anyway… the more you use Typescript, the more you feel like missing a limb when you have to use Vanilla JS, but the thing people don’t tell you is: JSDOC!
An example
I put together a little Todo example for you to play with:
(don’t mind the example much… have I ever said that I’m awful at creating examples?)
Anyway, for this you need to open an IDE to check all the types, I also left a lot of comments.
Yes, this is React, but you can use JSDOC with anything!
They are just comments that your IDE interprets, so there’s no need to “compile” them.
Need more?
I’m of the opinion that your documentation (and JSDoc, even TS, is a type of documentation) needs to be the closest it can be to where you use it.
But for some cases where you can create a d.ts file that will help you and your colleagues with advanced stuff. And that will totally ignored by compilers and anything else!
I usually create it to copy utilities that JSDoc might not support out of the box or any utility I might need (doing extend this or infer with multiple generics is really hard in JSDoc (although not impossible for many things, mind you)).
Caveats
Unfortunately, JSDoc is not TS. Not only that, it’s really limited in what it can do.
Don’t get me wrong. It’s amazing in what it can do, but there are things it just can’t.
Not only that, it’s verbose! You need a lot to do the same as with TS.
And an important one: from what I understood, the way the JSDoc comments are interpreted into usable types might be different depending on the IDE… if you’re using VSCode you can do anything you’ll find out there about it, but for others, I’m not sure.
How to start
If you check the example again, you will see a // @ts-check at the top of the file.
You will need this in every file you want to be checked or you can add checkJs: true to a jsconfig.json (in this case, you can add a // @ts-nocheck to the files you don’t want checking.
You also want, in your VSCode settings, to search and check true checkJs or add "js/ts.implicitProjectConfig.checkJs": true to the settings JSON.
When to start
If you’re in a legacy project and like TS, but you have JS and can’t migrate to TS, for any reason, then start NOW!
You can start with the feature/fix you’re working on, then expand to utilities… also, bring your colleagues on it with you!
And when you just show the “magic” of types working to your fellow programmers, then I don’t think you need arguments.
The less you wait, the fewer problems you’ll have (and you’ll probably have enough of them). So, the first thing you have to do is set stuff up and start sprinkling the types (VSCode is really smart, so you don’t really need to type everything and the more you do, the more you’ll be helped by it).
My experience with the adoption
In my case, I ended up using a whole day or two just making and passing types that the frontend was using, but because I never had to think about actually typing them, then I had a lot of problems even figuring out what I had in there (I was just coming back from vacations).
I still had a lot of problems thereafter (it was a HUGE feature), but it’s totally worth it! Every time it just knows what I’m using and gives me completions and errors on typos… it’s bliss.
Sources you can use
The official docs (which are really bad TBH)
The typescript one (that doesn’t really help much, but hey! all of this is powered by TS)
https://www.typescriptlang.org/docs/handbook/jsdoc-supported-types.html
And then there are a lot of people who already wrote about this, this one is a little outdated, but still gives a lot of good info and saved me more than a few times
Top comments (15)
In my experience, JSDoc can't fully replace TS. For quickly check that there are no silly mistakes, you need
tsc, and JSDoc types quickly become way more cumbersome than TS definitions.But, big advantage of JSDoc is documenting code, surprisingly, can put usage example and link to documentation in it. It is great for reusable code, meanwhile TS good for static checks and IDE autocomplete.
Verbosity aside, there are but a few cases where what you want is to pass generics, but then you have to make some casting that doesn't do what simply passing generics does.
Other than that, jsdoc gives the same static check and IDE autocomplete.
The thing about jsdoc for types is when you have some legacy project that wouldn't support TS otherwise. But for normal "everyday" apps, it's not something you would choose over just using TS.
For libraries, however, I can also see the appeal because it makes debugging and changing the lib far easier. Since you have the code that was written, it's easier to change and then upstream the changes.
Types are most useful with complex cases, e.g. with generics, JSDoc maybe will never get all feature of TS, why MS would do that.
But it does.
I've been using it for almost a couple of years and I can tell you that: as far as typing goes, you can do it with JSDoc. Check the article: dev.to/noriller/jsdoc-101-218c
It's not ergonomic to make some things in JSDoc, so I just make a
d.tsfile for those, but for most things... jsdoc will enable the same types and autocomplete as TS.So, struggle to implement generics and other things, no
tscfor validation, and manually creatingd.tsfiles.It is a thing similar to running Doom on smart toaster, if you can do it, doesn't mean it is a good idea.
But you can run
tscon.jsfiles for validation.And you can also manually create
d.tsfiles in normal TS projects.And its less "struggle" and more verbose.
Not to mention. Most cases and projects nowadays start out with TS from day zero. So it's not needed.
Also, most projects are not a lib that might gain from being easy to change the source code.
But, if you are in that few cases it benefits...
You're missing the point.
Most of devs aren't so good and/or motivated, TS let's enforce types check, JSDoc doesn't. Even if you can perfectly live without TS, most of people who will work with your code are not so disciplined to spend more time on verbosity and don't make silly mistakes.
TS benefits teams, that why it get so widely adopted.
Actually you can enforce it.
The point you're missing is that it's not for all projects. But for the ones where you can't use TS (or the even fewer cases where you know you get more from using jsdoc than TS.).
I don't recall any way to enforce types check without TS, something that works only in VSCode won't cut it, need CI/CD as well.
Never seen project when you can't use TS.
tscworks, you just need to add to check js in tsconfig.it should be enough to show all the errors, but in vscode you might need to turn on a feat, see the other post where I say about it.
and there are legacy code with commonjs where you might be able to do whats needed to work with TS, but depending on the size of the projects it's easier to just use jsdoc instead of nothing at all.
Svelte is leaving TypeScript
I checked it out and I don't know why... they must have their reasons, but it's not something I would do. Typescript is more than just types.
This is certainly something to keep the eye on, thank you for bringing it up!
Hello Handsome
Trying to gather some people doing this here as well: github.com/voxpelli/types-in-js/di...
Nice!