tsx

Node.js enhanced with esbuild to run TypeScript & ESM

Runtime
privatenumber/tsxtsx

README

tsx


_TypeScript Execute (tsx)_: Node.js enhanced to run TypeScript & ESM files


Features

- Blazing fast on-demand TypeScript & ESM compilation
- Works in both CommonJS and ESM packages
- Supports next-gen TypeScript extensions (.cts & .mts)
- Hides experimental feature warnings
- TypeScript REPL
- Resolves tsconfig.json [paths](https://www.typescriptlang.org/tsconfig#paths)

💡 Protip: Looking to bundle your TypeScript project?

>

If you're looking for a dead simple way to bundle your TypeScript projects, take a look at [pkgroll](https://github.com/privatenumber/pkgroll). It's an esbuild-enhanced Rollup that's auto configured based on your package.json!


About

tsx is a CLI command (alternative to node) for seamlessly running TypeScript & ESM, in both commonjs & module package types.

It's powered by esbuild so it's insanely fast.

Want to just run TypeScript code? Try tsx:

  1. ```sh
  2. npx tsx ./script.ts
  3. ```

How does it compare to ts-node? Checkout the comparison.

Mission

tsx strives to:
1. Enhance Node.js with TypeScript compatibility
2. Improve ESM <-> CJS interoperability
3. Support the LTS versions of Node.js

Install


Local installation

If you're using it in an npm project, install it as a development dependency:
  1. ```sh
  2. npm install --save-dev tsx
  3. ```

You can reference it directly in the package.json#scripts object:
  1. ```json5
  2. {
  3.     "scripts": {
  4.         "dev": "tsx ..."
  5.     }
  6. }
  7. ```

To use the binary, you can call it with [npx](https://docs.npmjs.com/cli/v8/commands/npx) while in the project directory:

  1. ```sh
  2. npx tsx ...
  3. ```

Global installation


If you want to use it in any arbitrary project without [npx](https://docs.npmjs.com/cli/v8/commands/npx), install it globally:

  1. ```sh
  2. npm install --global tsx
  3. ```

Then, you can call tsx directly:

  1. ```sh
  2. tsx ...
  3. ```

Usage


tsx is designed to be a drop-in replacement for node, so you can use it just the way you would use Node.js. All command-line arguments (with the exception of a few) are propagated to Node.js.


Run TypeScript / ESM / CJS module


Pass in a file to run:

  1. ```sh
  2. tsx ./file.ts
  3. ```

Custom tsconfig.json path

By default, tsconfig.json will be detected from the current working directory.

To set a custom path, use the --tsconfig flag:

  1. ```sh
  2. tsx --tsconfig ./path/to/tsconfig.custom.json ./file.ts
  3. ```

Alternatively, use the TSX_TSCONFIG_PATH environment variable:

  1. ```sh
  2. TSX_TSCONFIG_PATH=./path/to/tsconfig.custom.json tsx ./file.ts
  3. ```

Watch mode

Run file and automatically rerun on changes:

  1. ```sh
  2. tsx watch ./file.ts
  3. ```

All imported files are watched except from the following directories:
node_modules, bower_components, vendor, dist, and .* (hidden directories).

Ignore files from watch


To exclude files from being watched, pass in a path or glob to the --ignore flag:
  1. ```sh
  2. tsx watch --ignore ./ignore-me.js --ignore ./ignore-me-too.js ./file.ts
  3. ```

Tips

- Press Return to manually rerun
- Pass in --clear-screen=false to disable clearing the screen on rerun

REPL

Start a TypeScript REPL by running with no arguments:

  1. ```sh
  2. tsx
  3. ```

Cache

Modules transformations are cached in the system cache directory ([TMPDIR](https://en.wikipedia.org/wiki/TMPDIR)). Transforms are cached by content hash, so duplicate dependencies are not re-transformed.

Set the --no-cache flag to disable the cache:

  1. ```sh
  2. tsx --no-cache ./file.ts
  3. ```

Alternatively, use the TSX_DISABLE_CACHE environment variable:

  1. ```sh
  2. TSX_DISABLE_CACHE=1 tsx ./file.ts
  3. ```

Node.js Loader


tsx is a standalone binary designed to be used in place of node, but sometimes you'll want to use node directly. For example, when adding TypeScript & ESM support to npm-installed binaries.

To use tsx as a  Node.js loader, pass it in to the [--import](https://nodejs.org/api/module.html#enabling) flag. This will add TypeScript & ESM support for both Module and CommonJS contexts.

  1. ```sh
  2. node --import tsx ./file.ts
  3. ```

Or as an environment variable:
  1. ```sh
  2. NODE_OPTIONS='--import tsx' node ./file.ts
  3. ```

Note: The loader is limited to adding support for loading TypeScript/ESM files. CLI features such as _watch mode_ or suppressing "experimental feature" warnings will not be available.