JSDoc is TypeScript

Source: Hacker News

Overview

In May 2023 an internal refactoring PR from the Svelte repo made it to the front page of Hacker News. The (superficially) controversial PR seemed to vindicate TypeScript skeptics / luddites (at the time including figures like Dan Abramov of the React team). The premier darling of web frameworks ostensibly rejecting static typing, this was a big deal. Rich Harris responded on HN (link) to explain that the move from .ts files to JSDoc comments in .js files was not a vindication of anti‑TypeScript positions.

Harris argued that Svelte’s “commitment to TypeScript […] stronger than ever.” This sparked a wave of “TypeScript vs JSDoc” posts defending JSDoc as “all the benefits of TypeScript without the build step” (albeit with a sometimes clunkier syntax).

Instead of that framing, I propose a subtler substitution: JSDoc is TypeScript.

Some background

TypeScript is C#?

(No, but it explains much of TS’s early development)

In the late 2000s / early 2010s JavaScript was often seen as unserious. Tooling lacked autocomplete, rename‑symbol, type safety, etc. Microsoft developers would write C# code and use a tool called ScriptSharp to generate slightly more type‑safe JavaScript. These are the origins of TypeScript.¹ Fundamentally, it began as a build tool to make writing JS less error‑prone.

TypeScript is IntelliSense!

Even if you don’t write .ts files, you’re probably using TypeScript because it powers the IntelliSense engine. If your editor provides code completion, parameter info, quick info, or member lists while you write JavaScript, it is almost certainly running the TypeScript language service.

TypeScript is JSDoc :)

The same TypeScript language service interprets JSDoc comments. That’s why the TypeScript CHANGELOG often includes notes about JSDoc features.² It also explains why JSDoc‑related IntelliSense can be governed by a tsconfig.json file and why you can run tsc on a project typed with JSDoc comments. In short, you are already using TypeScript.

My Own Experience

I recently rewrote the front‑end of an old project, typing everything with JSDoc comments. Here are some takeaways:

• Apart from runtime features like enums, you can express essentially everything in TypeScript via JSDoc. Certain features (e.g., generics) are clunkier, requiring you to annotate return types to infer generic slots. Sometimes the extra verbosity encourages better practices by pushing developers toward type inference.
• For packages typed with JSDoc, Ctrl/Cmd‑clicking a function jumps to the actual implementation rather than a separate declaration file—a workflow I much prefer.
• TypeScript tooling works surprisingly well for JSDoc projects. This includes type‑generation libraries that consume schemas (e.g., OpenAPI or GraphQL) and emit JSDoc comments instead of TypeScript code.

Take it from a self‑confessed TypeScript nerd: JSDoc is not an anti‑TypeScript stance; it provides the same powerful static analysis without a separate build step.

• The reason enums were, regrettably, added to the language¹.
• A miserable sidenote: becoming a TypeScript expert means accepting that half of the documentation lives in the changelog. For example, see the entry on unique symbols.²

Footnotes

1. See the original discussion of TypeScript’s origins. ↩ ↩²

2. See the TypeScript 5.5 release notes for JSDoc import tag details. ↩ ↩²