JSDoc
Hacker ApprovedType annotation syntax in Developer tools
Lets JavaScript get TypeScript-style type checking through comments, with no build step. Common caveat: it cannot express everything TypeScript can, and generics and some imports are awkward.
Lets JavaScript get TypeScript-style type checking through comments, with no build step. Common caveat: it cannot express everything TypeScript can, and generics and some imports are awkward.
42 people gave an opinion
- recommend it
- 31
- criticize it
- 11
- approval share
- 74%
Recommended in 4 of 13 months
- November 2025: recommended
- December 2025: recommended
- January 2026: not recommended
- February 2026: not recommended
- March 2026: not recommended
- April 2026: not recommended
- May 2026: recommended
- June 2026: not recommended
- July 2026: recommended
- August 2026: not recommended
- September 2026: not recommended
- October 2026: not recommended
- November 2026: not recommended (month in progress)
Why it carries the badge
- 31 people recommend itNeeds 10 or more, met.
- 2.8 recommenders for every criticNeeds 2 to 1 or better, met.
- Recommended in 4 of 13 monthsNeeds 4 or more, met.
The same three rules apply to every product, and the badge can’t be bought. How the badge works
What people say about it
The reasons people give, with the number of comments that give each one. Open a reason to read what they said.
Why people recommend it
Each mark is one comment
No build step needed
“you do not need a build step and the javascript you ship to the browser would be the same you write in your editor”
Comment from 13 Jul 2026 in “Why Vanilla JavaScript” “it's quite nice to just be able to copy them to new projects and have it all work without a build step”
Comment from 14 Dec 2025 in “JSDoc is TypeScript” “TypeScript benefits can be had without a build step by leveraging JsDoc”
Comment from 13 Jul 2026 in “Why Vanilla JavaScript” - Comment from 15 Dec 2025 in “JSDoc is TypeScript”
- Comment from 15 Dec 2025 in “JSDoc is TypeScript”
Same checker as TypeScript
“The advantage of JSDoc is that the TypeScript compiler treats it as equivalent to TypeScript source code”
Comment from 15 Dec 2025 in “JSDoc is TypeScript” “I'm simply pointing out that using JSDoc is using TypeScript. It's the same language service.”
Comment from 15 Dec 2025 in “JSDoc is TypeScript” “Aside from the following, JSDoc is absolutely TypeScript.”
Comment from 15 Dec 2025 in “JSDoc is TypeScript” Covers most TypeScript features
“tuples, `&` operator, and even generics all work perfectly well inside a `@type` declaration”
Comment from 15 Dec 2025 in “JSDoc is TypeScript” “JSDoc lets you do pretty much everything that isn't a runtime feature of TypeScript”
Comment from 14 Dec 2025 in “JSDoc is TypeScript” “I haven't run into anything you can do in TypeScript that you can't do in JSDoc.”
Comment from 14 Dec 2025 in “JSDoc is TypeScript” - Comment from 15 Dec 2025 in “JSDoc is TypeScript”
Types live outside function parameters
“it makes code less dense because it lives outside the function parameters”
Comment from 14 Dec 2025 in “JSDoc is TypeScript” “jsdoc is nice because you don’t have to write the non-helpful types.”
Comment from 14 Dec 2025 in “JSDoc is TypeScript”
What people warn about
Each mark is one comment
Weaker than TypeScript for advanced types
“Support for generics is limited in JSDoc compared to TypeScript, especially when arrow function is involved.”
Comment from 14 Dec 2025 in “JSDoc is TypeScript” “JSDoc doesn't support everything you need in TypeScript and there is a lot of inlining”
Comment from 15 Dec 2025 in “JSDoc is TypeScript” “JSDoc is not as powerful as TypeScript types but that might be fine for your use case”
Comment from 13 Jul 2026 in “Why Vanilla JavaScript” - Comment from 14 Dec 2025 in “JSDoc is TypeScript”
- Comment from 14 Dec 2025 in “JSDoc is TypeScript”
Verbose and clumsy to write
“it's more annoying than just writing TypeScript”
Comment from 14 Dec 2025 in “JSDoc is TypeScript” “JavaScript with JSDoc is much more verbose, with a lot of limitations”
Comment from 14 Dec 2025 in “JSDoc is TypeScript” “this gets messy, repetitive and it's difficult to use algebraic types”
Comment from 15 Dec 2025 in “JSDoc is TypeScript” - Comment from 16 Dec 2025 in “JSDoc is TypeScript”
Some tags and imports fail
“@callback works the most of the time, except in such cases where these JSDoc tags don't work nicely together”
Comment from 15 Dec 2025 in “JSDoc is TypeScript” “Things like type star imports, destructured imports or satisfies operator don't work in jsdoc.”
Comment from 15 Dec 2025 in “JSDoc is TypeScript” “Whatever I do, there is always a error. Meanwhile, it does not take much to TS code to work.”
Comment from 15 Dec 2025 in “JSDoc is TypeScript” - Comment from 15 Dec 2025 in “JSDoc is TypeScript”
What people said
40 of the 64 comments that mention it, newest first. Each links to the original comment.
“JSDoc is not as powerful as TypeScript types but that might be fine for your use case”
“TypeScript benefits can be had without a build step by leveraging JsDoc”
“you do not need a build step and the javascript you ship to the browser would be the same you write in your editor”
“if you really need its key features just add JSDoc and Zod to any given vanilla JS codebase”
“Just make it a habit to write your types in JSDoc be done with it. It's so much nicer in every way.”
“JSDoc is ugly, clumsy, and leads to worse types on average over time.”
“JSDoc has been around for more than twenty years and most implementations have never had most of the capabilities you're describing.”
“Things like type star imports, destructured imports or satisfies operator don't work in jsdoc.”
“This. Or use ts-blank-space if you prefer TypeScript over JSDoc.”
“It's not perfect, but it gets you a long way.”
“there were annoying things that you would expect would work in JSDoc, but didn't quite”
“this gets messy, repetitive and it's difficult to use algebraic types”
“JSDoc doesn't support everything you need in TypeScript and there is a lot of inlining”
“Types for classes work exactly the same way”
“The advantage of JSDoc is that the TypeScript compiler treats it as equivalent to TypeScript source code”
“I'm simply pointing out that using JSDoc is using TypeScript. It's the same language service.”
“tuples, `&` operator, and even generics all work perfectly well inside a `@type` declaration”
“@callback works the most of the time, except in such cases where these JSDoc tags don't work nicely together”
“You can either define your types in JSDoc comments or in .ts files.”
“Aside from the following, JSDoc is absolutely TypeScript.”
“Whatever I do, there is always a error. Meanwhile, it does not take much to TS code to work.”
“I prefer not to add typescript lib and an additional build step”
“I've not yet come across a use-case JSDoc couldn't handle”
“JSDoc works great for buildless application setups!”
“That's technically a fair complaint but feels like a minor nitpick.”
“I haven't run into anything you can do in TypeScript that you can't do in JSDoc.”
“Support for generics is limited in JSDoc compared to TypeScript, especially when arrow function is involved.”
“JavaScript with JSDoc is much more verbose, with a lot of limitations”
“it's more annoying than just writing TypeScript”
“i think this is a good practice for every developer”
“The list of things jsdoc cannot do is long but a simple example is overloading”
“JSDoc lets you do pretty much everything that isn't a runtime feature of TypeScript”
“it makes code less dense because it lives outside the function parameters”
“JSDoc does actually have generic slots with the @template tag. Actually using them in practice is a little unintuitive”
“Modern HTML/CSS with Web Components and JSDoc is underrated.”
“jsdoc is nice because you don’t have to write the non-helpful types.”
“whenever I define a lambda, I need to add an doc type”
“there are plenty things you can't express in jsdoc but can in typescript”
“it's quite nice to just be able to copy them to new projects and have it all work without a build step”
“Type safety matters on the tooling side anyway.”
Counts come from 1,795,640 Hacker News comments, November 2025 to November 2026. How we count. Report a mistake.