Node.js Dropped --experimental-transform-types: What Breaks and How to Fix It

Somewhere in the Node.js 26 release notes, sandwiched between a Temporal API announcement and a GCC version bump, is a single bullet point that broke more projects than anything else in that changelog: --experimental-transform-types is gone. Not deprecated. Not warned about for a release or two first. Removed.

If you have been running TypeScript enums, namespaces, or parameter properties directly with node and that flag, your code stopped running the moment you upgraded. And here is the part that catches teams off guard: this is not a Node 26 story. The same removal landed in Node 25.2.0 and, far more importantly, in a patch release of the Node 24 LTS line, 24.12.0. If your CI pins 24.x instead of an exact version, you can wake up to a red pipeline without a single major version number changing anywhere in your repo.

This guide walks through exactly what changed, why enums and namespaces were never going to survive the transition, and how to migrate every affected pattern before the October 2026 LTS cutover forces the issue.

Node's native TypeScript support runs your .ts file through amaro, a thin wrapper around the Rust-based SWC compiler. There were always two modes, and only one of them was ever meant to be permanent.

Strip mode, originally behind --experimental-strip-types and the default behaviour since Node 22.18.0 and 24.3.0, deletes type annotations and replaces them with whitespace. A : number becomes four spaces. Line numbers and column offsets stay identical, which is why stack traces from a stripped file still point at the right place with no source map. Nothing about the JavaScript underneath changes, because nothing needs to.

Transform mode did more. Enums, namespaces, and constructor parameter properties do not merely carry type information, they compile into different runtime code. An enum becomes an object with forward and, for numeric members, reverse key mappings. A namespace becomes an IIFE that assigns onto a namespace object. A parameter property becomes an explicit this.x = x assignment inside the constructor body. Transform mode ran that compilation step inside Node itself.

That is the part the Node TSC decided not to keep carrying. A transform is not a stable target: it changes as TypeScript changes, and it puts Node in the position of shipping and versioning a TypeScript compiler in core. Strip mode has no such problem, because it does not need to know what TypeScript means, only which characters are annotations. After roughly two years behind an experimental flag, transform mode was removed with no replacement.

You no longer choose between these. Strip-only is all Node ships, so the decision moved out of a flag and into your source code.

The mental model worth internalising is simple, and it is the same rule the TypeScript team encoded into erasableSyntaxOnly: if deleting the syntax leaves valid JavaScript behind, it strips. If new JavaScript has to be generated in its place, it does not. Every breakage in this post is a direct consequence of that one sentence.

Run a file containing a plain enum on Node 26 (or 24.12+, or 25.2+) and you get a syntax error before a single line of your program executes:

Namespaces with runtime content and constructor parameter properties produce the same error code with a different message. Two details about this failure are worth calling out, because both surprise people.

First, it is a parse error, not a runtime one. The file does not partially execute. Nothing above the offending line runs, no side effect fires, and no try/catch anywhere in your application will catch it. From your process manager's point of view the service simply refused to boot.

Second, your editor will not warn you about it. TypeScript considers all of this syntax completely valid, because it is: tsc compiles enums and namespaces happily and always has. The compiler has no opinion about what Node's stripper can handle unless you explicitly ask it to have one, which is the next thing to fix.

Before rewriting anything, make the compiler tell you where the problems are. TypeScript 5.8 added a compiler option built specifically for this transition. With erasableSyntaxOnly enabled, tsc reports every non-erasable construct as a compile error, in your editor, as you type, instead of at runtime in a CI job:

verbatimModuleSyntax belongs in the same change, and it is the flag people skip. Without it, an import of something that turns out to be a type gets left in the output as a real import. Stripping preserves it, Node tries to resolve a value that does not exist at runtime, and you get a module resolution error that looks nothing like a type problem. With verbatimModuleSyntax on, TypeScript forces the type keyword on type-only imports and the ambiguity disappears.

If you want the whole config generated rather than assembled by hand, the tsconfig Builder outputs a Node-ready file with both flags already set.

Four patterns account for essentially every failure. Each has a mechanical rewrite, and three of the four are pure syntax swaps with no behaviour change at all.

Not every codebase can absorb this refactor before its next Node upgrade, and a large NestJS monolith full of parameter properties is a genuinely multi-sprint job. Three options buy you time.

Pin an exact Node version below the removal. Note that pinning the LTS line is not enough: 24.x and ^24.0.0 both resolve to 24.12.0 or later. You need a concrete version such as 24.11.1, set in .nvmrc, engines, your Volta config, and your Docker base image tag, because a single unpinned one of those undoes the other three.

Put a real compiler back in the loop. tsx and ts-node still transform enums, namespaces, and parameter properties, so they remain a working local-development and CI path. Compiling with tsc or esbuild before deploying sidesteps the question entirely, and if you already build before shipping then none of this affects your production artefact at all. It only ever affected running node file.ts with no build step.

For new services, Deno is worth a look: it runs enums and namespaces natively with no flag and never had this limitation, since it ships a full TypeScript compiler rather than a stripper. The Deno tutorial covers the runtime differences if you have not used it recently.

One closing note on sequencing. Because this is a parse error rather than a type error, a green tsc --noEmit proves nothing on its own unless erasableSyntaxOnly is on. Add the flag first, then migrate, then run the actual test suite on the actual target Node version. Teams that skip the last step tend to find the remaining files in production. If you are also mid-way through a compiler upgrade, the TypeScript 7 migration guide covers how to sequence both changes without stalling feature work.

The removal of --experimental-transform-types is a small changelog line with an outsized blast radius, mostly because it reached an LTS line through a patch release. The migration itself is mechanical: four patterns, three of them pure syntax swaps. The part worth doing carefully is the audit, and the part worth doing permanently is erasableSyntaxOnly, so this never has to be a migration again. For the other TypeScript tooling break to plan around this year, see why the TypeScript 7 upgrade broke ESLint and ts-jest.