patheticGeek / tsx

⚡️ TypeScript Execute (tsx): Node.js enhanced with esbuild to run TypeScript & ESM

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
• 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

Run TypeScript / ESM / CJS module

Pass in a file to run:

tsx ./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

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!