A Node.js 24 service runs on built-in type stripping; which TypeScript constructs does it refuse at run time, and how do you fix each one?
answer
- anything that needs generated JavaScript
- enum, parameter properties, runtime namespaces
- type imports need the type keyword
- node_modules and paths are refused
basics
~20 sNode.js 24 type stripping refuses syntax that needs generated JavaScript (enum, parameter properties, namespaces with runtime code, import aliases), decorators, tsconfig paths aliases, .tsx and TypeScript under node_modules. Rewrite to erasable syntax, or build ahead.
solid answer
~40 sNode.js 24 only deletes type syntax, so anything that needs JavaScript *written* fails. `enum`, parameter properties, namespaces holding runtime code and `import x = require()` aliases throw `ERR_UNSUPPORTED_TYPESCRIPT_SYNTAX`; replace them with an `as const` object, explicit field assignments and plain modules. Decorators are not transformed and fail to parse. A type imported without `type` stays a value import, so an ES module fails at link time; use `import type`. `tsconfig.json` `paths` are never applied; subpath imports starting with `#` are the closest built-in feature. `.ts` files under `node_modules` throw `ERR_UNSUPPORTED_NODE_MODULES_TYPE_STRIPPING`, so dependencies must ship JavaScript. `--experimental-transform-types` covers the code-generating constructs, but it is a release candidate in 24 and removed in 26, so a build step is the durable fix.
code
typescript · 12 lines// status.ts: runs under Node 24 type stripping
export const Status = { Active: 'active', Disabled: 'disabled' } as const;
export type Status = (typeof Status)[keyof typeof Status];
export class Account {
status: Status;
constructor(status: Status) {
this.status = status;
}
}
console.log(new Account(Status.Active).status);go deeper
Recall that Node only deletes type syntax, so features that create runtime values, like enum, are rejected with ERR_UNSUPPORTED_TYPESCRIPT_SYNTAX.
Explain the erasable test and give the rewrite for each refused construct: as const objects, explicit field assignment, import type, and real file extensions.
Diagnose a startup crash from the error code alone, and know the node_modules refusal forces shared libraries to be published as JavaScript.
Weigh rewriting to erasable syntax against keeping a build step, given that the transform flag is a release candidate in 24 and gone in 26.
## The rule behind every refusal Node.js 24 runs TypeScript by **type stripping**: it overwrites type-only syntax with whitespace and runs the JavaScript that remains. Nothing is ever *added*. So the question "will this run?" reduces to one test: **can this construct be deleted without changing what the program does?** If yes, it is *erasable* and runs. If running it requires the compiler to emit JavaScript, Node refuses it, usually at startup when the module is loaded. ## Constructs that need code generation These throw `ERR_UNSUPPORTED_TYPESCRIPT_SYNTAX` (a `SyntaxError`) when the module loads: - **`enum` declarations.** An enum creates a runtime object, so deleting it would leave references to nothing. - **Parameter properties**, such as `constructor(private repo: Repo) {}`. The `private` modifier makes the compiler write `this.repo = repo`, which stripping cannot do. - **`namespace` blocks with runtime code.** A namespace that only exports types is erasable and runs; one that exports a value needs a generated object. - **Import aliases** of the `import fs = require('fs')` form. The erasable rewrites are mechanical: | Refused | Erasable replacement | |---|---| | `enum Status { Active = 'active' }` | `const Status = { Active: 'active' } as const;` plus a derived `type Status` | | `constructor(private repo: Repo) {}` | declare the field, assign `this.repo = repo` in the body | | `namespace Util { export const x = 1 }` | an ordinary module with `export const x` | | `import fs = require('fs')` | `import fs from 'node:fs'` or `const fs = require('node:fs')` | ## Constructs that fail for other reasons 1. **Decorators.** They are a TC39 Stage 3 proposal, so Node does not transform them and its parser rejects them. Code built around decorators needs a build step or a full-syntax runner. 2. **Type imports without `type`.** `import { User, loadUser } from './user.ts'` keeps `User` as a value import. In an ES module, linking fails with a `SyntaxError` that the requested module does not provide an export named `User`. Write `import type { User }` or an inline `type User` modifier. Configuring the compiler's `verbatimModuleSyntax` option makes the editor flag these before Node does. 3. **`tsconfig.json` `paths` aliases.** Node never reads `tsconfig.json`, so `@app/db` style aliases do not resolve and the import errors. The closest Node feature is **subpath imports** in `package.json`, whose keys must start with `#`. 4. **Extensionless relative imports.** `import './db'` does not find `db.ts`; specifiers must name the real file, `./db.ts`. 5. **`.tsx` files**, which are unsupported. ## TypeScript inside `node_modules` Node refuses to strip any file whose path is under a `node_modules` directory and throws `ERR_UNSUPPORTED_NODE_MODULES_TYPE_STRIPPING`. The documentation states the reason plainly: to discourage package authors from publishing TypeScript. The practical consequence for a service team is that a shared internal library must be published as compiled JavaScript; consuming its raw `.ts` sources through `node_modules` will fail even though the same files would run from the application's own tree. ## The escape hatch and why it is temporary `--experimental-transform-types` tells Node to *transform* the code-generating constructs instead of refusing them, and it implies `--enable-source-maps` because transformed code no longer lines up with the source. In Node 24 it is a **release candidate**, and the Node 26 documentation records the flag as **removed** in v26.0.0. Building a production service on it means a forced rewrite at the next LTS upgrade. Decorators stay unsupported even with it. ## When the failure shows up Stripping happens as each module is **loaded**, not when the process starts. A refused construct in the entry file's static import graph crashes the service at startup, which is noisy but safe. The same construct in a module reached only through a dynamic `import()`, for example a rarely used admin route or a lazily loaded report generator, fails the first time that path runs, possibly days after a deploy. That is why a startup smoke test alone is not enough and why the check belongs in the compiler, which sees every file. ## How to keep a codebase inside the line - Turn on the compiler's `erasableSyntaxOnly` option (TypeScript 5.8 or newer) so non-erasable syntax is a compile error in the editor and CI rather than a crash at startup. - Run `tsc --noEmit` as a separate gate; Node never checks types. - When a framework or library depends on decorators or enums, compile ahead of time instead of fighting the constraint. A senior answer names the refusal, the error the operator will see, and the rewrite, and knows which of the three is a code change versus a delivery-model change.
- A monorepo's shared package is consumed from node_modules as raw .ts files; why does the Node 24 service crash, and what fixes it?Node refuses to strip files under a `node_modules` path and throws `ERR_UNSUPPORTED_NODE_MODULES_TYPE_STRIPPING`; the rule exists to discourage publishing TypeScript. The fix is to publish the shared package as compiled JavaScript (with declarations for type checking), so the service loads JavaScript from `node_modules` and keeps stripping only its own sources.
- Why is `--experimental-transform-types` a poor long-term answer to an enum-heavy codebase on Node 24?It transforms enums and parameter properties instead of refusing them, but in Node 24 it is only a release candidate and the Node 26 documentation lists it as removed in v26.0.0. Depending on it ties the service to one LTS line. Rewriting to erasable syntax or compiling ahead removes the dependency.
- Every TypeScript feature works in Node 24, only slower.
- A namespace that only exports types throws under type stripping.
- tsconfig paths aliases resolve because Node reads tsconfig.json.
- Decorators work once --experimental-transform-types is passed.
- Dependencies can ship .ts because Node strips node_modules too.
Assumes Node.js 24, where type stripping is stable (v24.12.0) and --experimental-transform-types is a release candidate; Node 26 removes that flag.