TypeScript Support in Node.js

1. Enabling TypeScript

• Full support: Use third-party packages like tsx for complete TypeScript features.
• Type stripping: Node.js removes erasable TypeScript syntax and executes the file directly.

// Install tsx
npm install --save-dev tsx

// Run TypeScript file
npx tsx your-file.ts

2. Type Stripping

Node.js strips erasable syntax and replaces inline types with whitespace. Features requiring transformation (e.g., enums, parameter properties) need the --experimental-transform-types flag.

// Recommended tsconfig.json
{
  "compilerOptions": {
    "noEmit": true,
    "target": "esnext",
    "module": "nodenext",
    "rewriteRelativeImportExtensions": true,
    "erasableSyntaxOnly": true,
    "verbatimModuleSyntax": true
  }
}

3. Determining Module System

• .ts: Determined like .js files, based on type in package.json.
• .mts: Always ES module.
• .cts: Always CommonJS.
• .tsx: Unsupported.

File extensions are mandatory in import and require statements.

4. TypeScript Features

• Features requiring transformation: enums, namespaces with runtime code, parameter properties, import aliases.
• Supported: namespaces and modules without runtime code.
• Unsupported: decorators (parser error).

5. Importing Types

The type keyword is required for type imports:

// Correct
import type { Type1, Type2 } from './module.ts';
import { fn, type FnParams } from './fn.ts';

// Runtime error
import { Type1, Type2 } from './module.ts';
import { fn, FnParams } from './fn.ts';

6. Non-file Inputs

Type stripping works with --eval and STDIN. Module system is determined by --input-type. TypeScript syntax is unsupported in REPL, --check, and inspect.

7. Source Maps

Type stripping does not require source maps. When --experimental-transform-types is enabled, source maps are generated automatically.

8. Limitations

• Node.js does not execute TypeScript files inside node_modules.
• tsconfig.json features like paths are unsupported.
• Closest alternative: subpath imports with # prefix.

Conclusion

TypeScript in Node.js can be enabled either with full support via third-party tools or lightweight type stripping. For development and testing, type stripping is fast and simple, while full support is recommended for complex projects requiring all TypeScript features.