From b7f7f041ffef1f308f152f9c21fb00ebcf40f73e Mon Sep 17 00:00:00 2001 From: Andrew Bradley Date: Mon, 7 Feb 2022 01:01:40 -0500 Subject: [PATCH] rebuild readme for 10.5.0 --- README.md | 120 +++++++++++++++++++++++++++++++++++++----------------- 1 file changed, 83 insertions(+), 37 deletions(-) diff --git a/README.md b/README.md index d55198566..e1e4e0188 100644 --- a/README.md +++ b/README.md @@ -10,7 +10,7 @@ You can build the readme with this command: cd website && yarn build-readme --> -# ![TypeScript Node](logo.svg?sanitize=true) +# [![TypeScript Node](logo.svg?sanitize=true)](https://typestrong.org/ts-node) [![NPM version](https://img.shields.io/npm/v/ts-node.svg?style=flat)](https://npmjs.org/package/ts-node) [![NPM downloads](https://img.shields.io/npm/dm/ts-node.svg?style=flat)](https://npmjs.org/package/ts-node) @@ -60,13 +60,15 @@ The latest documentation can also be found on our website: *Environment:* `TS_NODE_PROJECT` -* `--skip-project` Skip project config resolution and loading
*Default:* `false`
*Environment:* `TS_NODE_SKIP_PROJECT` -* `-c, --cwd-mode` Resolve config relative to the current directory instead of the directory of the entrypoint script -* `-O, --compiler-options [opts]` JSON object to merge with compiler options
*Environment:* `TS_NODE_COMPILER_OPTIONS` -* `--show-config` Print resolved `tsconfig.json`, including `ts-node` options, and exit +* `--skipProject` Skip project config resolution and loading
*Default:* `false`
*Environment:* `TS_NODE_SKIP_PROJECT` +* `-c, --cwdMode` Resolve config relative to the current directory instead of the directory of the entrypoint script +* `-O, --compilerOptions [opts]` JSON object to merge with compiler options
*Environment:* `TS_NODE_COMPILER_OPTIONS` +* `--showConfig` Print resolved `tsconfig.json`, including `ts-node` options, and exit ## Typechecking -* `-T, --transpile-only` Use TypeScript's faster `transpileModule`
*Default:* `false`
*Environment:* `TS_NODE_TRANSPILE_ONLY` -* `--type-check` Opposite of `--transpile-only`
*Default:* `true`
*Environment:* `TS_NODE_TYPE_CHECK` -* `-H, --compiler-host` Use TypeScript's compiler host API
*Default:* `false`
*Environment:* `TS_NODE_COMPILER_HOST` +* `-T, --transpileOnly` Use TypeScript's faster `transpileModule`
*Default:* `false`
*Environment:* `TS_NODE_TRANSPILE_ONLY` +* `--typeCheck` Opposite of `--transpileOnly`
*Default:* `true`
*Environment:* `TS_NODE_TYPE_CHECK` +* `-H, --compilerHost` Use TypeScript's compiler host API
*Default:* `false`
*Environment:* `TS_NODE_COMPILER_HOST` * `--files` Load `files`, `include` and `exclude` from `tsconfig.json` on startup
*Default:* `false`
*Environment:* `TS_NODE_FILES` -* `-D, --ignore-diagnostics [code]` Ignore TypeScript warnings by diagnostic code
*Environment:* `TS_NODE_IGNORE_DIAGNOSTICS` +* `-D, --ignoreDiagnostics [code]` Ignore TypeScript warnings by diagnostic code
*Environment:* `TS_NODE_IGNORE_DIAGNOSTICS` ## Transpilation * `-I, --ignore [pattern]` Override the path patterns to skip compilation
*Default:* `/node_modules/`
*Environment:* `TS_NODE_IGNORE` -* `--skip-ignore` Skip ignore checks
*Default:* `false`
*Environment:* `TS_NODE_SKIP_IGNORE` +* `--skipIgnore` Skip ignore checks
*Default:* `false`
*Environment:* `TS_NODE_SKIP_IGNORE` * `-C, --compiler [name]` Specify a custom TypeScript compiler
*Default:* `typescript`
*Environment:* `TS_NODE_COMPILER` +* `--swc` Transpile with [swc](#swc). Implies `--transpileOnly`
*Default:* `false` * `--transpiler [name]` Specify a third-party, non-typechecking transpiler -* `--prefer-ts-exts` Re-order file extensions so that TypeScript imports are preferred
*Default:* `false`
*Environment:* `TS_NODE_PREFER_TS_EXTS` +* `--preferTsExts` Re-order file extensions so that TypeScript imports are preferred
*Default:* `false`
*Environment:* `TS_NODE_PREFER_TS_EXTS` ## Diagnostics -* `--log-error` Logs TypeScript errors to stderr instead of throwing exceptions
*Default:* `false`
*Environment:* `TS_NODE_LOG_ERROR` +* `--logError` Logs TypeScript errors to stderr instead of throwing exceptions
*Default:* `false`
*Environment:* `TS_NODE_LOG_ERROR` * `--pretty` Use pretty diagnostic formatter
*Default:* `false`
*Environment:* `TS_NODE_PRETTY` * `TS_NODE_DEBUG` Enable debug logging
@@ -323,7 +343,8 @@ node --trace-deprecation --abort-on-uncaught-exception -r ts-node/register ./ind * `--scopeDir` Directory within which compiler is limited when `scope` is enabled.
*Default:* First of: `tsconfig.json` "rootDir" if specified, directory containing `tsconfig.json`, or cwd if no `tsconfig.json` is loaded.
*Environment:* `TS_NODE_SCOPE_DIR` * `moduleType` Override the module type of certain files, ignoring the `package.json` `"type"` field. See [Module type overrides](#module-type-overrides) for details.
*Default:* obeys `package.json` `"type"` and `tsconfig.json` `"module"`
*Can only be specified via `tsconfig.json` or API.* * `TS_NODE_HISTORY` Path to history file for REPL
*Default:* `~/.ts_node_repl_history`
-* `--no-experimental-repl-await` Disable top-level await in REPL. Equivalent to node's [`--no-experimental-repl-await`](https://nodejs.org/api/cli.html#cli_no_experimental_repl_await)
*Default:* Enabled if TypeScript version is 3.8 or higher and target is ES2018 or higher.
*Environment:* `TS_NODE_EXPERIMENTAL_REPL_AWAIT` set `false` to disable +* `--noExperimentalReplAwait` Disable top-level await in REPL. Equivalent to node's [`--no-experimental-repl-await`](https://nodejs.org/api/cli.html#cli_no_experimental_repl_await)
*Default:* Enabled if TypeScript version is 3.8 or higher and target is ES2018 or higher.
*Environment:* `TS_NODE_EXPERIMENTAL_REPL_AWAIT` set `false` to disable +* `experimentalResolverFeatures` Enable experimental features that re-map imports and require calls to support: `baseUrl`, `paths`, `rootDirs`, `.js` to `.ts` file extension mappings, `outDir` to `rootDir` mappings for composite projects and monorepos. For details, see [#1514](https://github.com/TypeStrong/ts-node/issues/1514)
*Default:* `false`
*Can only be specified via `tsconfig.json` or API.* ## API @@ -403,7 +424,7 @@ You must set [`"type": "module"`](https://nodejs.org/api/packages.html#packages_ ## Understanding configuration ts-node uses sensible default configurations to reduce boilerplate while still respecting `tsconfig.json` if you -have one. If you are unsure which configuration is used, you can log it with `ts-node --show-config`. This is similar to +have one. If you are unsure which configuration is used, you can log it with `ts-node --showConfig`. This is similar to `tsc --showConfig` but includes `"ts-node"` options as well. ts-node also respects your locally-installed `typescript` version, but global installations fallback to the globally-installed @@ -415,7 +436,7 @@ ts-node v10.0.0 node v16.1.0 compiler v4.2.2 -$ ts-node --show-config +$ ts-node --showConfig { "compilerOptions": { "target": "es6", @@ -490,7 +511,7 @@ These tricks will make ts-node faster. It is often better to use `tsc --noEmit` to typecheck once before your tests run or as a lint step. In these cases, ts-node can skip typechecking. * Enable [`transpileOnly`](#options) to skip typechecking -* Use our [`swc` integration](#bundled-swc-integration) +* Use our [`swc` integration](#swc) * This is by far the fastest option ## With typechecking @@ -519,12 +540,20 @@ Vanilla `node` loads `.js` by reading code from disk and executing it. Our hook ### Skipping `node_modules` -By default, **TypeScript Node** avoids compiling files in `/node_modules/` for three reasons: +By default, ts-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 +If you need to import uncompiled TypeScript in `node_modules`, use [`--skipIgnore`](#transpilation) or [`TS_NODE_SKIP_IGNORE`](#transpilation) to bypass this restriction. + +### Skipping pre-compiled TypeScript + +If a compiled JavaScript file with the same name as a TypeScript file already exists, the TypeScript file will be ignored. ts-node will import the pre-compiled JavaScript. + +To force ts-node to import the TypeScript source, not the precompiled JavaScript, use [`--preferTsExts`](#transpilation). + ## paths and baseUrl 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`. @@ -628,7 +657,7 @@ For example, to use `ttypescript` and `ts-transformer-keys`, add this to your `t } ``` -## Third-party transpilers +## Transpilers In transpile-only mode, we skip typechecking to speed up execution time. You can go a step further and use a third-party transpiler to transform TypeScript into JavaScript even faster. You will still benefit from @@ -641,12 +670,11 @@ boilerplate. > For our purposes, a compiler implements TypeScript's API and can perform typechecking. > A third-party transpiler does not. Both transform TypeScript into JavaScript. -### Bundled `swc` integration +### swc -We have bundled an experimental `swc` integration. +swc support is built-in via the `--swc` flag or `"swc": true` tsconfig option. -[`swc`](https://swc.rs) is a TypeScript-compatible transpiler implemented in Rust. This makes it an order of magnitude faster -than `transpileModule`. +[`swc`](https://swc.rs) is a TypeScript-compatible transpiler implemented in Rust. This makes it an order of magnitude faster than vanilla `transpileOnly`. To use it, first install `@swc/core` or `@swc/wasm`. If using `importHelpers`, also install `@swc/helpers`. If `target` is less than "es2015" and using either `async`/`await` or generator functions, also install `regenerator-runtime`. @@ -659,20 +687,38 @@ Then add the following to your `tsconfig.json`. ```jsonc title="tsconfig.json" { "ts-node": { - "transpileOnly": true, - "transpiler": "ts-node/transpilers/swc-experimental" + "swc": true } } ``` > `swc` uses `@swc/helpers` instead of `tslib`. If you have enabled `importHelpers`, you must also install `@swc/helpers`. +### Third-party transpilers + +The `transpiler` option allows using third-party transpiler integrations with ts-node. `transpiler` must be given the +name of a module which can be `require()`d. The built-in `swc` integration is exposed as `ts-node/transpilers/swc`. + +For example, to use a hypothetical "speedy-ts-compiler", first install it into your project: `npm install speedy-ts-compiler` + +Then add the following to your tsconfig: + +```jsonc title="tsconfig.json" +{ + "ts-node": { + "transpileOnly": true, + "transpiler": "speedy-ts-compiler" + } +} +``` + ### Writing your own integration To write your own transpiler integration, check our [API docs](https://typestrong.org/ts-node/api/interfaces/TranspilerModule.html). -Integrations are `require()`d, so they can be published to npm. The module must export a `create` function matching the -[`TranspilerModule`](https://typestrong.org/ts-node/api/interfaces/TranspilerModule.html) interface. +Integrations are `require()`d by ts-node, so they can be published to npm for convenience. The module must export a `create` function described by our +[`TranspilerModule`](https://typestrong.org/ts-node/api/interfaces/TranspilerModule.html) interface. `create` is invoked by ts-node +at startup to create the transpiler. The transpiler is used repeatedly to transform TypeScript into JavaScript. ## Module type overrides