JSDoc-typed JavaScript vs Node's type stripping

What type stripping is

Since version 22.6, Node.js can run a .ts file directly: it replaces the type annotations with whitespace and runs what is left as JavaScript. Per the Node.js documentation and release notes, it arrived behind --experimental-strip-types in 22.6.0 (August 2024), became the default in 23.6.0 (January 2025) and in the 22.x line from 22.18.0 (July 2025), and was marked stable in 25.2.0 (November 2025) and 24.12.0. The documentation lists the feature as stable today. We did not run Node.js for this page; the version history is the documentation’s.

That removes one of the oldest arguments for JSDoc in Node.js code: “TypeScript needs a build step”. For an application or a script on a current Node.js, it no longer does.

What it does not do

Stripping is not checking. Per the Node.js documentation, no type checking is performed: a .ts file with a type error runs, and fails or not at runtime exactly as the equivalent JavaScript would. You still run tsc, in the editor and in CI, exactly as you would for JSDoc-typed JavaScript. The checking half of the workflow is identical; only the syntax of the types and the file extension change.

The documentation lists the other limits:

• Only erasable syntax. Anything that needs JavaScript written in its place is an error at runtime: enum, a namespace with values in it, parameter properties, import x = require() aliases. Decorators are a parse error. The --experimental-transform-types flag that once handled some of these was removed in Node.js 26.
• No tsconfig.json. Node.js ignores it, so paths, baseUrl and the rest have no effect at runtime.
• Explicit extensions and type-only imports. Imports name the .ts file, and an import that brings in only types must say import type, or the program fails when it loads.
• Not in node_modules. Files under node_modules are not stripped, so packages must still publish JavaScript.

Matching tsc to what Node.js can run

TypeScript 5.8 added erasableSyntaxOnly for exactly this: it reports every construct Node.js cannot erase, as TS1294. With it on, the TypeScript spelling of a module either runs under Node.js or fails tsc. The JavaScript tab of each example below is the JSDoc version, which runs everywhere; the TypeScript tab is checked with erasableSyntaxOnly and verbatimModuleSyntax on:

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

export const FREE_SHIPPING_CENTS = 5000;

/**
 * @param {LineItem[]} items
 * @returns {number}
 */
export function shippingCents(items) {
  const subtotal = items.reduce((sum, item) => sum + item.quantity * item.unitCents, 0);
  return subtotal >= FREE_SHIPPING_CENTS ? 0 : 500;
}

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

export const FREE_SHIPPING_CENTS = 5000;

export function shippingCents(items: LineItem[]): number {
  const subtotal = items.reduce((sum, item) => sum + item.quantity * item.unitCents, 0);
  return subtotal >= FREE_SHIPPING_CENTS ? 0 : 500;
}

export const Status = /** @type {const} */ ({ Open: "open", Paid: "paid" });
/** @typedef {(typeof Status)[keyof typeof Status]} StatusValue */

export class Order {
  /**
   * @param {string} id
   * @param {StatusValue} status
   */
  constructor(id, status = Status.Open) {
    this.id = id;
    this.status = status;
  }
}

export enum Status {error TS1294: This syntax is not allowed when 'erasableSyntaxOnly' is enabled.
  Open = "open",
  Paid = "paid",
}

export class Order {
  constructor(public id: string, public status: Status = Status.Open) {}error TS1294: This syntax is not allowed when 'erasableSyntaxOnly' is enabled.error TS1294: This syntax is not allowed when 'erasableSyntaxOnly' is enabled.
}

The JSDoc side needed no special option: JavaScript has no enum and no parameter properties, so the same subset is the only one available. That is the convergence in one sentence: TypeScript code written for type stripping and JavaScript written with JSDoc now avoid the same constructs.

So which?

For code that runs only on Node.js 22.18 or later, the choice is now about syntax and taste: TypeScript annotations are shorter, JSDoc runs everywhere. Two cases still point to JSDoc: packages, because Node.js will not strip types inside node_modules and you publish JavaScript anyway, and code that also runs in browsers or older runtimes without a build. In both, a .js file with JSDoc is the file that ships, and tsc checks it the same way.