diff --git a/.github/workflows/website.yml b/.github/workflows/website.yml index 6e907f718..940088257 100644 --- a/.github/workflows/website.yml +++ b/.github/workflows/website.yml @@ -17,8 +17,7 @@ jobs: with: node-version: 14 # Render typedoc - # Using custom branch to workaround: https://github.com/TypeStrong/typedoc/issues/1585 - - run: npm install && git clone --depth 1 https://github.com/cspotcode/typedoc --branch patch-2 && pushd typedoc && npm install && npm run build || true && popd && ./typedoc/bin/typedoc + - run: npm install && npx typedoc # Render docusaurus and deploy website - run: | set -euo pipefail diff --git a/package.json b/package.json index 277cb7b68..705f6d2c0 100644 --- a/package.json +++ b/package.json @@ -167,5 +167,9 @@ }, "prettier": { "singleQuote": true + }, + "volta": { + "node": "16.9.1", + "npm": "6.14.15" } } diff --git a/website/docs/configuration.md b/website/docs/configuration.md index ad9998328..5a1d43bea 100644 --- a/website/docs/configuration.md +++ b/website/docs/configuration.md @@ -2,13 +2,13 @@ title: Configuration --- -`ts-node` supports a variety of options which can be specified via `tsconfig.json`, as CLI flags, as environment variables, or programmatically. +ts-node supports a variety of options which can be specified via `tsconfig.json`, as CLI flags, as environment variables, or programmatically. For a complete list, see [Options](./options.md). ## CLI flags -`ts-node` CLI flags must come *before* the entrypoint script. For example: +ts-node CLI flags must come *before* the entrypoint script. For example: ```shell $ ts-node --project tsconfig-dev.json say-hello.ts Ronald @@ -17,7 +17,7 @@ Hello, Ronald! ## Via tsconfig.json (recommended) -`ts-node` automatically finds and loads `tsconfig.json`. Most `ts-node` options can be specified in a `"ts-node"` object using their programmatic, camelCase names. We recommend this because it works even when you cannot pass CLI flags, such as `node --require ts-node/register` and when using shebangs. +ts-node automatically finds and loads `tsconfig.json`. Most ts-node options can be specified in a `"ts-node"` object using their programmatic, camelCase names. We recommend this because it works even when you cannot pass CLI flags, such as `node --require ts-node/register` and when using shebangs. Use `--skip-project` to skip loading the `tsconfig.json`. Use `--project` to explicitly specify the path to a `tsconfig.json`. @@ -55,7 +55,7 @@ Our bundled [JSON schema](https://unpkg.com/browse/ts-node@latest/tsconfig.schem ### @tsconfig/bases [@tsconfig/bases](https://github.com/tsconfig/bases) maintains recommended configurations for several node versions. -As a convenience, these are bundled with `ts-node`. +As a convenience, these are bundled with ts-node. ```json title="tsconfig.json" { @@ -68,7 +68,7 @@ As a convenience, these are bundled with `ts-node`. ### Default config -If no `tsconfig.json` is loaded from disk, `ts-node` will use the newest recommended defaults from +If no `tsconfig.json` is loaded from disk, ts-node will use the newest recommended defaults from [@tsconfig/bases](https://github.com/tsconfig/bases/) compatible with your `node` and `typescript` versions. With the latest `node` and `typescript`, this is [`@tsconfig/node16`](https://github.com/tsconfig/bases/blob/master/bases/node16.json). @@ -78,7 +78,7 @@ When in doubt, `ts-node --show-config` will log the configuration being used, an ## `node` flags -[`node` flags](https://nodejs.org/api/cli.html) must be passed directly to `node`; they cannot be passed to the `ts-node` binary nor can they be specified in `tsconfig.json` +[`node` flags](https://nodejs.org/api/cli.html) must be passed directly to `node`; they cannot be passed to the ts-node binary nor can they be specified in `tsconfig.json` We recommend using the [`NODE_OPTIONS`](https://nodejs.org/api/cli.html#cli_node_options_options) environment variable to pass options to `node`. @@ -86,7 +86,7 @@ We recommend using the [`NODE_OPTIONS`](https://nodejs.org/api/cli.html#cli_node NODE_OPTIONS='--trace-deprecation --abort-on-uncaught-exception' ts-node ./index.ts ``` -Alternatively, you can invoke `node` directly and install `ts-node` via `--require`/`-r` +Alternatively, you can invoke `node` directly and install ts-node via `--require`/`-r` ```shell node --trace-deprecation --abort-on-uncaught-exception -r ts-node/register ./index.ts diff --git a/website/docs/how-it-works.md b/website/docs/how-it-works.md index 28dec08aa..923c0592c 100644 --- a/website/docs/how-it-works.md +++ b/website/docs/how-it-works.md @@ -2,7 +2,7 @@ title: How It Works --- -`ts-node` works by registering hooks for `.ts`, `.tsx`, `.js`, and/or `.jsx` extensions. +ts-node works by registering hooks for `.ts`, `.tsx`, `.js`, and/or `.jsx` extensions. Vanilla `node` loads `.js` by reading code from disk and executing it. Our hook runs in the middle, transforming code from TypeScript to JavaScript and passing the result to `node` for execution. This transformation will respect your `tsconfig.json` as if you had compiled via `tsc`. @@ -12,7 +12,7 @@ Vanilla `node` loads `.js` by reading code from disk and executing it. Our hook > **Warning:** if a file is ignored or its file extension is not registered, node will either fail to resolve the file or will attempt to execute it as JavaScript without any transformation. This may cause syntax errors or other failures, because node does not understand TypeScript type syntax nor bleeding-edge ECMAScript features. -> **Warning:** When `ts-node` is used with `allowJs`, all non-ignored JavaScript files are transformed using the TypeScript compiler. +> **Warning:** When ts-node is used with `allowJs`, all non-ignored JavaScript files are transformed using the TypeScript compiler. ## Skipping `node_modules` diff --git a/website/docs/imports.md b/website/docs/imports.md index 9f759d207..6b04f776f 100644 --- a/website/docs/imports.md +++ b/website/docs/imports.md @@ -2,7 +2,7 @@ title: "CommonJS vs native ECMAScript modules" --- -TypeScript is almost always written using modern `import` syntax, but you can choose to either transform to CommonJS or use node's native ESM support. Configuration is different for each. +TypeScript is almost always written using modern `import` syntax, but it is also transformed before being executed by the underlying runtime. You can choose to either transform to CommonJS or to preserve the native `import` syntax, using node's native ESM support. Configuration is different for each. Here is a brief comparison of the two. @@ -11,7 +11,7 @@ Here is a brief comparison of the two. | Write native `import` syntax | Write native `import` syntax | | Transforms `import` into `require()` | Does not transform `import` | | Node executes scripts using the classic [CommonJS loader](https://nodejs.org/dist/latest-v16.x/docs/api/modules.html) | Node executes scripts using the new [ESM loader](https://nodejs.org/dist/latest-v16.x/docs/api/esm.html) | -| Use any of:
`ts-node` CLI
`node -r ts-node/register`
`NODE_OPTIONS="ts-node/register" node`
`require('ts-node').register({/* options */})` | Must use the ESM loader via:
`node --loader ts-node/esm`
`NODE_OPTIONS="--loader ts-node/esm" node` | +| Use any of:
ts-node CLI
`node -r ts-node/register`
`NODE_OPTIONS="ts-node/register" node`
`require('ts-node').register({/* options */})` | Must use the ESM loader via:
`node --loader ts-node/esm`
`NODE_OPTIONS="--loader ts-node/esm" node` | ## CommonJS @@ -32,7 +32,7 @@ Transforming to CommonJS is typically simpler and more widely supported because } ``` -If you must keep `"module": "ESNext"` for `tsc`, webpack, or another build tool, you can set an override for `ts-node`. +If you must keep `"module": "ESNext"` for `tsc`, webpack, or another build tool, you can set an override for ts-node. ```json title="tsconfig.json" { @@ -49,8 +49,7 @@ If you must keep `"module": "ESNext"` for `tsc`, webpack, or another build tool, ## Native ECMAScript modules -[Node's ESM loader hooks](https://nodejs.org/api/esm.html#esm_experimental_loaders) are [**experimental**](https://nodejs.org/api/documentation.html#documentation_stability_index) and subject to change. `ts-node`'s ESM support is also experimental. They may have -breaking changes in minor and patch releases and are not recommended for production. +[Node's ESM loader hooks](https://nodejs.org/api/esm.html#esm_experimental_loaders) are [**experimental**](https://nodejs.org/api/documentation.html#documentation_stability_index) and subject to change. ts-node's ESM support is as stable as possible, but it relies on APIs which node can *and will* break in new versions of node. Thus it is not recommended for production. For complete usage, limitations, and to provide feedback, see [#1007](https://github.com/TypeStrong/ts-node/issues/1007). diff --git a/website/docs/module-type-overrides.md b/website/docs/module-type-overrides.md index 1656d9629..43ab19f55 100644 --- a/website/docs/module-type-overrides.md +++ b/website/docs/module-type-overrides.md @@ -2,7 +2,7 @@ title: Module type overrides --- -When deciding between CommonJS and native ECMAScript modules, `ts-node` defaults to matching vanilla `node` and `tsc` +When deciding between CommonJS and native ECMAScript modules, ts-node defaults to matching vanilla `node` and `tsc` behavior. This means TypeScript files are transformed according to your `tsconfig.json` `"module"` option and executed according to node's rules for the `package.json` `"type"` field. @@ -15,7 +15,7 @@ In these situations, our `moduleTypes` option lets you override certain files, f CommonJS or ESM. Node supports similar overriding via `.cjs` and `.mjs` file extensions, but `.ts` files cannot use them. `moduleTypes` achieves the same effect, and *also* overrides your `tsconfig.json` `"module"` config appropriately. -The following example tells `ts-node` to execute a webpack config as CommonJS: +The following example tells ts-node to execute a webpack config as CommonJS: ```json title=tsconfig.json { diff --git a/website/docs/overview.md b/website/docs/overview.md index 9835306f9..4afde82d2 100644 --- a/website/docs/overview.md +++ b/website/docs/overview.md @@ -3,7 +3,7 @@ title: Overview slug: / --- -`ts-node` is a TypeScript execution engine and REPL for Node.js. +ts-node is a TypeScript execution engine and REPL for Node.js. It JIT transforms TypeScript into JavaScript, enabling you to directly execute TypeScript on Node.js without precompiling. This is accomplished by hooking node's module loading APIs, enabling it to be used seamlessly alongside other Node.js diff --git a/website/docs/paths.md b/website/docs/paths.md index 6bc60fecc..f514e8043 100644 --- a/website/docs/paths.md +++ b/website/docs/paths.md @@ -3,7 +3,7 @@ title: | 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`. +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`. ```json title="tsconfig.json" { @@ -14,7 +14,7 @@ You can use `ts-node` together with [tsconfig-paths](https://www.npmjs.com/packa } ``` -## Why is this not built-in to `ts-node`? +## Why is this not built-in to ts-node? The official TypeScript Handbook explains the intended purpose for `"paths"` in ["Additional module resolution flags"](https://www.typescriptlang.org/docs/handbook/module-resolution.html#additional-module-resolution-flags). @@ -23,4 +23,4 @@ The official TypeScript Handbook explains the intended purpose for `"paths"` in > It is important to note that the compiler will not perform any of these transformations; it just uses these pieces of information to guide the process of resolving a module import to its definition file. This means `"paths"` are intended to describe mappings that the build tool or runtime *already* performs, not to tell the build tool or -runtime how to resolve modules. In other words, they intend us to write our imports in a way `node` already understands. For this reason, `ts-node` does not modify `node`'s module resolution behavior to implement `"paths"` mappings. +runtime how to resolve modules. In other words, they intend us to write our imports in a way `node` already understands. For this reason, ts-node does not modify `node`'s module resolution behavior to implement `"paths"` mappings. diff --git a/website/docs/performance.md b/website/docs/performance.md index 625e1cd96..a875bd2eb 100644 --- a/website/docs/performance.md +++ b/website/docs/performance.md @@ -2,11 +2,11 @@ title: Make it fast --- -These tricks will make `ts-node` faster. +These tricks will make ts-node faster. ## Skip typechecking -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. +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.md) to skip typechecking * Use our [`swc` integration](./transpilers.md#bundled-swc-integration) diff --git a/website/docs/recipes/visual-studio-code.md b/website/docs/recipes/visual-studio-code.md index 1d8d44b7f..e3327c03b 100644 --- a/website/docs/recipes/visual-studio-code.md +++ b/website/docs/recipes/visual-studio-code.md @@ -2,20 +2,22 @@ title: 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`). +Create a new Node.js debug 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`). -```json +```json title=".vscode/launch.json" { - "type": "node", - "request": "launch", - "name": "Launch Program", - "runtimeArgs": [ - "-r", - "ts-node/register" - ], - "args": [ - "${workspaceFolder}/index.ts" - ] + "configurations": [{ + "type": "node", + "request": "launch", + "name": "Launch Program", + "runtimeArgs": [ + "-r", + "ts-node/register" + ], + "args": [ + "${workspaceFolder}/src/index.ts" + ] + }], } ``` diff --git a/website/docs/transpilers.md b/website/docs/transpilers.md index 2df5fa2e8..6343a61ef 100644 --- a/website/docs/transpilers.md +++ b/website/docs/transpilers.md @@ -4,7 +4,7 @@ title: Third-party 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 -`ts-node`'s automatic `tsconfig.json` discovery, sourcemap support, and global `ts-node` CLI. Integrations +ts-node's automatic `tsconfig.json` discovery, sourcemap support, and global ts-node CLI. Integrations can automatically derive an appropriate configuration from your existing `tsconfig.json` which simplifies project boilerplate. diff --git a/website/docs/troubleshooting.md b/website/docs/troubleshooting.md index 4ddac6910..2ee75225d 100644 --- a/website/docs/troubleshooting.md +++ b/website/docs/troubleshooting.md @@ -4,11 +4,11 @@ title: Troubleshooting ## Understanding configuration -`ts-node` uses sensible default configurations to reduce boilerplate while still respecting `tsconfig.json` if you +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 `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 +ts-node also respects your locally-installed `typescript` version, but global installations fallback to the globally-installed `typescript`. If you are unsure which versions are used, `ts-node -vv` will log them. ```shell @@ -54,7 +54,7 @@ $ ts-node --show-config ## Understanding Errors -It is important to differentiate between errors from `ts-node`, errors from the TypeScript compiler, and errors from `node`. It is also important to understand when errors are caused by a type error in your code, a bug in your code, or a flaw in your configuration. +It is important to differentiate between errors from ts-node, errors from the TypeScript compiler, and errors from `node`. It is also important to understand when errors are caused by a type error in your code, a bug in your code, or a flaw in your configuration. ### `TSError` @@ -62,7 +62,7 @@ Type errors from the compiler are thrown as a `TSError`. These are the same as ### `SyntaxError` -Any error that is not a `TSError` is from node.js (e.g. `SyntaxError`), and cannot be fixed by TypeScript or `ts-node`. These are bugs in your code or configuration. +Any error that is not a `TSError` is from node.js (e.g. `SyntaxError`), and cannot be fixed by TypeScript or ts-node. These are bugs in your code or configuration. #### Unsupported JavaScript syntax diff --git a/website/docs/types.md b/website/docs/types.md index 168c5c6a7..eaf425a93 100644 --- a/website/docs/types.md +++ b/website/docs/types.md @@ -2,7 +2,7 @@ title: "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. +ts-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](https://www.typescriptlang.org/docs/handbook/tsconfig-json.html#types-typeroots-and-types). diff --git a/website/docs/usage.md b/website/docs/usage.md index 76048706c..ecd6721bc 100644 --- a/website/docs/usage.md +++ b/website/docs/usage.md @@ -42,14 +42,14 @@ Passing CLI arguments via shebang is allowed on Mac but not Linux. For example, // This shebang is not portable. It only works on Mac ``` -Instead, specify all `ts-node` options in your `tsconfig.json`. +Instead, specify all ts-node options in your `tsconfig.json`. ## 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. +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. +**Note:** If you need to use advanced node.js CLI arguments (e.g. `--inspect`), use them with `node -r ts-node/register` instead of ts-node's CLI. ### Developers -`ts-node` exports a `create()` function that can be used to initialize a TypeScript compiler that isn't registered to `require.extensions`, and it uses the same code as `register`. +ts-node exports a `create()` function that can be used to initialize a TypeScript compiler that isn't registered to `require.extensions`, and it uses the same code as `register`. diff --git a/website/readme-sources/prefix.md b/website/readme-sources/prefix.md index 2b5fe41ab..a24738ff9 100644 --- a/website/readme-sources/prefix.md +++ b/website/readme-sources/prefix.md @@ -21,12 +21,8 @@ You can build the readme with this command: [![Build status](https://img.shields.io/github/workflow/status/TypeStrong/ts-node/Continuous%20Integration)](https://github.com/TypeStrong/ts-node/actions?query=workflow%3A%22Continuous+Integration%22) [![Test coverage](https://codecov.io/gh/TypeStrong/ts-node/branch/main/graph/badge.svg)](https://codecov.io/gh/TypeStrong/ts-node) -> TypeScript execution and REPL for node.js, with source map support. **Works with `typescript@>=2.7`**. +> TypeScript execution and REPL for node.js, with source map and native ESM support. The latest documentation can also be found on our website: [https://typestrong.org/ts-node](https://typestrong.org/ts-node) -### *Experimental ESM support* - -Native ESM support is currently experimental. For usage, limitations, and to provide feedback, see [#1007](https://github.com/TypeStrong/ts-node/issues/1007). - # Table of Contents