A few things I've come to personally believe after spending years developing web and robotics software in Python/JavaScript then spending years having to maintain while constantly adding new features and dealing with company pivots:
- The types exist whether you write them down or not.
- If they're not written down, they're written down in your head.
- Your head is very volatile and hard for others to access.
- Typing is an incredibly good form of documentation.
- JSDoc and TypeScript are standards/formats for typing. Like any tools, they both have advantages and disadvantages. Neither is objectively better than the other.
- Make informed decisions on how you'll describe your types, and then be consistent and unsurprising.
- A type checker is the computer saying, "okay then, prove it" about your program's type validity.
- Not every program benefits from the same amount of "prove it."
- Too much can be as bad as too little. You're wasting resources proving throwaway code.
- I like languages that let you decide how much you need to "prove it."
> For packages typed with JSDoc, CTRL/CMD clicking on a function will take you to actual code rather than a type declarations file. I much prefer this experience as a dev.
More broadly, this is the default behavior of JS even without JSDoc blocks, and it ought to be the default behavior everywhere, including TS. I'm not alone in this sentiment, but it's incredibly contentious. There's been an open GH issue about it with hundreds of replies for years. I have no idea why they can't just pick a different shortcut for viewing types and call it a day. They'd be doing the entire ecosystem a favor.
I'm a fan of anything that allows me to build with javascript that doesn't require a build step.
Modern HTML/CSS with Web Components and JSDoc is underrated. Not for everyone but should be more in the running for a modern frontend stack than it is.
On the one hand I can see the appeal of not having a build step. On the other, given how many different parts of the web dev pipeline require one, it seems very tricky to get all of your dependencies to be build-step-free. And with things like HMR the cost of a build step is much ameliorated.
Any kind of downleveling, though that's less important these days most users only need polyfills, new syntax features like `using` are not widely used.
Minification, and bundling for web is still somewhat necessary. ESM is still tricky to use without assistance.
None of these are necessary. But if you use any of them you've already committed to having a build step, so adding in a typescript-erasure step isn't much extra work.
Agreed on native HTML+CSS+JSDoc. An advantage in my use-cases is that built-in browser dev tools become fluid to use. View a network request, click to the initiator directly in your source code, add breakpoints and step without getting thrown into library internals, edit code and data in memory to verify assumptions & fixes, etc.
Especially helpful as applications become larger and a debugger becomes necessary to efficiently track down and fix problems.
So, some history. When SPA's started to boom on the web JSDoc was a life saver for typing. Application state was getting more complex. We needed more guard rails.
Then Google Closure Compiler came along which added type safety via JSDOC and TS came along with (TS)JSDoc support and it's own TS syntax.
The community chose native TS and Google Closure compiler slipped away into the background.
So (TS)JSDoc support is a relic from when Microsoft was trying to get market share from Google.
Today in 2025, TS offers so much more than the (TS)JSDoc implementation. Generics, Enums, Utility types, Type Testing in Vitest, typeguards, plus other stuff.
Today I use TS. I also use plain JSDoc for documentation. e.g. @link and @see for docs. Or @deprecated when I'm flagging a method to be removed. @example for a quick look up of how to use a component.
TS and plain JSDoc are both important together. But (TS)JSDoc alone, is a relic of the past.
JSDoc works great for buildless application setups! One downside is that if you publish a library to npm you still need a build step to generate .d.ts files from your JSDoc type annotations so that npm shows a "TS" badge on the npm package page. This also seems to apply to VSCode's intellisense which keeps trying to poke you to "try to install @types/jsdoc-typed-package to get type information". Other JS ecosystem tooling also doesn't seem to process JSDoc types at all such as jsdocs.io or tsdocs.dev. So for libraries we're stuck with .d.ts generation via "tsc --allowJs --checkJs --declaration ..." even if it's all JS.
1. there are plenty things you can't express in jsdoc but can in typescript, flow did the right thing here where you have access to full language, not sure why typescript never did it, they could, with the same syntax flow is using
2. you can have navigation that goes to typescript file instead of definition, just arrange your exports in package.json correctly (first ones take precedence)
Well I'd love to hear some concrete examples if you have any on hand! I was of the same opinion as you until I refactored a project of mine to use JSDoc.
Since any TypeScript type can be expressed in JSDoc, I imagine you're mostly thinking of generics. At least that was my main sticking point. JSDoc does actually have generic slots with the @template tag. Actually using them in practice is a little unintuitive but involves typing the return type. E.g. for a function it'd look like this:
Support for generics is limited in JSDoc compared to TypeScript, especially when arrow function is involved. Things that work fine in TypeScript trigger errors even though they are syntactically the same.
Because AirBnB's ESLint config has been burned into my brain I almost only use arrow functions. I also use generics extremely often. It's definitely a little more clunky but I haven't run into anything you can do in TypeScript that you can't do in JSDoc.
JSDoc also allows you to type stuff in-line. For example I often have to type an empty array like so:
(I had to make it a little bit different from the JS code to make it compile)
Note that I cannot make the type check in JS code to pass. Whatever I do, there is always a error. Meanwhile, it does not take much to TS code to work.
Having JSDoc-like syntax isn't the same as it being fully supported. If you have a large enough codebase, you'll likely find a few cases where things work in TypeScript but its equivalent somehow fails type check in JSDoc.
> If you have a large enough codebase, you'll likely find a few cases where things work in TypeScript but its equivalent somehow fails type check in JSDoc.
You keep repeating this throughout the thread. Can you give an example?
TypeScript's type system is Turing complete so you have access to essentially unlimited expressivity (up to the typechecking termination depth): https://news.ycombinator.com/item?id=14905043
I'm a big advocate for explicit type annotations in code. Likewise, either or is good with me when working on the FE or BE. However, these days I lean towards using JSDoc only because I prefer not to add typescript lib and an additional build step just to get type safety in a project.
Also, you can use both (if that's what you prefer).
5 years ago I was at a meet up and the guy talking was saying how if you don't like typescript these jsdocs are the way to go. Had to explain to my employer attending that it is still typescript. Didn't seem to believe me and was super against typescript but not jsdocs lol
> Had to explain to my employer attending that it is still typescript
"is" is doing a lot of heavy lifting there: JSDoc and TypeScript are two different ways to explicit prescribe typing in a way that tooling can use to determine correctness. The TS syntax is _far_ more powerful, but JSDoc can do most of the common TS use cases, for folks who want to stay in JS land while still benefiting from type tooling (either invoked or straight up built into the IDE).
> in a way that tooling can use to determine correctness.
As I pointed out in the article, the "tooling" is exactly TypeScript language services. If you are using JSDoc and you get squigglies or intellisense or any other similar features, you are using TypeScript.
You can copy-paste basically any bit of TypeScript into a JSDoc comment and it will work. JSDoc supports any non-runtime feature of TypeScript (so not enums). Even generics! You can even reference TypeScript utility types!
The whole point of this article was to correct the idea that JSDoc is not TypeScript. It absolutely is! There's almost nothing you can't define in JSDoc that you can't define in a .ts file. Albeit with a sometimes clunkier syntax
In practice today JSDoc 100% completely and utterly always is Typescript.
It might not have been so originally. It might still be possible to do differently. But in practice today you are getting Typescript in your JSDoc with the out of the box tooling that is everywhere.
> For packages typed with JSDoc, CTRL/CMD clicking on a function will take you to actual code rather than a type declarations file. I much prefer this experience as a dev.
ok i didn't think about this, that's an underrated benefit
It doesn't. You might be thinking of libraries that you wrote, not packages from e.g. npm, which are distributed as JavaScript + type definition files not as TypeScript code.
In real IDEs, not glorified text editors like VSCode, it does. I use this often in IDEA, it's muscle memory so I'm not even completely sure what to press, but it's likely "go to definition" and by default is tied to ctrl+alt+b.
IDEA adds its own analysis on top of that provided by the language server.
Works on JS + every variant of type definitions I've ever seen, among many other things (not only programming languages, but also database objects, etc).
I'm actually using JSTypes in app, I don't mind it.
I choose to use it because I didn't want to deal with a build step for a smaller project. The project has grown and I am looking at adding a build step for bundling but still not too worried about using JSDoc over TS.
This might be my config, but one thing that does annoy me is whenever I define a lambda, I need to add an doc type. I guess if that's disincentivising me from writing lambdas maybe I should just add a TS compile step lol.
These days you can run TypeScript files as-is (type stripping) for testing in many runtimes, and for bundling, most bundlers support using a ts file as the entry point directly.
This is how I develop web software, and I've found it productive and maintainable.
A bonus of this approach is that it clearly delineates what type information is available at runtime, vs what type information is just a comment. (especially useful when working with serialized data).
I also like that it generally means all of the preconditions and postconditions for functions are in a single place (both the prose and the technical information are in the JSDoc comment), keeping the code itself low-noise and boiled down to its essence, and providing a natural place to write example inputs and outputs to guide usage.
As for generic types, I use them extensively, and this is made less verbose e.g. on function calls by using an @type annotation on the function which accepts a TypeScript signature without needing separate @template + @param annotations.
It's awesome stuff, and I'm happy that TypeScript works so well with JSDoc!
I work in a codebase that unfortunately does not support TypeScript. I use JSDoc extensively, although not with type check enabled (due to various limitations). I also work on other projects with TypeScript. My own experience is that the DX with "real" TypeScript is much, much better than JavaScript with JSDoc, without question. JavaScript with JSDoc is much more verbose, with a lot of limitations when types get long or complex compared to TypeScript. The official TypeScript language service also does not provide the same level of support.
Basically, the fact that it works does not mean it works well, and I don't recommend anyone going in this other direction unless they understand what they are getting into.
Not a limitation in language service, but an issue with the codebase itself -- legacy codebase with a lot of missing/incorrect typing from upstream JavaScript code (owned by other teams), making it practically impossible to actually run type check.
I tried making a library this way and lacking control over the visibility of the exported types was really painful; it made my intellisense awful because every type I defined at the root was exported from the library
I really like it for web components. Lately I have many "my-component.js" files and it's quite nice to just be able to copy them to new projects and have it all work without a build step. But I'm not sure I would use JSDoc over typescript syntax in a large project.
Who cares what some framework guy thinks. When I was writing JavaScript for employment most people doing that work were hyper concerned with how to write code and what other people thought about it. These kinds of opinions and conversations are critically important for beginners, but junior and senior developers never seemed to get past these concerns of basic literacy.
When other developers and non-developers look at JavaScript developers as small children it’s because the maturity difference is very evident from the outside. Once developers get past basic literacy they are free to worry about architecture, performance, scale, platform independence, and more. For most JavaScript developers they just expect some framework to do it for them.
Dunno. Your comment seems pretty immature and strangely emotional. If you think you’re too good for these sorts of articles and this sort of tech, then maybe you’re also too good for the related discussion.
I still think that JS is very much not TS. Most TS code assumes you never need to check for errors because the type checker proves they can't happen.
Then, paradoxically, with no error checking at runtime, it becomes fully possible for JS code to call into TS code in a way that breaks the shit out of the TS compiler's assumptions. In philosophy then TS and JS are as incompatible as GPL and EULA
It doesn't matter if a library is written in TS or JS; you cannot meaningfully protect against other code calling you incorrectly.
Sure, you can check if they gave you a string instead of a number. But if you receive an array of nested objects, are you going to traverse the whole graph and check every property? If the caller gives you a callback, do you check if it returns the correct value? If that callback itself returns a function, do you check that function's return type too? And will you check these things at every single function boundary?
This kind of paranoid runtime type-checking would completely dominate the code, and nobody does it. Many invariants which exist at compile-time cannot be meaningfully checked at runtime, even if you wanted to. All you can do is offer a type-safe interface, trust your callers to respect it, and check for a few common mistakes at the boundary. You cannot protect your code against other code calling it incorrectly, and in practice nobody does. This is equally true for JS and TS.
Writing a Typescript program that takes external input but has no runtime error checking is already a mistake, though. Dealing with external input requires type assertions (since Typescript doesn't know what the program is getting at compile-time) and if you write type assertions without ensuring that the assertions are accurate, then that's on you, not Typescript.
However, if your point is that Typescript can lull people into a false sense of safety, then sure, I take your point. You have to understand where type assertions are coming into play, and if that's obscured then the type safety can be illusory. The benefits of Typescript require you to make sure that the runtime inputs to your program are sufficiently validated.
> Writing a Typescript program that takes external input but has no runtime error checking is already a mistake, though.
If it's a service, yes, and that's true no matter what technology the service is using. If it's a library, no, because...
> and if you write type assertions without ensuring that the assertions are accurate, then that's on you, not Typescript.
That's on whoever is using the library, not the library author. If the library author provides type definitions, and you as the consumer choose to ignore them, then it's on you.
Sure, but if the caller is Javascript then you're running Javascript, not Typescript*, so it makes sense that you're not going to get type safety.
I'm also not sure we're actually disagreeing on anything, so perhaps my reply was pointless. I agree that if you mix JS and TS in the way you describe, you'll have problems. My reply was just to say "yes, and that's not really Typescript's fault", but perhaps you weren't implying that to begin with.
* I'm aware that you can't run Typescript directly, but I hope my point here is clear... you're running a program that wasn't type-checked by TS.
The type checker can only prove what is known at compile time and only if you're disciplined.
To bridge runtime and compile time (as your application will likely get some external data) you've got to use a proper parser such as zod[1] or if you want to stretch it even further effect-schema[2].
A somewhat related thing programmers must understand is that whether you write typescript, JSX, .astro or .svelte files, you are technically not writing JavaScript.
You should occasionally look at the build artifacts of your framework but also ask yourself whether it is worth it to write code that may not represent what actually ends up being executed.
Lately I just use vite with no starter template but with web components and css modules. It at least feels more convenient than using any framework or library.
This seems like an issue but in all my practical experience it really isn't. TypeScript becomes JavaScript with the types removed. Then you tree-shake, minify, and whatever is executed is no where near what you actually wrote but at the same it totally is the same because that's no different than any other compilation process.
Occasionally, I have to remember that JavaScript has no types at runtime but it's surprisingly not that often.
I mean what makes it more acceptable is that you have HMR and instant preview during development. So, all the transformations and bundling aside, you do see how it runs during development.
However I have been in a few situations at work where all of a sudden we did have issues that required us to dig deeper. There were also some bundling related issues that caused problems in production deployments. At that point many co workers had no idea how to even approach it to be honest.
I've had similar experiences with compiled languages in one form or another throughout my career as well. I don't think JavaScript is particularly special that we need to call it out for things like TypeScript, minification, or bundling.
Somewhat. I could still use framework agnostic state management libraries/patterns and most are (e.g. svelte signals, jotai, zustand, etc.).
I've even used Proxies directly to implement some reactivity before. However as for the "declarative" parts, I think it's just a little bit of a different way to work but you get used to it and imo it pays off. Knowing the web APIs should be a requirement anyway and it doesn't hurt to work with them directly as much as possible.
Yeah it’s a silly line of reasoning. The transformations of TS -> JS are a lot smaller and simpler than C-> asm / machine code; it’s basically just removing type annotations. Now minification and optimization can make the output a lot more terse, but that can be done for JS too. And it’s not as complicated and detached from the source as an optimizing compiler is.
Let's not act like it's the same thing. I'm not strictly talking about just Typescript, I'm saying that if you work with these technologies every day it would be wise to go look at their Vite plugins to see how they transform your code and be sure to understand it. It's nice to have magic but it's nicer to use the magic if we have demystified it first.
And I don't know about you, but I occasionally do open compiled ELF files in a hex editor and I certainly did at first when I was learning more. That's a good practice also.
That's correct, however I would say there is a small difference in that most of this code still seems just like JavaScript, sometimes it even feels as though it is JavaScript running in the same context when it then gets compiled to run on server/client.
I think the point I'm trying to make is that this can be confusing or even dangerous especially for new developers. It just doesn't hurt to actually look at the Vite plugins transforming it all to understand it instead of making assumptions if we work with it on the daily.
You mean a TypeScript project without strict mode? Sure. Again, whether you're defining types in JSDoc comments or in .ts files, the behavior is entirely governed by a tsconfig file
Oh man, the mention of ScriptSharp brought back memories. I started my career at MSFT on SharePoint and the front end was an ungodly mix of ScriptSharp and other stuff.
I vividly remember being in a meeting with the Exchange team (about building shared frontend components) arguing for us to adopt TS instead as it had a better experience and very rapidly growing popularity (that was about 10 years ago). Plus, as strong as Nikhil [0] was, he was basically the only person behind ScriptSharp while TS had a whole team.
Of course, this being MSFT, this effort went no where. While true that the TS toolchain lacked the tree-shaking that ScriptSharp had, I was just annoyed that we had to build stuff using what was obviously an dead-ish language with limited support, many flaws, and no resources to improve it.
From what I've read, many of TypeScript's design regrets have political origins. Enums and other features that oppose TS's structural type system were added as compromises with C# developers in MS and similar negotiations with the Angular team in order to increase adoption of TypeScript over alternatives
Eh. I agree with the principle. I’ve written personal projects with JSDoc because I truly love the idea of finally being done with build systems and just serving the files I write without a step in between.
But it’s more annoying than just writing TypeScript. There are ways to express just about everything TypeScript can but they’re all more difficult and convoluted (generics are a great example). For a project of any reasonable size I’m still going to advocate to use TypeScript.
It's certainly more verbose but certainly not a limited subset. You can copy paste any typescript Type or Interface in a jsdoc @typedef. As I stated in the article, it's still the TypeScript language service that's analyzing either JSDoc-defined types or TypeScript defined types. It's typescript all the way down
But JSDoc lets you do pretty much everything that isn't a runtime feature of TypeScript (e.g. enums, namespaces, etc). Even generic slots are supported
The list of things jsdoc cannot do is long but a simple example is overloading, you cannot express this[1] in jsdoc, and if you need to reference .d.ts files you're back at using TypeScript, so the point of JSDoc was...?
If you need precise return typing, conditional types, literal values, etc, you aren't going far if anywhere with JSDoc.
But not properly documented (https://www.typescriptlang.org/docs/handbook/jsdoc-supported...), which shows how much Microsoft neglects JS + JSDoc workflow. Github issues have been created a long time ago, but nothing has been done so far. Apparently Microsoft is too busy with their AI slop to work on actually useful stuff.
Care to give an example. In another reply I pointed out how advanced JSDoc syntax's support for generics is.[0] Even allowing for `extends` and default values for generic slots.
The clunkiest part is in the way you "pass in" a generic to a slot. But this is solved by typing the return type.
I use generics pretty extensively and I've not yet come across a use-case JSDoc couldn't handle
Once we get it, there is still a solid decade before runtimes support it, and optimistically, still more 10 years minimum having to deal with an interpreted language that has acquired an unecessary build step.
I absolutely hated when PHP switched from a phpDoc culture with static analysis (and IDE inconsistencies that would click-take you to stubs as well) to actual types. Not because I hate types, but because of the transition period. Once it's gone, it's such a relief to get rid of unecessary docblocks.
Something needs to change. I don't care about one specific proposal.
It's miserable having a de-facto build step for an interpreted language. Worst of both worlds.
Maybe just TS is fast, but it encourages developers to put more and more stuff into that build step (and they do, they do that a lot). Culturally, that trend is not going to change unless the main reason for having said build step is removed.
The whole babel/transpiling thing was meant to be temporary. It became temporarily permanent / permanently temporary.
The proposal is to introduce a whole slew of syntax to JS that according to the proposal will have no meaning. This is a paradox. You have only created a language if you can use it to convey meaning
Unless I say it's meaning is to be optionally reflected upon during runtime!
Look, I understand the purism and mostly, I agree. But this is not a clean slate language, it will never be perfect and it's going to become more and more idiosyncratic as times go by.
Comments are a kind of freedom in code. You're completely free to use them precisely because (in a plain execution environment) they cannot influence the result of evaluation
If comments /can/ change the result of evaluation then you simply are not (completely) free to use them. (And yes I know that this is a simplification in JS where you can already get the source code of a function with toString... Ugh)
Agree. It’s superior. I arrived at this about 2 years ago no regrets. Type safety matters on the tooling side anyway. Unless you’re testing for the runtime I guess?
I'm glad to hear you've had a good experience with it but I want to reiterate that my position isn't that JSDoc is superior. Just that it is TypeScript
A few things I've come to personally believe after spending years developing web and robotics software in Python/JavaScript then spending years having to maintain while constantly adding new features and dealing with company pivots:
- The types exist whether you write them down or not.
- If they're not written down, they're written down in your head.
- Your head is very volatile and hard for others to access.
- Typing is an incredibly good form of documentation.
- JSDoc and TypeScript are standards/formats for typing. Like any tools, they both have advantages and disadvantages. Neither is objectively better than the other.
- Make informed decisions on how you'll describe your types, and then be consistent and unsurprising.
- A type checker is the computer saying, "okay then, prove it" about your program's type validity.
- Not every program benefits from the same amount of "prove it." - Too much can be as bad as too little. You're wasting resources proving throwaway code. - I like languages that let you decide how much you need to "prove it."
> For packages typed with JSDoc, CTRL/CMD clicking on a function will take you to actual code rather than a type declarations file. I much prefer this experience as a dev.
More broadly, this is the default behavior of JS even without JSDoc blocks, and it ought to be the default behavior everywhere, including TS. I'm not alone in this sentiment, but it's incredibly contentious. There's been an open GH issue about it with hundreds of replies for years. I have no idea why they can't just pick a different shortcut for viewing types and call it a day. They'd be doing the entire ecosystem a favor.
I'm a fan of anything that allows me to build with javascript that doesn't require a build step.
Modern HTML/CSS with Web Components and JSDoc is underrated. Not for everyone but should be more in the running for a modern frontend stack than it is.
On the one hand I can see the appeal of not having a build step. On the other, given how many different parts of the web dev pipeline require one, it seems very tricky to get all of your dependencies to be build-step-free. And with things like HMR the cost of a build step is much ameliorated.
I haven't run into any steps that require one, there's always alternatives.
Do you have anything specific in mind?
Anything that uses JSX syntax, for instance.
Any kind of downleveling, though that's less important these days most users only need polyfills, new syntax features like `using` are not widely used.
Minification, and bundling for web is still somewhat necessary. ESM is still tricky to use without assistance.
None of these are necessary. But if you use any of them you've already committed to having a build step, so adding in a typescript-erasure step isn't much extra work.
Agreed on native HTML+CSS+JSDoc. An advantage in my use-cases is that built-in browser dev tools become fluid to use. View a network request, click to the initiator directly in your source code, add breakpoints and step without getting thrown into library internals, edit code and data in memory to verify assumptions & fixes, etc.
Especially helpful as applications become larger and a debugger becomes necessary to efficiently track down and fix problems.
Webcomponents are a pain in the ass to make, though. That is, sufficiently complex ones. I wish there was an easier way.
They could have better ergonomics and I hope a successor that does comes out but they're really not that bad.
So, some history. When SPA's started to boom on the web JSDoc was a life saver for typing. Application state was getting more complex. We needed more guard rails.
Then Google Closure Compiler came along which added type safety via JSDOC and TS came along with (TS)JSDoc support and it's own TS syntax.
The community chose native TS and Google Closure compiler slipped away into the background.
So (TS)JSDoc support is a relic from when Microsoft was trying to get market share from Google.
Today in 2025, TS offers so much more than the (TS)JSDoc implementation. Generics, Enums, Utility types, Type Testing in Vitest, typeguards, plus other stuff.
Today I use TS. I also use plain JSDoc for documentation. e.g. @link and @see for docs. Or @deprecated when I'm flagging a method to be removed. @example for a quick look up of how to use a component.
TS and plain JSDoc are both important together. But (TS)JSDoc alone, is a relic of the past.
JSDoc works great for buildless application setups! One downside is that if you publish a library to npm you still need a build step to generate .d.ts files from your JSDoc type annotations so that npm shows a "TS" badge on the npm package page. This also seems to apply to VSCode's intellisense which keeps trying to poke you to "try to install @types/jsdoc-typed-package to get type information". Other JS ecosystem tooling also doesn't seem to process JSDoc types at all such as jsdocs.io or tsdocs.dev. So for libraries we're stuck with .d.ts generation via "tsc --allowJs --checkJs --declaration ..." even if it's all JS.
npm displays packages with bundled TypeScript declarations https://github.blog/changelog/2020-12-16-npm-displays-packag...
JSDoc-typed node modules require special configuration in consumers to be useful https://github.com/microsoft/TypeScript/issues/19145
1. there are plenty things you can't express in jsdoc but can in typescript, flow did the right thing here where you have access to full language, not sure why typescript never did it, they could, with the same syntax flow is using
2. you can have navigation that goes to typescript file instead of definition, just arrange your exports in package.json correctly (first ones take precedence)
Well I'd love to hear some concrete examples if you have any on hand! I was of the same opinion as you until I refactored a project of mine to use JSDoc.
Since any TypeScript type can be expressed in JSDoc, I imagine you're mostly thinking of generics. At least that was my main sticking point. JSDoc does actually have generic slots with the @template tag. Actually using them in practice is a little unintuitive but involves typing the return type. E.g. for a function it'd look like this:
Last time I checked, there isn't a way to extend types (https://www.typescriptlang.org/docs/handbook/2/objects.html#...) that works exactly like in TypeScript.
JSDoc actually has the @extends tag
But I don't really use that feature in TypeScript. Instead I rely on `&`. This works in exactly the same way in JSDoc.Also if you're curious about the equivalent of `extends` in generic slots, here's an example I have from a different project
The generic slot here, T, is "extended" by Record<string, unknown>. The equivalent in TypeScript would look likeYou can use `&` operator to combine types. Works for adding fields, making branded types, etc.
which is not the same as "extends".
Support for generics is limited in JSDoc compared to TypeScript, especially when arrow function is involved. Things that work fine in TypeScript trigger errors even though they are syntactically the same.
Because AirBnB's ESLint config has been burned into my brain I almost only use arrow functions. I also use generics extremely often. It's definitely a little more clunky but I haven't run into anything you can do in TypeScript that you can't do in JSDoc.
JSDoc also allows you to type stuff in-line. For example I often have to type an empty array like so:
If you have a tangible example of a problem you've run into, I'd love to walk through it.JavaScript example:
https://www.typescriptlang.org/play/?filetype=js#code/PTAEAE...
Almost equivalent typescript code:
https://www.typescriptlang.org/play/?#code/C4TwDgpgBA6glsAFg...
(I had to make it a little bit different from the JS code to make it compile)
Note that I cannot make the type check in JS code to pass. Whatever I do, there is always a error. Meanwhile, it does not take much to TS code to work.
ReturnType is TypeScript, no? You’re using JSDoc to express but it’s a TypeScript type.
As I stated in the article, JSDoc is TypeScript :P
TypeScript utility types are available in JSDoc. You can pretty much copy-paste any typescript Type/Interface into JSDoc
Isn't that the whole point of the article? For all intents and purposes, JSDoc IS TypeScript
and types can be written in .d.ts file(s), which can be used in jsdoc out of the box (no import needed)
You could, but in a large codebase with multiple contributors, it easily becomes messy and confusing.
> there are plenty things you can't express in jsdoc but can in typescript
This isn't really true anymore, they have systematically added pretty much every type system feature to the JSDoc-like syntax.
Having JSDoc-like syntax isn't the same as it being fully supported. If you have a large enough codebase, you'll likely find a few cases where things work in TypeScript but its equivalent somehow fails type check in JSDoc.
> If you have a large enough codebase, you'll likely find a few cases where things work in TypeScript but its equivalent somehow fails type check in JSDoc.
You keep repeating this throughout the thread. Can you give an example?
https://news.ycombinator.com/item?id=46268701
TypeScript's type system is Turing complete so you have access to essentially unlimited expressivity (up to the typechecking termination depth): https://news.ycombinator.com/item?id=14905043
I'm a big advocate for explicit type annotations in code. Likewise, either or is good with me when working on the FE or BE. However, these days I lean towards using JSDoc only because I prefer not to add typescript lib and an additional build step just to get type safety in a project.
Also, you can use both (if that's what you prefer).
5 years ago I was at a meet up and the guy talking was saying how if you don't like typescript these jsdocs are the way to go. Had to explain to my employer attending that it is still typescript. Didn't seem to believe me and was super against typescript but not jsdocs lol
> Had to explain to my employer attending that it is still typescript
"is" is doing a lot of heavy lifting there: JSDoc and TypeScript are two different ways to explicit prescribe typing in a way that tooling can use to determine correctness. The TS syntax is _far_ more powerful, but JSDoc can do most of the common TS use cases, for folks who want to stay in JS land while still benefiting from type tooling (either invoked or straight up built into the IDE).
> in a way that tooling can use to determine correctness.
As I pointed out in the article, the "tooling" is exactly TypeScript language services. If you are using JSDoc and you get squigglies or intellisense or any other similar features, you are using TypeScript.
You can copy-paste basically any bit of TypeScript into a JSDoc comment and it will work. JSDoc supports any non-runtime feature of TypeScript (so not enums). Even generics! You can even reference TypeScript utility types!
The whole point of this article was to correct the idea that JSDoc is not TypeScript. It absolutely is! There's almost nothing you can't define in JSDoc that you can't define in a .ts file. Albeit with a sometimes clunkier syntax
In practice today JSDoc 100% completely and utterly always is Typescript.
It might not have been so originally. It might still be possible to do differently. But in practice today you are getting Typescript in your JSDoc with the out of the box tooling that is everywhere.
The difference is syntax compression imo.
> For packages typed with JSDoc, CTRL/CMD clicking on a function will take you to actual code rather than a type declarations file. I much prefer this experience as a dev.
ok i didn't think about this, that's an underrated benefit
could be a customizable behavior in editor/ide though
There is indeed an option in VSCode (can't find it right now), following the work in https://github.com/microsoft/typescript-go/pull/1543
This works with Typescript too though?
It doesn't. You might be thinking of libraries that you wrote, not packages from e.g. npm, which are distributed as JavaScript + type definition files not as TypeScript code.
In real IDEs, not glorified text editors like VSCode, it does. I use this often in IDEA, it's muscle memory so I'm not even completely sure what to press, but it's likely "go to definition" and by default is tied to ctrl+alt+b.
IDEA adds its own analysis on top of that provided by the language server.
Works on JS + every variant of type definitions I've ever seen, among many other things (not only programming languages, but also database objects, etc).
It should work if the library was compiled with deceleration map option. Which most libraries are not and it's a shame.
It was added like 3 years ago which was probably a bit too late, not even sure why it's not the default. (File size?)
TypeScript won over the alternatives, exactly because it is only a type checker, and not a new language.
Granted they initially weren't down that path, but they course corrected it on time, and not much people use stuff like enums in new code.
I'm actually using JSTypes in app, I don't mind it.
I choose to use it because I didn't want to deal with a build step for a smaller project. The project has grown and I am looking at adding a build step for bundling but still not too worried about using JSDoc over TS.
This might be my config, but one thing that does annoy me is whenever I define a lambda, I need to add an doc type. I guess if that's disincentivising me from writing lambdas maybe I should just add a TS compile step lol.
----------------------
Here's an example - I got some config typed with this function https://github.com/AKST/analysis-notebook/blob/c9fea8b465317... - Here's the type https://github.com/AKST/analysis-notebook/blob/c9fea8b465317... - And here's something to generate a more complicated type for defining config knobs https://github.com/AKST/analysis-notebook/blob/c9fea8b465317...
These days you can run TypeScript files as-is (type stripping) for testing in many runtimes, and for bundling, most bundlers support using a ts file as the entry point directly.
This is how I develop web software, and I've found it productive and maintainable.
A bonus of this approach is that it clearly delineates what type information is available at runtime, vs what type information is just a comment. (especially useful when working with serialized data).
I also like that it generally means all of the preconditions and postconditions for functions are in a single place (both the prose and the technical information are in the JSDoc comment), keeping the code itself low-noise and boiled down to its essence, and providing a natural place to write example inputs and outputs to guide usage.
As for generic types, I use them extensively, and this is made less verbose e.g. on function calls by using an @type annotation on the function which accepts a TypeScript signature without needing separate @template + @param annotations.
It's awesome stuff, and I'm happy that TypeScript works so well with JSDoc!
I work in a codebase that unfortunately does not support TypeScript. I use JSDoc extensively, although not with type check enabled (due to various limitations). I also work on other projects with TypeScript. My own experience is that the DX with "real" TypeScript is much, much better than JavaScript with JSDoc, without question. JavaScript with JSDoc is much more verbose, with a lot of limitations when types get long or complex compared to TypeScript. The official TypeScript language service also does not provide the same level of support.
Basically, the fact that it works does not mean it works well, and I don't recommend anyone going in this other direction unless they understand what they are getting into.
> although not with type check enabled (due to various limitations)
Curious what limitations there are on static type checking. It seems like a matter of your IDE setup
> My own experience is that the DX with "real" TypeScript is much, much better than JavaScript with JSDoc
I agree with the DX point. I would just point out that if you're using JSDoc and getting intellisense from it, you are using TypeScript
Not a limitation in language service, but an issue with the codebase itself -- legacy codebase with a lot of missing/incorrect typing from upstream JavaScript code (owned by other teams), making it practically impossible to actually run type check.
counterpoint: JSDoc is not typescript
If you define a type in a file with @typedef, it is automatically exported and there is nothing you can do to control that: https://github.com/microsoft/TypeScript/issues/46011
I tried making a library this way and lacking control over the visibility of the exported types was really painful; it made my intellisense awful because every type I defined at the root was exported from the library
That's technically a fair complaint but feels like a minor nitpick. Just don't `@import` the types you don't want to use.
I really like it for web components. Lately I have many "my-component.js" files and it's quite nice to just be able to copy them to new projects and have it all work without a build step. But I'm not sure I would use JSDoc over typescript syntax in a large project.
Who cares what some framework guy thinks. When I was writing JavaScript for employment most people doing that work were hyper concerned with how to write code and what other people thought about it. These kinds of opinions and conversations are critically important for beginners, but junior and senior developers never seemed to get past these concerns of basic literacy.
When other developers and non-developers look at JavaScript developers as small children it’s because the maturity difference is very evident from the outside. Once developers get past basic literacy they are free to worry about architecture, performance, scale, platform independence, and more. For most JavaScript developers they just expect some framework to do it for them.
Dunno. Your comment seems pretty immature and strangely emotional. If you think you’re too good for these sorts of articles and this sort of tech, then maybe you’re also too good for the related discussion.
I still think that JS is very much not TS. Most TS code assumes you never need to check for errors because the type checker proves they can't happen.
Then, paradoxically, with no error checking at runtime, it becomes fully possible for JS code to call into TS code in a way that breaks the shit out of the TS compiler's assumptions. In philosophy then TS and JS are as incompatible as GPL and EULA
It doesn't matter if a library is written in TS or JS; you cannot meaningfully protect against other code calling you incorrectly.
Sure, you can check if they gave you a string instead of a number. But if you receive an array of nested objects, are you going to traverse the whole graph and check every property? If the caller gives you a callback, do you check if it returns the correct value? If that callback itself returns a function, do you check that function's return type too? And will you check these things at every single function boundary?
This kind of paranoid runtime type-checking would completely dominate the code, and nobody does it. Many invariants which exist at compile-time cannot be meaningfully checked at runtime, even if you wanted to. All you can do is offer a type-safe interface, trust your callers to respect it, and check for a few common mistakes at the boundary. You cannot protect your code against other code calling it incorrectly, and in practice nobody does. This is equally true for JS and TS.
Writing a Typescript program that takes external input but has no runtime error checking is already a mistake, though. Dealing with external input requires type assertions (since Typescript doesn't know what the program is getting at compile-time) and if you write type assertions without ensuring that the assertions are accurate, then that's on you, not Typescript.
However, if your point is that Typescript can lull people into a false sense of safety, then sure, I take your point. You have to understand where type assertions are coming into play, and if that's obscured then the type safety can be illusory. The benefits of Typescript require you to make sure that the runtime inputs to your program are sufficiently validated.
> Writing a Typescript program that takes external input but has no runtime error checking is already a mistake, though.
If it's a service, yes, and that's true no matter what technology the service is using. If it's a library, no, because...
> and if you write type assertions without ensuring that the assertions are accurate, then that's on you, not Typescript.
That's on whoever is using the library, not the library author. If the library author provides type definitions, and you as the consumer choose to ignore them, then it's on you.
TS certainly thinks of external input as a boundary requiring safety, but usually that would mean form input or CLI args parsing or something.
Usually there's little if any protection against a JS caller providing wrong-type args to TS functions.
Sure, but if the caller is Javascript then you're running Javascript, not Typescript*, so it makes sense that you're not going to get type safety.
I'm also not sure we're actually disagreeing on anything, so perhaps my reply was pointless. I agree that if you mix JS and TS in the way you describe, you'll have problems. My reply was just to say "yes, and that's not really Typescript's fault", but perhaps you weren't implying that to begin with.
* I'm aware that you can't run Typescript directly, but I hope my point here is clear... you're running a program that wasn't type-checked by TS.
Something similar is true for most statically typed languages.
If you write a C library, nothing stops someone from writing an assembly-language program that calls functions in your library with the wrong types.
The type checker can only prove what is known at compile time and only if you're disciplined.
To bridge runtime and compile time (as your application will likely get some external data) you've got to use a proper parser such as zod[1] or if you want to stretch it even further effect-schema[2].
[1] https://zod.dev/
[2] https://effect.website/docs/schema/introduction/
I’m currently in love with Arktype, and as it supports Standard Schema it plugs into most places that can take Zod schemas too :)
https://arktype.io/
That's a validator, not a proper parser, no?
No it isn’t, otherwise Closure Compiler would (still) be running MS365
“There’s nuance” yeah as much in my comment as the headline at the top of the article
A somewhat related thing programmers must understand is that whether you write typescript, JSX, .astro or .svelte files, you are technically not writing JavaScript.
You should occasionally look at the build artifacts of your framework but also ask yourself whether it is worth it to write code that may not represent what actually ends up being executed.
Lately I just use vite with no starter template but with web components and css modules. It at least feels more convenient than using any framework or library.
This seems like an issue but in all my practical experience it really isn't. TypeScript becomes JavaScript with the types removed. Then you tree-shake, minify, and whatever is executed is no where near what you actually wrote but at the same it totally is the same because that's no different than any other compilation process.
Occasionally, I have to remember that JavaScript has no types at runtime but it's surprisingly not that often.
I mean what makes it more acceptable is that you have HMR and instant preview during development. So, all the transformations and bundling aside, you do see how it runs during development.
However I have been in a few situations at work where all of a sudden we did have issues that required us to dig deeper. There were also some bundling related issues that caused problems in production deployments. At that point many co workers had no idea how to even approach it to be honest.
I've had similar experiences with compiled languages in one form or another throughout my career as well. I don't think JavaScript is particularly special that we need to call it out for things like TypeScript, minification, or bundling.
Aren't you loosing a lot of the declarative features like signals or similar, when you do your projects without those frameworks?
(asking to learn)
Somewhat. I could still use framework agnostic state management libraries/patterns and most are (e.g. svelte signals, jotai, zustand, etc.).
I've even used Proxies directly to implement some reactivity before. However as for the "declarative" parts, I think it's just a little bit of a different way to work but you get used to it and imo it pays off. Knowing the web APIs should be a requirement anyway and it doesn't hurt to work with them directly as much as possible.
> ask yourself whether it is worth it to write code that may not represent what actually ends up being executed.
Doesn't this describe every programming language?
When you write C, you are technically not writing machine code.
Even when you write JavaScript, what actually gets executed is V8 bytecode and/or machine code (depending on whether the JIT fires).
Yeah it’s a silly line of reasoning. The transformations of TS -> JS are a lot smaller and simpler than C-> asm / machine code; it’s basically just removing type annotations. Now minification and optimization can make the output a lot more terse, but that can be done for JS too. And it’s not as complicated and detached from the source as an optimizing compiler is.
Let's not act like it's the same thing. I'm not strictly talking about just Typescript, I'm saying that if you work with these technologies every day it would be wise to go look at their Vite plugins to see how they transform your code and be sure to understand it. It's nice to have magic but it's nicer to use the magic if we have demystified it first.
And I don't know about you, but I occasionally do open compiled ELF files in a hex editor and I certainly did at first when I was learning more. That's a good practice also.
That's correct, however I would say there is a small difference in that most of this code still seems just like JavaScript, sometimes it even feels as though it is JavaScript running in the same context when it then gets compiled to run on server/client.
I think the point I'm trying to make is that this can be confusing or even dangerous especially for new developers. It just doesn't hurt to actually look at the Vite plugins transforming it all to understand it instead of making assumptions if we work with it on the daily.
jsdoc is nice because you don’t have to write the non-helpful types.
---
In WebStorm, jsdoc can be rendered in HTML, which makes the code easier to scan. Here's a side-by-side VSCode vs WebStorm:
https://x.com/efortis/status/1989776568676221137
---
And in jsdoc you can have an inline description:
> you don’t have to write the non-helpful types
This entirely depends on your tsconfig setup. You can run a JSDoc-typed project in strict mode exactly the same way you would a *.ts-typed project.
Do you know if it's possible to do that the other way around?
You mean a TypeScript project without strict mode? Sure. Again, whether you're defining types in JSDoc comments or in .ts files, the behavior is entirely governed by a tsconfig file
Some TypeScript features are only available through JSDoc. The one I encounter most often is `@deprecated`.
What do you mean? Jsdoc has it
https://jsdoc.app/tags-deprecated
I think he’s saying that only JSDoc has it. Vanilla TS doesn’t.
Webpack is typed using JSDoc and type-checked via TypeScript -- I started this migration a while ago. It works pretty well
Wow I had no idea! Have you written anywhere about your experiences?
Oh man, the mention of ScriptSharp brought back memories. I started my career at MSFT on SharePoint and the front end was an ungodly mix of ScriptSharp and other stuff.
I vividly remember being in a meeting with the Exchange team (about building shared frontend components) arguing for us to adopt TS instead as it had a better experience and very rapidly growing popularity (that was about 10 years ago). Plus, as strong as Nikhil [0] was, he was basically the only person behind ScriptSharp while TS had a whole team.
Of course, this being MSFT, this effort went no where. While true that the TS toolchain lacked the tree-shaking that ScriptSharp had, I was just annoyed that we had to build stuff using what was obviously an dead-ish language with limited support, many flaws, and no resources to improve it.
But hey, at least it wasn’t GWT.
[0] https://github.com/nikhilk
From what I've read, many of TypeScript's design regrets have political origins. Enums and other features that oppose TS's structural type system were added as compromises with C# developers in MS and similar negotiations with the Angular team in order to increase adoption of TypeScript over alternatives
I would love to know where you read this!
I am always using JSDocs whenever i am writing a function - i think this is a good practice for every developer - even if it's a simple function.
Eh. I agree with the principle. I’ve written personal projects with JSDoc because I truly love the idea of finally being done with build systems and just serving the files I write without a step in between.
But it’s more annoying than just writing TypeScript. There are ways to express just about everything TypeScript can but they’re all more difficult and convoluted (generics are a great example). For a project of any reasonable size I’m still going to advocate to use TypeScript.
Not really, at best it's a verbose and limited subset.
https://github.com/tc39/proposal-type-annotations?tab=readme...
It's certainly more verbose but certainly not a limited subset. You can copy paste any typescript Type or Interface in a jsdoc @typedef. As I stated in the article, it's still the TypeScript language service that's analyzing either JSDoc-defined types or TypeScript defined types. It's typescript all the way down
But JSDoc lets you do pretty much everything that isn't a runtime feature of TypeScript (e.g. enums, namespaces, etc). Even generic slots are supported
You just haven't worked in a complex enough project yet.
I found several limitations and already opened several issues on github.
Although it's more verbose, it makes code less dense because it lives outside the function parameters.
Also, it's not a super limited subset. For instance, you can write types in .d.ts the IDE uses those types in jsdoc out of the box.
The list of things jsdoc cannot do is long but a simple example is overloading, you cannot express this[1] in jsdoc, and if you need to reference .d.ts files you're back at using TypeScript, so the point of JSDoc was...?
If you need precise return typing, conditional types, literal values, etc, you aren't going far if anywhere with JSDoc.
[1] https://shorturl.at/pg5dL
There a few points in favor of TS types in jsdoc (in order):
1. not having to type everything (many types are not helpful)
2. makes code less dense (and they can be rendered in HTML) https://x.com/efortis/status/1989776568676221137
3. not needing a compiler (browsers don't support TS)
I think the main jsdoc caveat is around private types.
About 1, IDK if there’s a way to set up TS for that.
This specific one is actually supported since 5.0:
https://devblogs.microsoft.com/typescript/announcing-typescr...
But not properly documented (https://www.typescriptlang.org/docs/handbook/jsdoc-supported...), which shows how much Microsoft neglects JS + JSDoc workflow. Github issues have been created a long time ago, but nothing has been done so far. Apparently Microsoft is too busy with their AI slop to work on actually useful stuff.
And in fact, this what the Closure Compiler does…typecheck based on JSDoc.
However, the precision and completeness is not nearly what can be expressed in TypeScript. With generics particularly.
Care to give an example. In another reply I pointed out how advanced JSDoc syntax's support for generics is.[0] Even allowing for `extends` and default values for generic slots.
The clunkiest part is in the way you "pass in" a generic to a slot. But this is solved by typing the return type.
I use generics pretty extensively and I've not yet come across a use-case JSDoc couldn't handle
[0] https://news.ycombinator.com/item?id=46267810
Clickbait ass title ffs
The sooner we get https://github.com/tc39/proposal-type-annotations, the better.
Once we get it, there is still a solid decade before runtimes support it, and optimistically, still more 10 years minimum having to deal with an interpreted language that has acquired an unecessary build step.
I absolutely hated when PHP switched from a phpDoc culture with static analysis (and IDE inconsistencies that would click-take you to stubs as well) to actual types. Not because I hate types, but because of the transition period. Once it's gone, it's such a relief to get rid of unecessary docblocks.
That proposal is a nonstarter. It cannot and will not ever be accepted
Something needs to change. I don't care about one specific proposal.
It's miserable having a de-facto build step for an interpreted language. Worst of both worlds.
Maybe just TS is fast, but it encourages developers to put more and more stuff into that build step (and they do, they do that a lot). Culturally, that trend is not going to change unless the main reason for having said build step is removed.
The whole babel/transpiling thing was meant to be temporary. It became temporarily permanent / permanently temporary.
I'm the person who is developing a permanent solution.
Which is?
Please elaborate!
The proposal is to introduce a whole slew of syntax to JS that according to the proposal will have no meaning. This is a paradox. You have only created a language if you can use it to convey meaning
That's not entirely true. Ideally, there would be a follow up with a reflection API.
Also, comments are syntax and they're mostly meaningless. By your reasoning, programming languages should have no comments.
So, it's not really a qualitative issue (presence of meaningless syntax) but a quantitative one (presence of lots of parsing complexity).
If you say that whatever data is put there doesn't matter at all, the one thing you definitely cannot ever do later is give it meaning.
Unless I say it's meaning is to be optionally reflected upon during runtime!
Look, I understand the purism and mostly, I agree. But this is not a clean slate language, it will never be perfect and it's going to become more and more idiosyncratic as times go by.
I don't see how it's optional.
Comments are a kind of freedom in code. You're completely free to use them precisely because (in a plain execution environment) they cannot influence the result of evaluation
If comments /can/ change the result of evaluation then you simply are not (completely) free to use them. (And yes I know that this is a simplification in JS where you can already get the source code of a function with toString... Ugh)
Makes sense. I'm excited for your solution, despite not having seen it. If you can solve that, it would be awesome.
Why?
In short, we can do much better. I'm building a full syntax extension/macro evaluation mechanism for JS.
Where is it? What is it called?
Agree. It’s superior. I arrived at this about 2 years ago no regrets. Type safety matters on the tooling side anyway. Unless you’re testing for the runtime I guess?
I'm glad to hear you've had a good experience with it but I want to reiterate that my position isn't that JSDoc is superior. Just that it is TypeScript