<!-- BEFORE EDITING THIS README Our README.md is auto-generated by combining pages in website/docs and website/readme-sources If you are sending a pull request to improve documentation, submit your changes in the source markdown files and we will generate the README from there. You can build the readme with this command: cd website && yarn build-readme -->

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

Table of Contents

• 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
    • Skipping node_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

Overview

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.js tools and libraries.

Features

• Automatic sourcemaps in stack traces
• Automatic tsconfig.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

Installation

# Locally in your project.
npm install -D typescript
npm install -D ts-node

# Or globally with TypeScript.
npm install -g typescript
npm install -g ts-node

# Depending on configuration, you may also need these
npm install -D tslib @types/node

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

Usage

Command Line

# 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 --transpileOnly
ts-node-transpile-only script.ts

# Equivalent to ts-node --cwdMode
ts-node-cwd script.ts

# Equivalent to ts-node --esm
ts-node-esm script.ts

Shebang

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

#!/usr/bin/env ts-node

// ts-node options are read from tsconfig.json

console.log("Hello, world!")

Including options within the shebang requires the env -S flag, which is available on recent versions of env. (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 of env for compatibility with -S:

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

node flags and other tools

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

In many cases, setting NODE_OPTIONS will enable ts-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 install ts-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

Programmatic

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

Check out our API for more features.

Configuration

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

For a complete list, see Options.

CLI flags

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

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

Via tsconfig.json (recommended)

ts-node automatically finds and loads tsconfig.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 as node --require ts-node/register and when using shebangs.

Use --skipProject to skip loading the tsconfig.json. Use --project to explicitly specify the path to a tsconfig.json.

When searching, it is resolved using the same search behavior as tsc. 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 bundled JSON schema lists all compatible options.

@tsconfig/bases

@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",
}

Default config

If no tsconfig.json is loaded from disk, ts-node will use the newest recommended defaults from @tsconfig/bases compatible with your node and typescript versions. With the latest node and typescript, this is @tsconfig/node16.

Older versions of typescript 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, and ts-node -vv will log node and typescript versions.

node flags

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

We recommend using the NODE_OPTIONS environment variable to pass options to node.

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

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

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

Options

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 the node.js CLI.

ts-node supports --project and --showConfig similar to the tsc CLI.

Environment variables, where available, are in ALL_CAPS

CLI Options

help

ts-node --help

Prints the help text

version

ts-node -v
ts-node -vvv

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

eval

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

Evaluate code

print

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

Print result of --eval

interactive

ts-node -i

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

esm

ts-node --esm
ts-node-esm

Bootstrap with the ESM loader, enabling full ESM support

TSConfig Options

project

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

Path to tsconfig file.

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

Environment: TS_NODE_PROJECT

skipProject

ts-node --skipProject

Skip project config resolution and loading

Default: false <br/> Environment: TS_NODE_SKIP_PROJECT

cwdMode

ts-node -c
ts-node --cwdMode
ts-node-cwd

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

compilerOptions

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

JSON object to merge with compiler options

Environment: TS_NODE_COMPILER_OPTIONS

showConfig

ts-node --showConfig

Print resolved tsconfig.json, including ts-node options, and exit

Typechecking