ts-node

What is ts-node?

The ts-node npm package is a TypeScript execution engine and REPL for Node.js. It allows developers to run TypeScript files directly without precompiling them to JavaScript. This is particularly useful for development purposes where you can execute scripts or run a REPL environment without an additional build step.

What are ts-node's main functionalities?

Execute TypeScript files

Run a TypeScript file directly from the command line without prior compilation.

ts-node script.ts

REPL

Start a TypeScript REPL (Read-Eval-Print Loop) to execute TypeScript code interactively.

ts-node

Transpile Only Mode

Run TypeScript files without type checking for faster execution, suitable for development.

ts-node --transpile-only script.ts

Type Checking

Enable type checking when running a TypeScript file, ensuring that the code adheres to the defined types.

ts-node --type-check script.ts

Integration with Testing Frameworks

Use ts-node to run TypeScript tests with Mocha or other Node.js testing frameworks.

mocha --require ts-node/register tests/**/*.spec.ts

Other packages similar to ts-node

esbuild-register

esbuild-register uses the esbuild bundler to transpile TypeScript and JavaScript files on the fly. It is known for its speed and efficiency compared to ts-node, which can be slower due to its full type checking.

babel-node

babel-node is a part of the Babel toolchain that allows running TypeScript and modern JavaScript directly. It is similar to ts-node but uses Babel for transpilation, which can be more configurable and supports a wider range of JavaScript features and experimental syntax.

sucrase-node

sucrase-node is a development tool that allows super-fast development builds. It is similar to ts-node but focuses on speed by avoiding full type checking and supporting a subset of TypeScript features.

swc-node

swc-node is a TypeScript/JavaScript compiler that uses SWC, a super-fast compiler written in Rust. It is designed to be a faster alternative to ts-node, especially for larger codebases.

README

TypeScript execution and REPL for node.js, with source map support. Works with typescript@>=2.0.

Installation

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

# Or globally (not recommended)
npm install -g ts-node
npm install -g typescript

Tip: Installing modules locally allows you to control and share the versions through package.json.

Usage

# 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 '"Hello, world!"'

# Pipe scripts to execute with TypeScript.
echo "console.log('Hello, world!')" | ts-node

Programmatic

You can require ts-node and register the loader for future requires by using require('ts-node').register({ /* options */ }). You can also use file shortcuts - node -r ts-node/register or node -r ts-node/register/transpile-only - depending on your preferences.

Note: If you need to use advanced node.js CLI arguments (e.g. --inspect), use them with node -r ts-node/register instead of the ts-node CLI.

Mocha

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

Note: --watch-extensions is only used in --watch mode.

Tape

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

Gulp

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

Visual Studio Code

Create a new node.js configuration, add -r ts-node/register to node args and move the program to the args list (so VS Code doesn't look for outFiles).

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

How It Works

TypeScript Node works by registering the TypeScript compiler for .tsx? and .jsx? (when allowJs == true) extensions. When node.js has an extension registered (via require.extensions), it will use the extension internally for module resolution. When an extension is unknown to node.js, it handles the file as .js (JavaScript). By default, TypeScript Node avoids compiling files in /node_modules/ for three reasons:

1. Modules should always be published in a format node.js can consume
2. Transpiling the entire dependency tree will make your project slower
3. Differing behaviours between TypeScript and node.js (e.g. ES2015 modules) can result in a project that works until you decide to support a feature natively from node.js

P.S. This means if you don't register an extension, it is compiled as JavaScript. When ts-node is used with allowJs, JavaScript files are transpiled using the TypeScript compiler.

Loading tsconfig.json

Typescript Node loads tsconfig.json automatically. Use --skip-project to the loading tsconfig.json.

Tip: You can use ts-node together with tsconfig-paths to load modules according to the paths section in tsconfig.json.

Configuration Options

You can set options by passing them before the script path, via programmatic usage or via environment variables.

ts-node --compiler ntypescript --project src/tsconfig.json hello-world.ts

CLI Options

Supports --print, --eval and --require from node.js CLI options.

• --help Prints help text
• --version Prints version information

CLI and Programmatic Options

Environment variable denoted in parentheses.

• -T, --transpileOnly Use TypeScript's faster transpileModule (TS_NODE_TRANSPILE_ONLY, default: false)
• --cacheDirectory Configure the output file cache directory (TS_NODE_CACHE_DIRECTORY)
• -I, --ignore [pattern] Override the path patterns to skip compilation (TS_NODE_IGNORE, default: /node_modules/)
• -P, --project [path] Path to TypeScript JSON project file (TS_NODE_PROJECT)
• -C, --compiler [name] Specify a custom TypeScript compiler (TS_NODE_COMPILER, default: typescript)
• -D, --ignoreDiagnostics [code] Ignore TypeScript warnings by diagnostic code (TS_NODE_IGNORE_DIAGNOSTICS)
• -O, --compilerOptions [opts] JSON object to merge with compiler options (TS_NODE_COMPILER_OPTIONS)
• --files Load files from tsconfig.json on startup (TS_NODE_FILES, default: false)
• --pretty Use pretty diagnostic formatter (TS_NODE_PRETTY, default: false)
• --no-cache Disable the local TypeScript Node cache (TS_NODE_CACHE, default: true)
• --skip-project Skip project config resolution and loading (TS_NODE_SKIP_PROJECT, default: false)
• --skip-ignore Skip ignore checks (TS_NODE_SKIP_IGNORE, default: false)

Programmatic Only Options

• transformers An array of transformers to pass to TypeScript
• readFile Custom TypeScript-compatible file reading function
• fileExists Custom TypeScript-compatible file existence function

Help! My Types Are Missing!

TypeScript Node does not use files, include or exclude, by default. This is because a large majority projects do not use all of the files in a project directory (e.g. Gulpfile.ts, runtime vs tests) and parsing every file for types slows startup time. Instead, ts-node starts with the script file (e.g. ts-node index.ts) and TypeScript resolves dependencies based on imports and references.

For global definitions, you can use typeRoots:

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

A types package is a folder with a file called index.d.ts or a folder with a package.json that has a types field. -- TypeScript Handbook

For module definitions, you can use paths:

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

Tip: If you must use files, enable --files flags or set TS_NODE_FILES=true.

Watching and Restarting

TypeScript Node compiles source code via require(), watching files and code reloads are out of scope for the project. If you want to restart the ts-node process on file change, existing node.js tools such as nodemon, onchange and node-dev work.

There's also ts-node-dev, a modified version of node-dev using ts-node for compilation and won't restart the process on file change.

License

MIT