How to Use Node.js Native TypeScript Support: Run TS Code Without Compilation
Jamal Washington
Infrastructure Lead
Since version 22.6, Node.js has included native TypeScript support, allowing developers to run TypeScript code directly without a compilation step. This groundbreaking feature eliminates the need for tools like ts-node or alternative runtimes like Bun or Deno when you simply want to execute TypeScript in a Node.js environment. With TypeScript 5.8's release, this integration has become even more powerful.
How Node.js Native TypeScript Support Works
Node.js uses a "strip-only" approach by default when running TypeScript code. Instead of compiling your TypeScript to JavaScript behind the scenes (which would be slower), it simply ignores the TypeScript-specific parts of your code. This makes execution faster but comes with some limitations you need to understand.
For example, when Node.js encounters type annotations on function parameters, it simply strips them away since they don't affect runtime behavior. However, features like enums that generate actual JavaScript code can't be handled through simple stripping.
Setting Up Your Project for Node.js Native TypeScript
To use Node.js native TypeScript support effectively, you'll need to make three important adjustments to your codebase:
- Add the 'type' keyword to type-only imports (interfaces, types, etc.)
- Import from .ts files directly instead of .js files
- Avoid TypeScript features that can't be stripped (like enums and namespaces)
1. Annotate Type-Only Imports
When importing TypeScript-specific constructs like interfaces or types, you need to add the 'type' keyword to your import statements. This tells Node.js that these imports don't exist at runtime and should be ignored.
// Before
import { UserInterface } from './types';
// After - with type annotation
import type { UserInterface } from './types';
2. Import from TypeScript Files
When using Node.js native TypeScript support, you should import directly from .ts files rather than .js files. This is different from the approach you'd take when compiling TypeScript to JavaScript first.
// Before (when compiling to JS first)
import { router } from './routes.js';
// After (for native TS support)
import { router } from './routes.ts';3. Configure Your tsconfig.json
You'll need to update your tsconfig.json file with several important settings to make everything work smoothly:
{
"compilerOptions": {
"allowImportingTsExtensions": true,
"noEmit": true,
"verbatimModuleSyntax": true
}
}- allowImportingTsExtensions: Enables importing .ts files directly
- noEmit: Prevents TypeScript from generating output files (since Node.js will handle the code directly)
- verbatimModuleSyntax: Forces you to use the 'type' keyword for type-only imports
TypeScript 5.8's New Feature: erasableSyntaxOnly
TypeScript 5.8 introduces a valuable new option called "erasableSyntaxOnly" that enhances the Node.js native TypeScript experience. When set to true in your tsconfig.json, this option warns you if you're using TypeScript features that can't be erased by simple stripping.
{
"compilerOptions": {
"allowImportingTsExtensions": true,
"noEmit": true,
"verbatimModuleSyntax": true,
"erasableSyntaxOnly": true
}
}With this setting enabled, your IDE will show warnings or errors when you use features like enums that won't work with Node.js's default strip-only mode. This helps you catch potential runtime issues during development.
Dealing with Non-Strippable Features
When using Node.js native TypeScript support, you'll need to replace certain TypeScript features with alternatives that can be stripped away:
- Instead of enums, use string literal union types
- Avoid namespace syntax in favor of ES modules
- Use type assertions carefully
// Instead of this enum (won't work with strip-only mode)
enum TodoStatus {
ACTIVE = 'active',
COMPLETED = 'completed'
}
// Use this string literal union type instead
type TodoStatus = 'active' | 'completed';Using Transform Mode for Full TypeScript Support
If you absolutely need to use TypeScript features that can't be stripped away, Node.js does offer a transformation mode as an alternative to the default strip-only approach. This mode fully compiles your TypeScript code to JavaScript before execution.
To use transformation mode, add the --experimental-wasm-modules flag when running your Node.js application:
node --experimental-transform-types app.tsWhile this enables all TypeScript features, it comes with a performance cost since your code must be compiled at runtime. For optimal performance, the strip-only mode is preferred when possible.
Benefits of Node.js Native TypeScript Support
- Simplified development workflow without separate compilation steps
- No need for additional tools like ts-node
- Faster execution compared to traditional TypeScript compilation
- Seamless integration with the Node.js ecosystem
- Improved developer experience with direct execution of TypeScript files
Conclusion
Node.js native TypeScript support represents a significant step forward for TypeScript developers. With TypeScript 5.8's new erasableSyntaxOnly option, it's now easier than ever to write TypeScript code that runs directly in Node.js without compilation. By understanding the limitations of the strip-only approach and making the necessary adjustments to your codebase, you can enjoy a streamlined development experience while maintaining the benefits of TypeScript's type safety.
Whether you're building a new Node.js application or maintaining an existing one, consider leveraging this native TypeScript support to simplify your workflow and improve your development experience.
Let's Watch!
Node.js 22.6+ Now Runs TypeScript Natively: No Compiler Needed
Ready to enhance your neural network?
Access our quantum knowledge cores and upgrade your programming abilities.
Initialize Training Sequence