-
-
Notifications
You must be signed in to change notification settings - Fork 535
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Improve the coverage of the README (#995) #1000
Changes from all commits
d0d3263
0800638
5130f9b
05388ec
984fc74
e973116
36de7d4
File filter
Filter by extension
Conversations
Jump to
Diff view
Diff view
There are no files selected for viewing
Original file line number | Diff line number | Diff line change |
---|---|---|
|
@@ -23,6 +23,8 @@ npm install -g ts-node | |
|
||
## Usage | ||
|
||
### Shell | ||
|
||
```sh | ||
# Execute a script as `node` + `tsc`. | ||
ts-node script.ts | ||
|
@@ -38,10 +40,33 @@ ts-node -p -e '"Hello, world!"' | |
|
||
# Pipe scripts to execute with TypeScript. | ||
echo 'console.log("Hello, world!")' | ts-node | ||
|
||
# Equivalent to ts-node --script-mode | ||
ts-node-script scripts.ts | ||
|
||
# Equivalent to ts-node --transpile-only | ||
ts-node-transpile-only scripts.ts | ||
``` | ||
|
||
![TypeScript REPL](https://github.com/TypeStrong/ts-node/raw/master/screenshot.png) | ||
|
||
### Shebang | ||
|
||
```typescript | ||
#!/usr/bin/env ts-node-script | ||
|
||
console.log("Hello, world!") | ||
``` | ||
|
||
`ts-node-script` is recommended because it enables `--script-mode`, discovering `tsconfig.json` relative to the script's location instead of `process.cwd()`. This makes scripts more portable. | ||
|
||
Passing CLI arguments via shebang is allowed on Mac but not Linux. For example, the following will fail on Linux: | ||
|
||
``` | ||
#!/usr/bin/env ts-node --script-mode --transpile-only --files | ||
// This shebang is not portable. It only works on Mac | ||
``` | ||
|
||
### 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. | ||
|
@@ -122,36 +147,42 @@ Create a new Node.js configuration and add `-r ts-node/register` to "Node parame | |
|
||
**Typescript Node** loads `tsconfig.json` automatically. Use `--skip-project` to skip loading the `tsconfig.json`. | ||
|
||
It is resolved relative to `--dir` using [the same search behavior as `tsc`](https://www.typescriptlang.org/docs/handbook/tsconfig-json.html). In `--script-mode`, this is the directory containing the script. Otherwise it is resolved relative to `process.cwd()`, which matches the behavior of `tsc`. | ||
|
||
Use `--project` to specify the path to your `tsconfig.json`, ignoring `--dir`. | ||
|
||
**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`. | ||
|
||
## Configuration Options | ||
|
||
You can set options by passing them before the script path, via programmatic usage or via environment variables. | ||
You can set options by passing them before the script path, via programmatic usage, via `tsconfig.json`, or via environment variables. | ||
|
||
```sh | ||
ts-node --compiler ntypescript --project src/tsconfig.json hello-world.ts | ||
``` | ||
|
||
**Note:** [`ntypescript`](https://github.com/TypeStrong/ntypescript#readme) is an example of a TypeScript compatible `compiler`. | ||
**Note:** [`ntypescript`](https://github.com/TypeStrong/ntypescript#readme) is an example of a TypeScript-compatible `compiler`. | ||
|
||
### CLI Options | ||
|
||
Supports `--print`, `--eval`, `--require` and `--interactive` similar to the [node.js CLI options](https://nodejs.org/api/cli.html). | ||
`ts-node` supports `--print` (`-p`), `--eval` (`-e`), `--require` (`-r`) and `--interactive` (`-i`) similar to the [node.js CLI options](https://nodejs.org/api/cli.html). | ||
|
||
* `--help` Prints help text | ||
* `--version` Prints version information | ||
* `-h, --help` Prints the help text | ||
* `-v, --version` Prints the version. `-vv` prints node and typescript compiler versions, too | ||
* `-s, --script-mode` Resolve config relative to the directory of the passed script instead of the current directory. Changes default of `--dir` | ||
|
||
### CLI and Programmatic Options | ||
|
||
_Environment variable denoted in parentheses._ | ||
_The name of the environment variable and the option's default value are denoted in parentheses._ | ||
|
||
* `-T, --transpile-only` Use TypeScript's faster `transpileModule` (`TS_NODE_TRANSPILE_ONLY`, default: `false`) | ||
* `-H, --compiler-host` Use TypeScript's compiler host API (`TS_NODE_COMPILER_HOST`, 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()`) | ||
* `--dir` Specify working directory for config resolution (`TS_NODE_CWD`, default: `process.cwd()`, or `dirname(scriptPath)` if `--script-mode`) | ||
* `--scope` Scope compiler to files within `cwd` (`TS_NODE_SCOPE`, default: `false`) | ||
* `--files` Load `files`, `include` and `exclude` from `tsconfig.json` on startup (`TS_NODE_FILES`, default: `false`) | ||
* `--pretty` Use pretty diagnostic formatter (`TS_NODE_PRETTY`, default: `false`) | ||
|
@@ -161,11 +192,27 @@ _Environment variable denoted in parentheses._ | |
* `--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 | ||
### 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 | ||
|
||
### Options via tsconfig.json | ||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. I intentionally had this without a title in the |
||
|
||
Most options can be specified by a `"ts-node"` object in `tsconfig.json` using their programmatic, camelCase names. For example, to enable `--transpile-only`: | ||
|
||
```json | ||
// tsconfig.json | ||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. Strictly speaking, comments are not allowed in JSON. Given the context is given in the line above, we could/should skip this here. |
||
{ | ||
"ts-node": { | ||
"transpileOnly": true | ||
}, | ||
"compilerOptions": {} | ||
} | ||
``` | ||
|
||
* `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 | ||
Our bundled [JSON schema](https://unpkg.com/browse/ts-node@8.8.2/tsconfig.schema.json) lists all compatible options. | ||
|
||
## SyntaxError | ||
|
||
|
@@ -183,7 +230,7 @@ For global definitions, you can use the `typeRoots` compiler option. This requi | |
|
||
Example `tsconfig.json`: | ||
|
||
``` | ||
```json | ||
{ | ||
"compilerOptions": { | ||
"typeRoots" : ["./node_modules/@types", "./typings"] | ||
|
@@ -193,7 +240,7 @@ Example `tsconfig.json`: | |
|
||
Example project structure: | ||
|
||
``` | ||
```text | ||
<project_root>/ | ||
-- tsconfig.json | ||
-- typings/ | ||
|
@@ -203,7 +250,7 @@ Example project structure: | |
|
||
Example module declaration file: | ||
|
||
``` | ||
```typescript | ||
declare module '<module_name>' { | ||
// module definitions go here | ||
} | ||
|
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Resolve
->Resolves
for consistency