JSDoc *is* TypeScript

In May 2023, an internal refactoring pull request from the Svelte repository sparked significant discussion on Hacker News. This (superficially) controversial PR appeared to validate skepticism towards TypeScript, a position even held by notable figures such as Dan Abramov of the React team at the time. The perceived rejection of static typing benefits by a leading web framework was a major event. Consequently, Rich Harris clarified on Hacker News that this move was "not a vindication of anti-TypeScript positions".

Harris provided a thoughtful explanation, detailing why transitioning type declarations from .ts files to JSDoc comments within .js files was not a stance against TypeScript. He asserted Svelte's "commitment to TypeScript [was] stronger than ever." This incident led to numerous "TypeScript VS JSDoc" discussions across blogs and forums, frequently advocating for JSDoc as offering "all the benefits of TypeScript without the build step," despite its sometimes more verbose syntax. This article, however, aims to shift focus from the "vs" narrative. Instead, it proposes a crucial reinterpretation: JSDoc is TypeScript.

Background: TypeScript's Origins

In the late 2000s and early 2010s, JavaScript was largely regarded as an informal language, lacking essential development tooling such as autocomplete, symbol renaming, and type safety. Microsoft developers, averse to JavaScript's perceived shortcomings, often wrote C# code and utilized ScriptSharp to generate more type-safe JavaScript. This context forms the foundational origins of TypeScript.

TypeScript Powers IntelliSense

Even without writing code in .ts files, many developers are actively leveraging TypeScript. This is because TypeScript serves as the underlying engine for IntelliSense. Regardless of whether you use VS Code or another editor, features like code completion, parameter information, quick info, and member lists while coding in JavaScript are almost certainly powered by the TypeScript language service.

TypeScript Interprets JSDoc

The TypeScript language service is also responsible for interpreting JSDoc comments. This close integration is reflected in the TypeScript changelog, which frequently documents new JSDoc features. Furthermore, JSDoc-related IntelliSense can be configured via a tsconfig.json file, and the tsc compiler can be run on projects that use JSDoc for type annotations. In essence, if you're using JSDoc for type hints, you're already utilizing TypeScript.

Practical Experience with JSDoc

Based on a recent front-end rewrite of an older project, entirely typed using JSDoc comments, several key observations emerged:

• Feature Parity: With the exception of runtime features like enums (which were, regrettably, added to the language), nearly all capabilities expressible in TypeScript can also be achieved with JSDoc. While certain features, such as generics, might require a more verbose syntax—often necessitating explicit return type declarations to infer generic slots—this can paradoxically encourage stronger TypeScript practices by promoting reliance on type inference.
• Enhanced Navigation: When working with JSDoc-typed packages, navigating to a function definition (e.g., via CTRL/CMD + click) directs developers straight to the actual source code, rather than a separate type declaration file. This direct access is often preferred by developers.
• Tooling Reusability: TypeScript's extensive tooling is remarkably adaptable for JSDoc-based projects. This includes type generation libraries that can process backend schemas (e.g., OpenAPI or GraphQL) to produce corresponding frontend types. Many of these tools can be configured to generate types directly within JSDoc comments instead of traditional TypeScript definition files.

From the perspective of a dedicated TypeScript enthusiast, adopting JSDoc is not an anti-TypeScript stance. Instead, it offers the same robust static analysis benefits without requiring an additional build step. This approach is gaining traction; for instance, it was recently noted in discussions on Hacker News that the webpack project has also migrated to utilizing JSDoc for its internal typing.