tsx

    3.8.0 • Public • Published

    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

    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.

    Install

    npm i tsx

    DownloadsWeekly Downloads

    33,995

    Version

    3.8.0

    License

    MIT

    Unpacked Size

    244 kB

    Total Files

    15

    Last publish

    Collaborators

    • hirokiosame