JSDoc with TypeScript vs Flow

Two checkers for typed JavaScript

Flow and TypeScript are both checkers for JavaScript, and both can work on plain .js files with the types kept in comments: Flow through its comment syntax, TypeScript through JSDoc. They are separate checkers with separate type systems, and neither reads the other’s annotations.

Where they stand on 21 October 2026, per their own sites: Flow ships frequent releases (0.336.0 on 15 October 2026), and flow.org describes it as a typed dialect of JavaScript used in production at Meta. A 2021 post on Flow’s direction and its open source engagement is now marked historical on the Flow blog. TypeScript’s checker is the one most editors run for JavaScript, and the one packages publish .d.ts files for. We did not run Flow for this page.

The same function, typed both ways

Flow’s comment types put Flow syntax inside comments, so the file runs without a build: /*: Type */ after a name, and /*:: … */ around a whole declaration such as a type alias. To TypeScript those are ordinary comments, so the function below has an untyped parameter, which strict reports, and the wrong call at the bottom passes:

// @flow
/*:: type LineItem = { sku: string, quantity: number, unitCents: number }; */

export function totalCents(items /*: Array<LineItem> */) /*: number */ {error TS7006: Parameter 'items' implicitly has an 'any' type.
  let sum = 0;
  for (const item of items) sum += item.quantity * item.unitCents;
  return sum;
}

totalCents("not a list");

The JSDoc version of the same file, checked by tsc, with the wrong call caught:

/** @typedef {{ sku: string, quantity: number, unitCents: number }} LineItem */

/**
 * @param {LineItem[]} items
 * @returns {number}
 */
export function totalCents(items) {
  let sum = 0;
  for (const item of items) sum += item.quantity * item.unitCents;
  return sum;
}

totalCents("not a list");error TS2345: Argument of type 'string' is not assignable to parameter of type 'LineItem[]'.

type LineItem = { sku: string; quantity: number; unitCents: number };

export function totalCents(items: LineItem[]): number {
  let sum = 0;
  for (const item of items) sum += item.quantity * item.unitCents;
  return sum;
}

totalCents("not a list");error TS2345: Argument of type 'string' is not assignable to parameter of type 'LineItem[]'.

Moving from Flow to JSDoc

A file-by-file move works the way any migration to checked JavaScript does: add // @ts-check to a file, rewrite its annotations, remove // @flow. The translations are mostly mechanical:

Two differences need care rather than translation. Flow’s object types are exact by default, while TypeScript checks extra properties only on fresh object literals, so code that relied on exactness elsewhere loses that check. And Flow’s ?T means “may be null or undefined”, which is wider than TypeScript’s optional property a?: T. Run tsc with strict from the first file, so both show up as errors rather than surprises.

For packages, publish .d.ts files when you switch: shipping types from a JavaScript package covers writing them from JSDoc.