Determining module system#

Node.js supports bothCommonJS andES Modules syntax in TypeScriptfiles. Node.js will not convert from one module system to another; if you wantyour code to run as an ES module, you must useimport andexport syntax, andif you want your code to run as CommonJS you must userequire andmodule.exports.

• .ts files will have their module system determinedthe same way as.jsfiles. To useimport andexport syntax, add"type": "module" to thenearest parentpackage.json.
• .mts files will always be run as ES modules, similar to.mjs files.
• .cts files will always be run as CommonJS modules, similar to.cjs files.
• .tsx files are unsupported.

As in JavaScript files,file extensions are mandatory inimport statementsandimport() expressions:import './file.ts', notimport './file'. Becauseof backward compatibility, file extensions are also mandatory inrequire()calls:require('./file.ts'), notrequire('./file'), similar to how the.cjs extension is mandatory inrequire calls in CommonJS files.

Thetsconfig.json optionallowImportingTsExtensions will allow theTypeScript compilertsc to type-check files withimport specifiers thatinclude the.ts extension.

TypeScript features#

Since Node.js is only removing inline types, any TypeScript features thatinvolvereplacing TypeScript syntax with new JavaScript syntax will error,unless the flag--experimental-transform-types is passed.

The most prominent features that require transformation are:

• Enum declarations
• namespace with runtime code
• legacymodule with runtime code
• parameter properties
• import aliases

namespaces andmodule that do not contain runtime code are supported.This example will work correctly:

// This namespace is exporting a typenamespaceTypeOnly {exporttype A =string;}copy

This will result inERR_UNSUPPORTED_TYPESCRIPT_SYNTAX error:

// This namespace is exporting a valuenamespaceA {exportlet x =1}copy

Since Decorators are currently aTC39 Stage 3 proposaland will soon be supported by the JavaScript engine,they are not transformed and will result in a parser error.This is a temporary limitation and will be resolved in the future.

In addition, Node.js does not readtsconfig.json files and does not supportfeatures that depend on settings withintsconfig.json, such as paths orconverting newer JavaScript syntax into older standards.

Importing types withouttype keyword#

Due to the nature of type stripping, thetype keyword is necessary tocorrectly strip type imports. Without thetype keyword, Node.js will treat theimport as a value import, which will result in a runtime error. The tsconfigoptionverbatimModuleSyntax can be used to match this behavior.

This example will work correctly:

importtype {Type1,Type2 }from'./module.ts';import { fn,typeFnParams }from'./fn.ts';copy

This will result in a runtime error:

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

Non-file forms of input#

Type stripping can be enabled for--eval and STDIN. The module systemwill be determined by--input-type, as it is for JavaScript.

TypeScript syntax is unsupported in the REPL,--check, andinspect.

Source maps#

Since inline types are replaced by whitespace, source maps are unnecessary forcorrect line numbers in stack traces; and Node.js does not generate them.When--experimental-transform-types is enabled, source-mapsare enabled by default.

Type stripping in dependencies#

To discourage package authors from publishing packages written in TypeScript,Node.js will by default refuse to handle TypeScript files inside folders underanode_modules path.

Paths aliases#

tsconfig "paths" won't be transformed and therefore produce an error. The closestfeature available issubpath imports with the limitation that they need to startwith#.