sfcode An Online Competing and Development Environment

> 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 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

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

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 <tt>tsconfig.json</tt>

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

## 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, --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`)
- `--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`)
- `--log-error` Logs errors of types instead of exit the process (`TS_NODE_LOG_ERROR`, default: `false`)
- `--prefer-ts-exts` Re-order file extensions so that TypeScript imports are preferred (`TS_NODE_PREFER_TS_EXTS`, 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 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