Repository files navigation

TypeScript execution and REPL for node.js, with source map and native ESM support.

The latest documentation can also be found on our website:https://typestrong.org/ts-node

• Overview
  • Features
• Installation
• Usage
  • Command Line
  • Shebang
  • node flags and other tools
  • Programmatic
• Configuration
  • CLI flags
  • Via tsconfig.json (recommended)
    • @tsconfig/bases
    • Default config
  • node flags
• Options
  • CLI Options
    • help
    • version
    • eval
    • print
    • interactive
    • esm
  • TSConfig Options
    • project
    • skipProject
    • cwdMode
    • compilerOptions
    • showConfig
  • Typechecking
    • transpileOnly
    • typeCheck
    • compilerHost
    • files
    • ignoreDiagnostics
  • Transpilation Options
    • ignore
    • skipIgnore
    • compiler
    • swc
    • transpiler
    • preferTsExts
  • Diagnostic Options
    • logError
    • pretty
    • TS_NODE_DEBUG
  • Advanced Options
    • require
    • cwd
    • emit
    • scope
    • scopeDir
    • moduleTypes
    • TS_NODE_HISTORY
    • noExperimentalReplAwait
    • experimentalResolver
    • experimentalSpecifierResolution
  • API Options
• SWC
• CommonJS vs native ECMAScript modules
  • CommonJS
  • Native ECMAScript modules
• Troubleshooting
  • Configuration
  • Common errors
    • TSError
    • SyntaxError
      • Unsupported JavaScript syntax
    • ERR_REQUIRE_ESM
    • ERR_UNKNOWN_FILE_EXTENSION
  • Missing Types
  • npx, yarn dlx, and node_modules
• Performance
  • Skip typechecking
  • With typechecking
• Advanced
  • How it works
  • Ignored files
    • File extensions
    • Skippingnode_modules
    • Skipping pre-compiled TypeScript
    • Scope by directory
    • Ignore by regexp
  • paths and baseUrl
    • Why is this not built-in to ts-node?
  • Third-party compilers
  • Transpilers
    • Third-party plugins
    • Write your own plugin
  • Module type overrides
    • Caveats
  • API
• Recipes
  • Watching and restarting
  • AVA
    • CommonJS
    • Native ECMAScript modules
  • Gulp
  • IntelliJ and Webstorm
  • Mocha
    • Mocha 7 and newer
    • Mocha <=6
  • Tape
  • Visual Studio Code
  • Other
• License

ts-node is a TypeScript execution engine and REPL for Node.js.

It JIT transforms TypeScript into JavaScript, enabling you to directly execute TypeScript on Node.js without precompiling.This is accomplished by hooking node's module loading APIs, enabling it to be used seamlessly alongside other Node.jstools and libraries.

• Automatic sourcemaps in stack traces
• Automatictsconfig.json parsing
• Automatic defaults to match your node version
• Typechecking (optional)
• REPL
• Write standalone scripts
• Native ESM loader
• Use third-party transpilers
• Use custom transformers
• Integrate with test runners, debuggers, and CLI tools
• Compatible with pre-compilation for production

# Locally in your project.npm install -D typescriptnpm install -D ts-node# Or globally with TypeScript.npm install -g typescriptnpm install -g ts-node# Depending on configuration, you may also need thesenpm install -D tslib @types/node

Tip: Installing modules locally allows you to control and share the versions throughpackage.json. ts-node will always resolve the compiler fromcwd before checking relative to its own installation.

# Execute a script as `node` + `tsc`.ts-node script.ts# Starts a TypeScript REPL.ts-node# Execute code with TypeScript.ts-node -e'console.log("Hello, world!")'# Execute, and print, code with TypeScript.ts-node -p -e'"Hello, world!"'# Pipe scripts to execute with TypeScript.echo'console.log("Hello, world!")'| ts-node# Equivalent to ts-node --transpileOnlyts-node-transpile-only script.ts# Equivalent to ts-node --cwdModets-node-cwd script.ts# Equivalent to ts-node --esmts-node-esm script.ts

To write scripts with maximum portability,specify options in yourtsconfig.json and omit them from the shebang.

#!/usr/bin/env ts-node// ts-node options are read from tsconfig.jsonconsole.log("Hello, world!")

Including options within the shebang requires theenv -S flag, which is available on recent versions ofenv. (compatibility)

