Alternative to #63853 or #63869

Problem

By default, Node.js refuses to strip types from .ts/.mts/.cts files under node_modules, throwing ERR_UNSUPPORTED_NODE_MODULES_TYPE_STRIPPING. The restriction protects editor/tsc performance: a dependency that ships raw TypeScript without declarations forces consumers to infer types from its source (“slow types”).

But using the folder as the boundary also blocks legitimate cases where trusted first-party TypeScript ends up under node_modules and does ship declarations:

• monorepo deploys that copy workspace packages into a real node_modules (pnpm deploy),
• packages installed from a private registry or a Git URL,
• globally installed TypeScript CLIs.

Solution

Add an experimental, opt-in flag, --experimental-strip-types-in-node-modules-with-declarations. Under it, a TypeScript file under node_modules is stripped and executed when a co-located declaration sits beside it (foo.d.ts next to foo.ts) — the default layout emitted by tsc --emitDeclarationOnly. The gate is a single stat, and requires type-stripping to be enabled (rejected with --no-strip-types). Otherwise the existing error is thrown.

Each of the blocked workflows already runs a build or publish step, so producing declarations is cheap: the same CI that assembles a pnpm deploy, publishes to a private registry, or packs a global CLI can run tsc --emitDeclarationOnly to emit .d.ts files beside the sources. That one artifact then both satisfies Node’s gate and ships ready-to-consume types, so the raw .ts runs with no separate JavaScript build — which is the thing these users are actually asking for.

It also keeps the TypeScript team’s guarantee intact. The restriction exists to stop a dependency’s raw, undeclared source from dragging down a consumer’s editor and tsc; by tying execution to the presence of a declaration, Node will only run raw .ts from a package that already provides one, so the consumer’s tooling always resolves a .d.ts and never falls back to inferring types across a dependency. The runtime permission is bound to the same artifact that keeps editing fast, rather than to where the code happens to live.

Notes

• Co-located only. A declaration reachable only through a separate directory (via the exports "types" condition) is not recognized in this initial version; adding that is a small follow-up if the layout proves common.
• Flagged, but should be unflaggable. It is behind an experimental flag for now to gauge reaction, but the intent is that this should be something that we can enable by default in the future. Since this preserves the gate that requires public registry packages to contain type declarations, it avoids the pollution of the public registry with TypeScript files that lack accompanying .d.ts files.
• Alternatives considered: module: allow type stripping in node_modules #63853 removes the restriction outright; module: add --experimental-strip-private-modules  #63869 gates on private: true (which can’t cover private-registry packages and doesn’t address editor performance).

@nodejs/typescript @anonrig @marco-ippolito @RyanCavanaugh