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
Tested on Linux & Windows with Node.js v12~18

_{Support this project by ⭐️ starring and sharing it. Follow me 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:

npx tsx ./script.ts

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:

npm install --save-dev tsx

You can reference it directly in the package.json#scripts object:

{
    "scripts": {
        "dev": "tsx ..."
    }
}

To use the binary, you can call it with npx while in the project directory:

npx tsx ...

Global installation

If you want to use it in any arbitrary project without npx, install it globally:

npm install --global tsx

Then, you can call tsx directly:

tsx ...

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:

tsx ./file.ts

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:

tsx --tsconfig ./path/to/tsconfig.custom.json ./file.ts

Watch mode

Run file and automatically rerun on changes:

tsx watch ./file.ts

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

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:

tsx

Cache

Modules transformations are cached in the system cache directory (TMPDIR). Transforms are cached by content hash, so duplicate dependencies are not re-transformed.

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

tsx --no-cache ./file.ts

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 with Node.js, pass it to the --loader flag.

Note: Node.js's experimental feature warnings will not be suppressed when used as a loader.

# As a CLI flag
node --loader tsx ./file.ts

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

Tip: In rare circumstances, you might be limited to using the -r, --require flag.

You can use @esbuild-kit/cjs-loader, but transformations will only be applied to require().

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", similar to npx ("Node.js package execute").

It has an unfortunate overlap with React's TSX/JSX, which stands for "JavaScript XML". However, we believe the naming is appropriate for what it does.

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

They are both tools to run TypeScript files.

The main difference is that tsx is powered by esbuild for blazing fast TypeScript compilation, whereas ts-node uses the TypeScript compiler, which is not as fast.

Because esbuild doesn't do type checking, tsx is more equivalent to ts-node --esm --transpileOnly.

Here's an exhaustive comparison between tsx vs ts-node (and other runtimes).

If you migrated from ts-node, please share your performance gains here!

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.

AyroTI/tsx

tsx