JSDoc-typed JavaScript vs TypeScript files

One checker, two syntaxes

A .js file with JSDoc and a .ts file are read by the same checker, so the same mistake gets the same error. Switch tabs on the example to compare the two spellings of one module:

/**
 * @typedef {object} Line
 * @property {string} sku
 * @property {number} quantity
 * @property {number} unitCents
 */

/**
 * @param {Line[]} lines
 * @returns {number}
 */
export function invoiceTotal(lines) {
  return lines.reduce((sum, line) => sum + line.quantity * line.unitCents, 0);
}

invoiceTotal([{ sku: "TEA-01", quantity: "2", unitCents: 450 }]);error TS2322: Type 'string' is not assignable to type 'number'.

interface Line {
  sku: string;
  quantity: number;
  unitCents: number;
}

export function invoiceTotal(lines: Line[]): number {
  return lines.reduce((sum, line) => sum + line.quantity * line.unitCents, 0);
}

invoiceTotal([{ sku: "TEA-01", quantity: "2", unitCents: 450 }]);error TS2322: Type 'string' is not assignable to type 'number'.

Everything that follows from the checker is shared: the error codes, strict and the other options, editor hovers and completions, and the .d.ts files tsc writes for a package. What differs is where the types are written and what runs.

What runs

The .js file runs exactly as written: Node.js, browsers, Deno and Bun all skip the comments. A .ts file has to become JavaScript first, either through a build (tsc, a bundler, a framework’s compiler) or through a runtime that strips the types as it loads the file, which Node.js does by default since 22.18 and 23.6 (JSDoc vs Node’s type stripping compares the two). Either way, the code you debug is the code you wrote only in the .js case, unless source maps bridge the gap.

What only TypeScript syntax can say

JSDoc covers types: every type expression TypeScript has works inside the braces, including generics, conditional and mapped types. What it cannot write is TypeScript syntax that does something at runtime or changes how the code is parsed: enum, namespace with code in it, parameter properties (constructor(private name: string)), abstract, and type arguments at a call site. In a .js file those are errors from the 8000 range, each pointing at the JSDoc to use instead:

export function cartTotal(prices: number[]): number {error TS8010: Type annotations can only be used in TypeScript files.error TS8010: Type annotations can only be used in TypeScript files.
  return prices.reduce((sum, price) => sum + price, 0);
}

export let itemCount: number = 0;error TS8010: Type annotations can only be used in TypeScript files.

export function first<T>(items: T[]): T | undefined {error TS8004: Type parameter declarations can only be used in TypeScript files.error TS8010: Type annotations can only be used in TypeScript files.error TS8010: Type annotations can only be used in TypeScript files.
  return items[0];
}

The JSDoc replacements are ordinary JavaScript: a const object and a union @typedef instead of enum, a field and a constructor assignment instead of a parameter property, a typed argument instead of a type argument. TypeScript’s own erasableSyntaxOnly option (5.8) asks .ts files to give up the same runtime syntax, so code written either way is converging on the same subset.

Where JSDoc is looser

A .js file is read with a few allowances for existing JavaScript: an object literal can gain properties after it is created, an untyped parameter is optional, and a value’s name works as a type. How TypeScript reads a JavaScript file has the full list, with the .ts behavior beside each. TypeScript 7.0 removes several of them, so code written in the strict style checks the same in both.

Cost in practice

JSDoc is longer for the same types: a parameter type takes a tag line instead of a few characters after a colon, and a complex generic signature can take a paragraph. Teams that choose JSDoc usually accept that for the benefit of shipping the code they wrote; teams that choose TypeScript usually already have a build. The list of projects that check JavaScript with JSDoc records the reasons several large projects gave for their choice.