TypeStrong/ts-node


TypeScript execution and REPL for node.js

License: MIT

Language: TypeScript

Keywords: nodejs, repl, runtime, ts, ts-node, typescript, typescript-compiler, typescript-node


TypeScript Node

NPM version NPM downloads Build status Test coverage

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

Installation

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

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

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

# 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

TypeScript REPL

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.

Developers

TS Node exports a create() function that can be used to initialize a TypeScript compiler that isn't registered to require.extensions, and it uses the same code as register.

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"
    ]
}

Note: If you are using the --project <tsconfig.json> command line argument as per the Configuration Options, and want to apply this same behavior when launching in VS Code, add an "env" key into the launch configuration: "env": { "TS_NODE_PROJECT": "<tsconfig.json>" }.

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 skip loading the 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

Note: ntypescript is an example of a TypeScript compatible compiler.

CLI Options

Supports --print, --eval, --require and --interactive similar to the node.js CLI options.

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

CLI and Programmatic Options

Environment variable denoted in parentheses.

  • -T, --transpile-only Use TypeScript's faster transpileModule (TS_NODE_TRANSPILE_ONLY, default: false)
  • -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, --ignore-diagnostics [code] Ignore TypeScript warnings by diagnostic code (TS_NODE_IGNORE_DIAGNOSTICS)
  • -O, --compiler-options [opts] JSON object to merge with compiler options (TS_NODE_COMPILER_OPTIONS)
  • --dir Specify working directory for config resolution (TS_NODE_CWD, default: process.cwd())
  • --scope Scope compiler to files within cwd (TS_NODE_SCOPE, default: false)
  • --files Load files from tsconfig.json on startup (TS_NODE_FILES, default: false)
  • --pretty Use pretty diagnostic formatter (TS_NODE_PRETTY, default: false)
  • --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)
  • --emit Emit output files into .ts-node directory (TS_NODE_EMIT, default: false)
  • --prefer-ts-exts Re-order file extensions so that TypeScript imports are preferred (TS_NODE_PREFER_TS_EXTS, default: false)
  • --log-error Logs TypeScript errors to stderr instead of throwing exceptions (TS_NODE_LOG_ERROR, default: false)

Programmatic Only Options

  • transformers _ts.CustomTransformers | ((p: _ts.Program) => _ts.CustomTransformers) An object with transformers or a function that accepts a program and returns an transformers object to pass to TypeScript. Function isn't available with transpileOnly flag
  • 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 the typeRoots compiler option. This requires that your type definitions be structured as type packages (not loose TypeScript definition files). More details on how this works can be found in the TypeScript Handbook.

Example tsconfig.json:

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

Example project structure:

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

Example module declaration file:

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

For module definitions, you can use paths:

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

An alternative approach for definitions of third-party libraries are triple-slash directives. This may be helpful if you prefer not to change your TypeScript compilerOptions or structure your custom type definitions when using typeRoots. Below is an example of the triple-slash directive as a relative path within your project:

/// <reference types="./types/untyped_js_lib" />
import UntypedJsLib from "untyped_js_lib"

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

Project Statistics

Sourcerank 23
Repository Size 919 KB
Stars 5,633
Forks 245
Watchers 67
Open issues 67
Dependencies 200
Contributors 69
Tags 110
Created
Last updated
Last pushed

Top Contributors See all

Blake Embrey Greenkeeper greenkeeper[bot] Marc Trudel Homa Wong Basarat Ali Syed Vasya Aksyonov Chris Basarat Ali Syed Sharon Rolel Jonathan Mourtada Mohamed Hegazy Jan Potoms Alex Jiri Spac Artem Mickael Burguet Anton Astashov Morlay Ross Harrison

Packages Referencing this Repo

ts-node
TypeScript execution environment and REPL for node.js, with source map support
Latest release 8.5.4 - Updated - 5.63K stars
custom-ts-node
TypeScript execution environment and REPL for node
Latest release 3.0.3 - Updated - 5.63K stars
ulong-ts-node
TypeScript execution environment and REPL for node
Latest release 2.1.0 - Published - 5.63K stars
@niik/ts-node
TypeScript execution environment and REPL for node
Latest release 1.7.0 - Published - 5.63K stars
ts-node-warnings
TypeScript execution environment and REPL for node
Latest release 1.6.0 - Published - 5.63K stars
ts-node-extendable
TypeScript execution environment and REPL for node
Latest release 0.8.0 - Published - 5.63K stars
typescript-node
TypeScript execution environment for node
Latest release 0.1.3 - Updated - 5.63K stars

Recent Tags See all

v8.5.4 November 28, 2019
v8.5.3 November 28, 2019
v8.5.2 November 15, 2019
v8.5.0 November 11, 2019
v8.4.1 September 16, 2019
v8.4.0 September 15, 2019
v8.3.0 June 15, 2019
v8.2.0 May 26, 2019
v8.1.1 May 25, 2019
v8.1.0 April 15, 2019
v8.0.3 March 07, 2019
v8.0.2 January 26, 2019
v8.0.1 January 22, 2019
v8.0.0 January 22, 2019
v7.0.1 August 11, 2018

Something wrong with this page? Make a suggestion

Last synced: 2019-11-28 17:02:47 UTC

Login to resync this repository