Hacker ApprovedDepartments

JSDoc

Hacker Approved

Type 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%
Each figure is one person. RecommendsCriticizes

Recommended in 4 of 13 months

  1. November 2025: recommended
  2. December 2025: recommended
  3. January 2026: not recommended
  4. February 2026: not recommended
  5. March 2026: not recommended
  6. April 2026: not recommended
  7. May 2026: recommended
  8. June 2026: not recommended
  9. July 2026: recommended
  10. August 2026: not recommended
  11. September 2026: not recommended
  12. October 2026: not recommended
  13. 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”
  • 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”
  • 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”
  • 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”
  • 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”

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”

MixedComment from 13 Jul 2026 in “Why Vanilla JavaScript”

“TypeScript benefits can be had without a build step by leveraging JsDoc”

RecommendsComment from 13 Jul 2026 in “Why Vanilla JavaScript”

“you do not need a build step and the javascript you ship to the browser would be the same you write in your editor”

RecommendsComment from 13 Jul 2026 in “Why Vanilla JavaScript”

“if you really need its key features just add JSDoc and Zod to any given vanilla JS codebase”

RecommendsComment from 8 Jul 2026 in “TypeScript 7”

“Just make it a habit to write your types in JSDoc be done with it. It's so much nicer in every way.”

RecommendsComment from 23 May 2026 in “Deno 2.8”

“JSDoc is ugly, clumsy, and leads to worse types on average over time.”

CriticizesComment from 16 Dec 2025 in “JSDoc is TypeScript”

“JSDoc has been around for more than twenty years and most implementations have never had most of the capabilities you're describing.”

MixedComment from 16 Dec 2025 in “JSDoc is TypeScript”

“Things like type star imports, destructured imports or satisfies operator don't work in jsdoc.”

CriticizesComment from 15 Dec 2025 in “JSDoc is TypeScript”

“This. Or use ts-blank-space if you prefer TypeScript over JSDoc.”

RecommendsComment from 15 Dec 2025 in “JSDoc is TypeScript”

“It's not perfect, but it gets you a long way.”

MixedComment from 15 Dec 2025 in “JSDoc is TypeScript”

“there were annoying things that you would expect would work in JSDoc, but didn't quite”

CriticizesComment from 15 Dec 2025 in “JSDoc is TypeScript”

“this gets messy, repetitive and it's difficult to use algebraic types”

CriticizesComment from 15 Dec 2025 in “JSDoc is TypeScript”

“JSDoc doesn't support everything you need in TypeScript and there is a lot of inlining”

CriticizesComment from 15 Dec 2025 in “JSDoc is TypeScript”

“Types for classes work exactly the same way”

RecommendsComment from 15 Dec 2025 in “JSDoc is TypeScript”

“The advantage of JSDoc is that the TypeScript compiler treats it as equivalent to TypeScript source code”

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

RecommendsComment from 15 Dec 2025 in “JSDoc is TypeScript”

“tuples, `&` operator, and even generics all work perfectly well inside a `@type` declaration”

RecommendsComment from 15 Dec 2025 in “JSDoc is TypeScript”

“@callback works the most of the time, except in such cases where these JSDoc tags don't work nicely together”

MixedComment from 15 Dec 2025 in “JSDoc is TypeScript”

“You can either define your types in JSDoc comments or in .ts files.”

RecommendsComment from 15 Dec 2025 in “JSDoc is TypeScript”

“Aside from the following, JSDoc is absolutely TypeScript.”

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

CriticizesComment from 15 Dec 2025 in “JSDoc is TypeScript”

“I prefer not to add typescript lib and an additional build step”

RecommendsComment from 15 Dec 2025 in “JSDoc is TypeScript”

“I've not yet come across a use-case JSDoc couldn't handle”

RecommendsComment from 15 Dec 2025 in “JSDoc is TypeScript”

“JSDoc works great for buildless application setups!”

MixedComment from 15 Dec 2025 in “JSDoc is TypeScript”

“That's technically a fair complaint but feels like a minor nitpick.”

RecommendsComment from 15 Dec 2025 in “JSDoc is TypeScript”

“I haven't run into anything you can do in TypeScript that you can't do in JSDoc.”

RecommendsComment from 14 Dec 2025 in “JSDoc is TypeScript”

“Support for generics is limited in JSDoc compared to TypeScript, especially when arrow function is involved.”

CriticizesComment from 14 Dec 2025 in “JSDoc is TypeScript”

“JavaScript with JSDoc is much more verbose, with a lot of limitations”

CriticizesComment from 14 Dec 2025 in “JSDoc is TypeScript”

“it's more annoying than just writing TypeScript”

MixedComment from 14 Dec 2025 in “JSDoc is TypeScript”

“i think this is a good practice for every developer”

RecommendsComment from 14 Dec 2025 in “JSDoc is TypeScript”

“The list of things jsdoc cannot do is long but a simple example is overloading”

CriticizesComment from 14 Dec 2025 in “JSDoc is TypeScript”

“JSDoc lets you do pretty much everything that isn't a runtime feature of TypeScript”

RecommendsComment from 14 Dec 2025 in “JSDoc is TypeScript”

“it makes code less dense because it lives outside the function parameters”

MixedComment from 14 Dec 2025 in “JSDoc is TypeScript”

“JSDoc does actually have generic slots with the @template tag. Actually using them in practice is a little unintuitive”

MixedComment from 14 Dec 2025 in “JSDoc is TypeScript”

“Modern HTML/CSS with Web Components and JSDoc is underrated.”

RecommendsComment from 14 Dec 2025 in “JSDoc is TypeScript”

“jsdoc is nice because you don’t have to write the non-helpful types.”

RecommendsComment from 14 Dec 2025 in “JSDoc is TypeScript”

“whenever I define a lambda, I need to add an doc type”

MixedComment from 14 Dec 2025 in “JSDoc is TypeScript”

“there are plenty things you can't express in jsdoc but can in typescript”

CriticizesComment from 14 Dec 2025 in “JSDoc is TypeScript”

“it's quite nice to just be able to copy them to new projects and have it all work without a build step”

RecommendsComment from 14 Dec 2025 in “JSDoc is TypeScript”

“Type safety matters on the tooling side anyway.”

RecommendsComment from 14 Dec 2025 in “JSDoc is TypeScript”

Counts come from 1,795,640 Hacker News comments, November 2025 to November 2026. How we count. Report a mistake.