Running TypeScript Build Scripts Directly in Node.js

A route‑checking script runs successfully even though it assigns a number to a variable declared as a string. Node exits with zero. TypeScript reports an error.
Nothing mysterious has happened. Node removed the type annotation and executed the remaining JavaScript. The type checker checked the annotation. They were doing different jobs, and the successful command only proves that one of those jobs finished.
Native TypeScript execution is useful for small build and maintenance scripts, particularly when a separate runner exists mainly to remove annotations. I'd happily remove a dependency which no longer earns its place. I'd be less pleased to discover that its replacement had also removed the only type check from CI.
Pin the Runtime Before Changing the Command
Node 22.18.0 enabled type stripping by default in July. That makes a direct node command possible without the earlier enabling flag. The feature is still experimental at this point; the absence of a warning is not a stable‑support declaration.
The earlier Node 22.6.0 release introduced --experimental-strip-types. The distinction matters if a laptop has a newer patch than CI. "We use Node 22" is not specific enough to explain why the same command behaves differently.
For the example below, I use 22.18.0 and record node --version beside the result. Check the actual build environment too. An engine range in a package manifest expresses a requirement; it does not prove which executable a hosted build selected.
My article on JavaScript build tools and module formats covers why these tool boundaries exist. Here, the aim is narrower: run one compatible script directly whilst keeping its other checks intact.
Keep the Example Small Enough to Inspect
This first file, routes.mts, accepts unknown input and returns a validated list of local paths:
export type Route = { path: string };
export function parseRoutes(input: unknown): Route[] {
if (!Array.isArray(input)) throw new Error('Expected a route array');
const seen = new Set<string>();
return input.map((item: unknown) => {
if (typeof item !== 'object' || item === null ||
!('path' in item) || typeof item.path !== 'string' ||
!/^\/(?!\/)[^?#\\\s]*$/.test(item.path)) {
throw new Error('Expected a local path');
}
if (seen.has(item.path)) throw new Error('Duplicate path');
seen.add(item.path);
return { path: item.path };
});
}The second file, check-routes.mts, provides a default input and prints the count:
import { parseRoutes, type Route } from './routes.mts';
const input: unknown = JSON.parse(process.argv[2] ?? '[{"path":"/articles/"}]');
const routes: Route[] = parseRoutes(input);
const count: number = routes.length;
console.log(`Validated ${count} routes.`);Run node check-routes.mts and it prints Validated 1 routes.. Both files use .mts, making their ES module interpretation explicit. The relative import includes its extension, and Route is marked as a type import because it does not exist as a value after stripping.
This is a deliberately modest route check. It rejects duplicate paths, external‑style // paths, queries, fragments, backslashes, and whitespace. It doesn't establish that a route exists, resolve redirects, or implement a complete URL‑normalisation policy. A real generator should check the rules its output actually needs.
Make the Type Error Visible
Change just count: number to count: string. Run the script again. It still prints the same result and exits successfully. The annotation has disappeared before JavaScript executes.
Now install the separate checker in your project and run it against these files:
yarn add --dev typescript@5.8.3 @types/node@22.18.0
yarn exec tsc --noEmit --strict --target ES2022 --module NodeNext \
--allowImportingTsExtensions --erasableSyntaxOnly \
--verbatimModuleSyntax routes.mts check-routes.mtsThe changed declaration produces TS2322 and a non‑zero exit. Restore number and the same check passes. In my fixture, the compiler exited with 2 for that type error, whilst Node exited with 0 for execution. CI should treat a non‑zero check as failure rather than relying on that particular numeric code forever.
--noEmit keeps the check from producing another set of JavaScript files. erasableSyntaxOnly helps reject TypeScript constructs which need generated runtime code. verbatimModuleSyntax makes the distinction between value and type imports explicit to the checker. These flags belong to the TypeScript check; Node does not read a tsconfig.json and adopt its settings.
Once the commands are established, put the checker options in the appropriate project configuration and run the check before execution. Removing a runtime loader need not remove the compiler from development dependencies. It still has useful work to do.
Test Syntax Support Separately
A type error and unsupported syntax fail at different boundaries. To see the latter, save this as enum.mts:
enum Output { JSON, Text }
console.log(Output.JSON);The ordinary stripping path rejects it. An enum needs runtime JavaScript generated from its declaration; merely removing an annotation cannot supply that object. Constructor parameter properties have a similar requirement.
Node 22.18 also has an optional --experimental-transform-types flag, which makes this enum example run. That is a separate, experimental transform path. It should not quietly become a dependency of a script described as using only type stripping, and it does not turn Node into a complete TypeScript project runner.
These are the useful outcomes to keep distinct on the pinned baseline:
| Input or change | Node execution | Separate type check |
|---|---|---|
| Original two files | Passes | Passes |
| Change count to string | Passes | Fails with TS2322 |
| Enum under ordinary stripping | Rejects unsupported syntax | Fails with erasableSyntaxOnly |
| Supply a numeric path in JSON | Rejects the input | Source still passes |
The last row is reproducible with node check-routes.mts '[{"path":4}]'. Static types cannot certify data which arrives after the check ran. The explicit validation in parseRoutes remains necessary. My JSON parsing guide explains the conversion boundary; valid JSON is not automatically a valid application record.
Keep Module Resolution Explicit
Node's TypeScript documentation for 22.18.0 describes further limits which are easy to miss when one file works.
Remove .mts from the relative import and resolution fails. Remove type before Route and Node tries to import a value which was erased. Rename the entry file to .tsx and the native path rejects that extension, even if the file contains no JSX. These are module and loader constraints, not proof that the route calculation is wrong.
A paths alias can satisfy the type checker whilst still failing in Node, because those mappings are not rewritten by stripping. TypeScript source inside node_modules is also refused by the native mechanism. Test the actual imports and dependency distribution before replacing a runner which previously handled them.
For a small script with erasable types and ordinary Node imports, direct execution can make the command easier to understand. When the work needs JSX, project‑specific resolution, or broader transformation, keeping a suitable runner or compiling to JavaScript may be the simpler choice. Make that decision from the script's requirements, and check execution, types, and runtime input separately.
Postscript
December 2025: Node 24.12.0 marked type stripping stable. That changes its support status, not the distinction in my example: direct execution still does not type‑check the source or read TypeScript project settings.
May 2026: Node 26 removed --experimental-transform-types. If a script relied on that optional flag for enums or parameter properties, it needs an explicit migration: use erasable syntax, compile it, or retain a suitable external runner. Stable stripping is not a promise to transform every TypeScript feature.