#!/usr/bin/env -S ts-node --files// This shebang works on Mac and Linux with newer versions of env// Technically, Mac allows omitting `-S`, but Linux requires it

To test your version ofenv for compatibility with-S:

# Note that these unusual quotes are necessary/usr/bin/env --debug'-S echo foo bar'

You can register ts-node without using our CLI:node -r ts-node/register andnode --loader ts-node/esm

In many cases, settingNODE_OPTIONS will enablets-node within other node tools, child processes, and worker threads. This can be combined with other node flags.

NODE_OPTIONS="-r ts-node/register --no-warnings" node ./index.ts

Or, if you require native ESM support:

NODE_OPTIONS="--loader ts-node/esm"

This tells any node processes which receive this environment variable to installts-node's hooks before executing other code.

If you are invoking node directly, you can avoid the environment variable and pass those flags to node.

node --loader ts-node/esm --inspect ./index.ts

You can require ts-node and register the loader for future requires by usingrequire('ts-node').register({ /* options */ }).

Check out ourAPI for more features.

ts-node supports a variety of options which can be specified viatsconfig.json, as CLI flags, as environment variables, or programmatically.

For a complete list, seeOptions.

ts-node CLI flags must comebefore the entrypoint script. For example:

$ ts-node --project tsconfig-dev.json say-hello.ts RonaldHello, Ronald!

ts-node automatically finds and loadstsconfig.json. Most ts-node options can be specified in a"ts-node" object using their programmatic, camelCase names. We recommend this because it works even when you cannot pass CLI flags, such asnode --require ts-node/register and when using shebangs.

Use--skipProject to skip loading thetsconfig.json. Use--project to explicitly specify the path to atsconfig.json.

When searching, it is resolved usingthe same search behavior astsc. By default, this search is performed relative to the entrypoint script. In--cwdMode or if no entrypoint is specified -- for example when using the REPL -- the search is performed relative to--cwd /process.cwd().

You can use this sample configuration as a starting point:

