Skip to content

Latest commit

 

History

History
161 lines (110 loc) · 6.06 KB

README.md

File metadata and controls

161 lines (110 loc) · 6.06 KB
Raw

TypeScript Node

NPM version NPM downloads Build status Test coverage

TypeScript execution and REPL for node. Works with typescript@>=2.0.

Installation

npm install -g ts-node

# Install a TypeScript compiler (requires `typescript` by default).
npm install -g typescript

Features

  • Execute TypeScript files with node
  • Interactive REPL
  • Execute (and print) TypeScript through the CLI
  • Source map support
  • Loads compiler options from tsconfig.json

Important: The default mode of ts-node is transpile without type checking. This can cause problems where type information is required to generate a valid JavaScript program. Two known examples of this are const enum and import elision of type files used in valid runtime positions. If you require these features, ensure you enable type checking.

Usage

# Execute a script as you would normally with `node`.
ts-node script.ts

# Starts the 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

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 the shortcuts node -r ts-node/register or node -r ts-node/register/type-check 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 the .ts, .tsx and, with allowJs enabled, .js extensions. When node.js has a file extension registered (the require.extensions object), it will use the extension internally for module resolution. When an extension is unknown to node.js, it will handle the file as .js (JavaScript).

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.

  • --typeCheck Enable type checking for TypeScript (TS_NODE_TYPE_CHECK)
  • --cacheDirectory Configure the output file cache directory (TS_NODE_CACHE_DIRECTORY)
  • -I, --ignore [pattern] Override the path patterns to skip compilation (TS_NODE_IGNORE)
  • -P, --project [path] Path to TypeScript JSON project file (TS_NODE_PROJECT)
  • -C, --compiler [name] Specify a custom TypeScript compiler (TS_NODE_COMPILER)
  • -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)
  • --no-cache Disable the local TypeScript Node cache (TS_NODE_CACHE)
  • --skip-project Skip project config resolution and loading (TS_NODE_SKIP_PROJECT)
  • --skip-ignore Skip ignore checks (TS_NODE_SKIP_IGNORE)

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

Watching and Restarting

TypeScript Node only compiles source code on the fly, watching files and code reloads are out of scope. If you want to restart the ts-node process on file changes, standard node.js tools exist already such as nodemon, onchange and node-dev.

There is also ts-node-dev, a modified version of node-dev that uses ts-node for compilation and doesn't restart the process on every change.

License

MIT