tsx

Node.js enhanced with esbuild to run TypeScript & ESM

Runtime
esbuild-kit/tsxtsx

README

tsx


_TypeScript Execute (tsx)_: Node.js enhanced with esbuild 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)
- Supports node: import prefixes
- Hides experimental feature warnings
- TypeScript REPL
- Resolves tsconfig.json [paths](https://www.typescriptlang.org/tsconfig#paths)
- Tested on Linux & Windows with Node.js v12~18

Support this project by ⭐️ starring and sharing it. [Follow me](https://github.com/privatenumber) to see what other cool projects I'm working on! ❤️

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.


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 ESBK_TSCONFIG_PATH environment variable:

  1. ```sh
  2. ESBK_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. ```

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, simply pass it in to the [--loader](https://nodejs.org/api/esm.html#loaders) flag.

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.


  1. ```sh
  2. # As a CLI flag
  3. node --loader tsx ./file.ts

  5. # As an environment variable
  6. NODE_OPTIONS='--loader tsx' node ./file.ts
  7. ```

Tip: In rare circumstances, you might be limited to using the [-r, --require](https://nodejs.org/api/cli.html#-r---require-module) flag.

>

You can use [@esbuild-kit/cjs-loader](https://github.com/esbuild-kit/cjs-loader), but transformations will only be applied to require() (not import).



Hashbang


If you prefer to write scripts that doesn't need to be passed into tsx, you can declare it in the hashbang.

Simply add #!/usr/bin/env tsx at the top of your file:

_file.ts_
  1. ```ts
  2. #!/usr/bin/env tsx

  4. console.log('argv:', process.argv.slice(2))
  5. ```

And make the file executable:
  1. ```sh
  2. chmod +x ./file.ts
  3. ```

Now, you can run the file without passing it into tsx:
  1. ```sh
  2. $ ./file.ts hello
  3. argv: [ 'hello' ]
  4. ```

Dependencies


@esbuild-kit/esm-loader

Node.js Loader to transform TypeScript to ESM.

@esbuild-kit/cjs-loader

Node.js require() hook to transform TypeScript & ESM to CommonJS.


FAQ


Why is it named tsx?


tsx stands for "TypeScript execute". Mirroring [npx](https://docs.npmjs.com/cli/v8/commands/npx), which stands for "Node.js package execute".

The 3-character package name offers an elegant developer experience, allowing usage like: npx tsx ....

Unfortunately, it overlaps with React's TSX/JSX, which stands for "TypeScript XML".

Does it do type-checking?


No, esbuild does not support type checking).

It's recommended to run TypeScript separately as a command (tsc --noEmit) or via IDE IntelliSense.


How is tsx different from [ts-node](https://github.com/TypeStrong/ts-node)?


They're both tools to run TypeScript files. But tsx does a lot more to improve the experience of using Node.js.

tsx _just works_. It's zero-config and doesn't require tsconfig.json to get started, making it easy for users that just want to run TypeScript code and not get caught up in the configuration.

It's a single binary with no peer-dependencies (e.g. TypeScript or esbuild), so there is no setup necessary, enabling usage that is elegant and frictionless for first-time users:

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

tsx is zero-config because it has smart detections built in. As a runtime, it detects what's imported to make many options in tsconfig.json redundant—which was designed for compiling matching files regardless of whether they're imported.

It seamlessly adapts between CommonJS and ESM package types by detecting how modules are loaded (require() or import) to determine how to compile them. It even adds support for require()ing ESM modules from CommonJS so you don't have to worry about your dependencies as the ecosystem migrates to ESM.

Newer and unsupported syntax & features like [importingnode: prefixes](https://2ality.com/2021/12/node-protocol-imports.html) are downgraded by detecting the Node.js version. For large TypeScript codebases, it has [tsconfig.json paths](https://www.typescriptlang.org/tsconfig#paths) aliasing support out of the box.

At the core, tsx is powered by esbuild for blazing fast TypeScript compilation, whereasts-node (by default) uses the TypeScript compiler. Because esbuild doesn't type check, tsx is similar to ts-node --esm --swc (which uses the SWC compiler).

As a bonus, tsx also comes with a watcher to speed up your development.

Here's an exhaustive technical comparison betweentsx, ts-node, and other runtimes.

Can it use esbuild plugins?


No. tsx uses esbuild's Transform API, which doesn't support plugins.

Does it have a configuration file?


No. tsx's integration with Node.js is designed to be seamless so there is no configuration.

Does it have any limitations?


Transformations are handled by esbuild, so it shares the same limitations such as:

- Compatibility with code executed via eval() is not preserved
- Only [certain tsconfig.json properties](https://esbuild.github.io/content-types/#tsconfig-json) are supported
- [emitDecoratorMetadata](https://www.typescriptlang.org/tsconfig#emitDecoratorMetadata) is not supported

For details, refer to esbuild's JavaScript caveats and TypeScript caveats documentation.