{// This is an alias to@tsconfig/node16: https://github.com/tsconfig/bases"extends":"ts-node/node16/tsconfig.json",// Most ts-node options can be specified here using their programmatic names."ts-node":{// It is faster to skip typechecking.// Remove if you want ts-node to do typechecking."transpileOnly":true,"files":true,"compilerOptions":{// compilerOptions specified here will override those declared below,// but *only* in ts-node.  Useful if you want ts-node and tsc to use// different options with a single tsconfig.json.}},"compilerOptions":{// typescript options here}}

Our bundledJSON schema lists all compatible options.

@tsconfig/bases maintains recommended configurations for several node versions.As a convenience, these are bundled with ts-node.

{"extends":"ts-node/node16/tsconfig.json",// Or install directly with `npm i -D @tsconfig/node16`"extends":"@tsconfig/node16/tsconfig.json",}

If notsconfig.json is loaded from disk, ts-node will use the newest recommended defaults from@tsconfig/bases compatible with yournode andtypescript versions.With the latestnode andtypescript, this is@tsconfig/node16.

Older versions oftypescript are incompatible with@tsconfig/node16. In those cases we will use an older default configuration.

When in doubt,ts-node --showConfig will log the configuration being used, andts-node -vv will lognode andtypescript versions.

node flags must be passed directly tonode; they cannot be passed to the ts-node binary nor can they be specified intsconfig.json

We recommend using theNODE_OPTIONS environment variable to pass options tonode.

NODE_OPTIONS='--trace-deprecation --abort-on-uncaught-exception' ts-node ./index.ts

Alternatively, you can invokenode directly and install ts-node via--require/-r

node --trace-deprecation --abort-on-uncaught-exception -r ts-node/register ./index.ts

All command-line flags support both--camelCase and--hyphen-case.

Most options can be declared in your tsconfig.json:Configuration via tsconfig.json

ts-node supports--print (-p),--eval (-e),--require (-r) and--interactive (-i) similar to thenode.js CLI.

ts-node supports--project and--showConfig similar to thetsc CLI.

Environment variables, where available, are inALL_CAPS

ts-node --help

Prints the help text

ts-node -vts-node -vvv

Prints the version.-vv includes node and typescript compiler versions.-vvv includes absolute paths to ts-node andtypescript installations.

ts-node -e<typescript code># Examplets-node -e'console.log("Hello world!")'

Evaluate code

ts-node -p -e<typescript code># Examplets-node -p -e'"Hello world!"'

Print result of--eval

ts-node -i

Opens the REPL even if stdin does not appear to be a terminal

ts-node --esmts-node-esm

Bootstrap with the ESM loader, enabling full ESM support

ts-node -P<path/to/tsconfig>ts-node --project<path/to/tsconfig>

Path to tsconfig file.

Note the uppercase-P. This is different fromtsc's-p/--project option.

Environment:TS_NODE_PROJECT

ts-node --skipProject

Skip project config resolution and loading

Default:false
Environment:TS_NODE_SKIP_PROJECT

ts-node -cts-node --cwdModets-node-cwd

Resolve config relative to the current directory instead of the directory of the entrypoint script

ts-node -O<json compilerOptions>ts-node --compilerOptions<json compilerOptions>

JSON object to merge with compiler options

Environment:TS_NODE_COMPILER_OPTIONS

ts-node --showConfig

Print resolvedtsconfig.json, includingts-node options, and exit

ts-node -Tts-node --transpileOnly

Use TypeScript's fastertranspileModule

Default:false
Environment:TS_NODE_TRANSPILE_ONLY

ts-node --typeCheck

Opposite of--transpileOnly

Default:true
Environment:TS_NODE_TYPE_CHECK

ts-node -Hts-node --compilerHost

Use TypeScript's compiler host API

Default:false
Environment:TS_NODE_COMPILER_HOST

ts-node --files

Loadfiles,include andexclude fromtsconfig.json on startup. This mayavoid certain typechecking failures. SeeMissing types for details.

Default:false
Environment:TS_NODE_FILES

ts-node -D<code,code>ts-node --ignoreDiagnostics<code,code>

Ignore TypeScript warnings by diagnostic code

Environment:TS_NODE_IGNORE_DIAGNOSTICS

ts-node -I<regexp matching ignored files>ts-node --ignore<regexp matching ignored files>

Override the path patterns to skip compilation

Default:/node_modules/
Environment:TS_NODE_IGNORE

ts-node --skipIgnore

Skip ignore checks

Default:false
Environment:TS_NODE_SKIP_IGNORE

ts-node -C<name>ts-node --compiler<name>

Specify a custom TypeScript compiler

Default:typescript
Environment:TS_NODE_COMPILER

ts-node --swc

Transpile withswc. Implies--transpileOnly

Default:false

ts-node --transpiler<name># Examplets-node --transpiler ts-node/transpilers/swc

Use a third-party, non-typechecking transpiler

ts-node --preferTsExts

Re-order file extensions so that TypeScript imports are preferred

Default:false
Environment:TS_NODE_PREFER_TS_EXTS

ts-node --logError

Logs TypeScript errors to stderr instead of throwing exceptions

Default:false
Environment:TS_NODE_LOG_ERROR

ts-node --pretty

Use pretty diagnostic formatter

Default:false
Environment:TS_NODE_PRETTY

TS_NODE_DEBUG=true ts-node

Enable debug logging

ts-node -r<module name or path>ts-node --require<module name or path>

Require a node module before execution

ts-node --cwd<path/to/directory>

Behave as if invoked in this working directory

Default:process.cwd()
Environment:TS_NODE_CWD

ts-node --emit

Emit output files into.ts-node directory. Requires--compilerHost

Default:false
Environment:TS_NODE_EMIT

ts-node --scope

Scope compiler to files withinscopeDir. Anything outside this directory is ignored.

Default:false
Environment:TS_NODE_SCOPE

ts-node --scopeDir<path/to/directory>

Directory within which compiler is limited whenscope is enabled.

Default: First of:tsconfig.json "rootDir" if specified, directory containingtsconfig.json, or cwd if notsconfig.json is loaded.
Environment:TS_NODE_SCOPE_DIR

Override the module type of certain files, ignoring thepackage.json"type" field. SeeModule type overrides for details.

Default: obeyspackage.json"type" andtsconfig.json"module"
Can only be specified viatsconfig.json or API.

TS_NODE_HISTORY=<path/to/history/file> ts-node

Path to history file for REPL

Default:~/.ts_node_repl_history

ts-node --noExperimentalReplAwait

Disable top-level await in REPL. Equivalent to node's--no-experimental-repl-await

Default: Enabled if TypeScript version is 3.8 or higher and target is ES2018 or higher.
Environment:TS_NODE_EXPERIMENTAL_REPL_AWAIT setfalse to disable

Enable experimental hooks that re-map imports and require calls to support:

• remapping extensions, e.g. so thatimport "./foo.js" will executefoo.ts. Currently the following extensions will be mapped:
  • .js to.ts,.tsx, or.jsx
  • .cjs to.cts
  • .mjs to.mts
  • .jsx to.tsx
• including file extensions in CommonJS, for consistency with ESM where this is often mandatory

In the future, this hook will also support:

• baseUrl,paths
• rootDirs
• outDir torootDir mappings for composite projects and monorepos

For details, see#1514.

Default:false, but will likely be enabled by default in a future version
Can only be specified viatsconfig.json or API.

ts-node --experimentalSpecifierResolution node

Like node's--experimental-specifier-resolution, but can also be set in yourtsconfig.json for convenience.Requiresesm to be enabled.

Default:explicit

The API includesadditional options not shown here.

SWC support is built-in via the--swc flag or"swc": true tsconfig option.

SWC is a TypeScript-compatible transpiler implemented in Rust. This makes it an order of magnitude faster than vanillatranspileOnly.

To use it, first install@swc/core or@swc/wasm. If usingimportHelpers, also install@swc/helpers. Iftarget is less than "es2015" and usingasync/await or generator functions, also installregenerator-runtime.

npm i -D @swc/core @swc/helpers regenerator-runtime

Then add the following to yourtsconfig.json.

{"ts-node":{"swc":true}}

SWC uses@swc/helpers instead oftslib. If you have enabledimportHelpers, you must also install@swc/helpers.

TypeScript is almost always written using modernimport syntax, but it is also transformed before being executed by the underlying runtime. You can choose to either transform to CommonJS or to preserve the nativeimport syntax, using node's native ESM support. Configuration is different for each.

Here is a brief comparison of the two.

Transforming to CommonJS is typically simpler and more widely supported because it is older. You must remove"type": "module" frompackage.json and set"module": "CommonJS" intsconfig.json.

{// This can be omitted; commonjs is the default"type":"commonjs"}

{"compilerOptions":{"module":"CommonJS"}}

If you must keep"module": "ESNext" fortsc, webpack, or another build tool, you can set an override for ts-node.

{"compilerOptions":{"module":"ESNext"},"ts-node":{"compilerOptions":{"module":"CommonJS"}}}

Node's ESM loader hooks areexperimental and subject to change. ts-node's ESM support is as stable as possible, but it relies on APIs which node canand will break in new versions of node. Thus it is not recommended for production.

For complete usage, limitations, and to provide feedback, see#1007.

You must set"type": "module" inpackage.json and"module": "ESNext" intsconfig.json.

{"type":"module"}

{"compilerOptions":{"module":"ESNext"// or ES2015, ES2020},"ts-node":{// Tell ts-node CLI to install the --loader automatically, explained below"esm":true}}

You must also ensure node is passed--loader. The ts-node CLI will do this automatically with ouresm option.

Note:--esm must spawn a child process to pass it--loader. This may change if node adds the ability to install loader hooksinto the current process.

# pass the flagts-node --esm# Use the convenience binaryts-node-esm# or add `"esm": true` to your tsconfig.json to make it automaticts-node

If you are not using our CLI, pass the loader flag to node.

node --loader ts-node/esm ./index.ts# Or via environment variableNODE_OPTIONS="--loader ts-node/esm" node ./index.ts

ts-node uses sensible default configurations to reduce boilerplate while still respectingtsconfig.json if youhave one. If you are unsure which configuration is used, you can log it withts-node --showConfig. This is similar totsc --showConfig but includes"ts-node" options as well.

ts-node also respects your locally-installedtypescript version, but global installations fallback to the globally-installedtypescript. If you are unsure which versions are used,ts-node -vv will log them.

$ ts-node -vvts-node v10.0.0node v16.1.0compiler v4.2.2$ ts-node --showConfig{"compilerOptions": {"target":"es6","lib": ["es6","dom"    ],"rootDir":"./src","outDir":"./.ts-node","module":"commonjs","moduleResolution":"node","strict": true,"declaration": false,"sourceMap": true,"inlineSources": true,"types": ["node"    ],"stripInternal": true,"incremental": true,"skipLibCheck": true,"importsNotUsedAsValues":"error","inlineSourceMap": false,"noEmit":false  },"ts-node": {"cwd":"/d/project","projectSearchDir":"/d/project","require": [],"project":"/d/project/tsconfig.json"  }}

It is important to differentiate between errors from ts-node, errors from the TypeScript compiler, and errors fromnode. It is also important to understand when errors are caused by a type error in your code, a bug in your code, or a flaw in your configuration.

Type errors from the compiler are thrown as aTSError. These are the same as errors you get fromtsc.

Any error that is not aTSError is from node.js (e.g.SyntaxError), and cannot be fixed by TypeScript or ts-node. These are bugs in your code or configuration.

Your version ofnode may not support all JavaScript syntax supported by TypeScript. The compiler must transform this syntax via "downleveling," which is controlled bythetsconfig"target" option. Otherwise your code will compile fine, but node will throw aSyntaxError.

For example,node 12 does not understand the?. optional chaining operator. If you use"target": "esnext", then the following TypeScript syntax:

constbar:string|undefined=foo?.bar;

will compile into this #"auto" data-snippet-clipboard-copy-content="const a = foo?.bar;">

consta=foo?.bar;

ERR_REQUIRE_ESM

ERR_UNKNOWN_FILE_EXTENSION

Missing Types

{"compilerOptions":{"typeRoots" :["./node_modules/@types","./typings"]}}

<project_root>/-- tsconfig.json-- typings/  -- <module_name>/    -- index.d.ts

declare module'<module_name>'{// module definitions go here}

{"compilerOptions":{"baseUrl":".","paths":{"custom-module-type":["types/custom-module-type"]}}}

/// <reference path="./types/lib_greeter" />import{Greeter}from"lib_greeter"constg=newGreeter();g.sayHello();

npx, yarn dlx, and node_modules

Performance

Skip typechecking

With typechecking

Advanced

How it works

Ignored files

File extensions

Skippingnode_modules

Skipping pre-compiled TypeScript

Scope by directory

Ignore by regexp

paths and baseUrl

{"ts-node":{// Do not forget to `npm i -D tsconfig-paths`"require":["tsconfig-paths/register"]}}

Why is this not built-in to ts-node?

Third-party compilers

{"ts-node":{// This can be omitted when using ts-patch"compiler":"ttypescript"},"compilerOptions":{// plugin configuration is the same for both ts-patch and ttypescript"plugins":[{"transform":"ts-transformer-keys/transformer"}]}}

Transpilers

Third-party plugins

{"ts-node":{"transpileOnly":true,"transpiler":"@cspotcode/fast-ts-compiler"}}

Write your own plugin

Module type overrides

{"ts-node":{"transpileOnly":true,"moduleTypes":{"webpack.config.ts":"cjs",// Globs are also supported with the same behavior as tsconfig "include""webpack-config-scripts/**/*":"cjs"}},"compilerOptions":{"module":"es2020","target":"es2020"}}

Caveats

API

Recipes

Watching and restarting

AVA

CommonJS

{"ava":{"extensions":["ts"],"require":["ts-node/register"]}}

Native ECMAScript modules

{"ava":{"extensions":{"ts":"module"},"nonSemVerExperiments":{"configurableModuleFormat":true},"nodeArguments":["--loader=ts-node/esm"]}}

Gulp

# Create a `gulpfile.ts` and run `gulp`.gulp

IntelliJ and Webstorm

Mocha

Mocha 7 and newer

mocha --require ts-node/register --extensions ts,tsx --watch --watch-files src'tests/**/*.{ts,tsx}' [...args]

{// Specify "require" for CommonJS"require":"ts-node/register",// Specify "loader" for native ESM"loader":"ts-node/esm","extensions":["ts","tsx"],"spec":["tests/**/*.spec.*"],"watch-files":["src"]}

Mocha <=6

mocha --require ts-node/register --watch-extensions ts,tsx"test/**/*.{ts,tsx}" [...args]

Tape

ts-node node_modules/tape/bin/tape [...args]

Visual Studio Code

{"configurations":[{"type":"node","request":"launch","name":"Launch Program","runtimeArgs":["-r","ts-node/register"],"args":["${workspaceFolder}/src/index.ts"]}],}

Other

NODE_OPTIONS="-r ts-node/register"

NODE_OPTIONS="--loader ts-node/esm"

License