1 | # ![TypeScript Node](logo.svg)
|
2 |
|
3 | [![NPM version][npm-image]][npm-url]
|
4 | [![NPM downloads][downloads-image]][downloads-url]
|
5 | [![Build status][travis-image]][travis-url]
|
6 | [![Test coverage][coveralls-image]][coveralls-url]
|
7 |
|
8 | > TypeScript execution and REPL for node.js, with source map support. **Works with `typescript@>=2.0`**.
|
9 |
|
10 | **Tip:** `ts-node` differs slightly from `tsc`. It will not load files from `tsconfig.json` by default. Instead, `ts-node` starts from the input file and discovers the rest of the project tree through imports and references.
|
11 |
|
12 | ## Installation
|
13 |
|
14 | ```sh
|
15 | # Locally in your project
|
16 | npm install -D ts-node
|
17 | npm install -D typescript
|
18 |
|
19 | # Or globally (not recommended)
|
20 | npm install -g ts-node
|
21 | npm install -g typescript
|
22 | ```
|
23 |
|
24 | **Tip:** Installing modules locally allows you to control and share the versions through `package.json`.
|
25 |
|
26 | ## Usage
|
27 |
|
28 | ```sh
|
29 | # Execute a script as `node` + `tsc`.
|
30 | ts-node script.ts
|
31 |
|
32 | # Starts a TypeScript REPL.
|
33 | ts-node
|
34 |
|
35 | # Execute code with TypeScript.
|
36 | ts-node -e 'console.log("Hello, world!")'
|
37 |
|
38 | # Execute, and print, code with TypeScript.
|
39 | ts-node -p '"Hello, world!"'
|
40 |
|
41 | # Pipe scripts to execute with TypeScript.
|
42 | echo "console.log('Hello, world!')" | ts-node
|
43 | ```
|
44 |
|
45 | ![TypeScript REPL](https://github.com/TypeStrong/ts-node/raw/master/screenshot.png)
|
46 |
|
47 | ### Programmatic
|
48 |
|
49 | 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.
|
50 |
|
51 | **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.
|
52 |
|
53 | ### Mocha
|
54 |
|
55 | ```sh
|
56 | mocha --require ts-node/register --watch-extensions ts,tsx "test/**/*.{ts,tsx}" [...args]
|
57 | ```
|
58 |
|
59 | **Note:** `--watch-extensions` is only used in `--watch` mode.
|
60 |
|
61 | ### Tape
|
62 |
|
63 | ```sh
|
64 | ts-node node_modules/tape/bin/tape [...args]
|
65 | ```
|
66 |
|
67 | ### Gulp
|
68 |
|
69 | ```sh
|
70 | # Create a `gulpfile.ts` and run `gulp`.
|
71 | gulp
|
72 | ```
|
73 |
|
74 | ### Visual Studio Code
|
75 |
|
76 | 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`).
|
77 |
|
78 | ```json
|
79 | {
|
80 | "type": "node",
|
81 | "request": "launch",
|
82 | "name": "Launch Program",
|
83 | "runtimeArgs": [
|
84 | "-r",
|
85 | "ts-node/register"
|
86 | ],
|
87 | "args": [
|
88 | "${workspaceFolder}/index.ts"
|
89 | ]
|
90 | }
|
91 | ```
|
92 |
|
93 | ## How It Works
|
94 |
|
95 | **TypeScript Node** works by registering the TypeScript compiler for `.tsx?` and `.jsx?` extension (when `allowJs == true`). 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).
|
96 |
|
97 | **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.
|
98 |
|
99 | ## Loading `tsconfig.json`
|
100 |
|
101 | **Typescript Node** loads `tsconfig.json` automatically. Use `--skip-project` to the loading `tsconfig.json`.
|
102 |
|
103 | **Tip**: You can use `ts-node` together with [tsconfig-paths](https://www.npmjs.com/package/tsconfig-paths) to load modules according to the `paths` section in `tsconfig.json`.
|
104 |
|
105 | ## Configuration Options
|
106 |
|
107 | You can set options by passing them before the script path, via programmatic usage or via environment variables.
|
108 |
|
109 | ```sh
|
110 | ts-node --compiler ntypescript --project src/tsconfig.json hello-world.ts
|
111 | ```
|
112 |
|
113 | ### CLI Options
|
114 |
|
115 | Supports `--print`, `--eval` and `--require` from [node.js CLI options](https://nodejs.org/api/cli.html).
|
116 |
|
117 | * `--help` Prints help text
|
118 | * `--version` Prints version information
|
119 |
|
120 | ### CLI and Programmatic Options
|
121 |
|
122 | _Environment variable denoted in parentheses._
|
123 |
|
124 | * `-T, --transpileOnly` Use TypeScript's faster `transpileModule` (`TS_NODE_TRANSPILE_ONLY`)
|
125 | * `--cacheDirectory` Configure the output file cache directory (`TS_NODE_CACHE_DIRECTORY`)
|
126 | * `-I, --ignore [pattern]` Override the path patterns to skip compilation (`TS_NODE_IGNORE`)
|
127 | * `-P, --project [path]` Path to TypeScript JSON project file (`TS_NODE_PROJECT`)
|
128 | * `-C, --compiler [name]` Specify a custom TypeScript compiler (`TS_NODE_COMPILER`)
|
129 | * `-D, --ignoreDiagnostics [code]` Ignore TypeScript warnings by diagnostic code (`TS_NODE_IGNORE_DIAGNOSTICS`)
|
130 | * `-O, --compilerOptions [opts]` JSON object to merge with compiler options (`TS_NODE_COMPILER_OPTIONS`)
|
131 | * `--files` Load files from `tsconfig.json` on startup (`TS_NODE_FILES`)
|
132 | * `--pretty` Use pretty diagnostic formatter (`TS_NODE_PRETTY`)
|
133 | * `--no-cache` Disable the local TypeScript Node cache (`TS_NODE_CACHE`)
|
134 | * `--skip-project` Skip project config resolution and loading (`TS_NODE_SKIP_PROJECT`)
|
135 | * `--skip-ignore` Skip ignore checks (`TS_NODE_SKIP_IGNORE`)
|
136 |
|
137 | ### Programmatic Only Options
|
138 |
|
139 | * `transformers` An array of transformers to pass to TypeScript
|
140 | * `readFile` Custom TypeScript-compatible file reading function
|
141 | * `fileExists` Custom TypeScript-compatible file existence function
|
142 |
|
143 | ## Watching and Restarting
|
144 |
|
145 | **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](https://github.com/remy/nodemon), [onchange](https://github.com/Qard/onchange) and [node-dev](https://github.com/fgnass/node-dev) work.
|
146 |
|
147 | There's also [`ts-node-dev`](https://github.com/whitecolor/ts-node-dev), a modified version of [`node-dev`](https://github.com/fgnass/node-dev) using `ts-node` for compilation and won't restart the process on file change.
|
148 |
|
149 | ## License
|
150 |
|
151 | MIT
|
152 |
|
153 | [npm-image]: https://img.shields.io/npm/v/ts-node.svg?style=flat
|
154 | [npm-url]: https://npmjs.org/package/ts-node
|
155 | [downloads-image]: https://img.shields.io/npm/dm/ts-node.svg?style=flat
|
156 | [downloads-url]: https://npmjs.org/package/ts-node
|
157 | [travis-image]: https://img.shields.io/travis/TypeStrong/ts-node.svg?style=flat
|
158 | [travis-url]: https://travis-ci.org/TypeStrong/ts-node
|
159 | [coveralls-image]: https://img.shields.io/coveralls/TypeStrong/ts-node.svg?style=flat
|
160 | [coveralls-url]: https://coveralls.io/r/TypeStrong/ts-node?branch=master
|