1.0.0 • Published 2 years ago

@matthd/tsx v1.0.0

Weekly downloads
-
License
MIT
Repository
github
Last release
2 years ago

tsx

TypeScript Execute (tsx): The easiest way to run TypeScript in Node.js

Features

!TIP Build your TypeScript projects?

Try pkgroll—the zero-config package bundler used by tsx!

pkgroll is a thin Rollup wrapper that makes it so simple for your package to support CommonJS, ESM, & TypeScript.

If you love tsx, you'll love pkgroll too!

About

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

tsx is for you if you want:

  • A command to just run TypeScript code without configuration
  • Something so fast it's unnoticeable

  • Seamless integration across ESM and CJS dependencies

    	If you're getting the following error, give tsx a try!

	```
	Error [ERR_REQUIRE_ESM]: require() of ES Module <ESM package> from ./file.js not supported.
	Instead change the require of <ESM package> in ./file.js to a dynamic import() which is available in all CommonJS modules.
	```

⚡️ Quick start

Try it out without setup! Just pass in a TypeScript file:

npx tsx ./script.ts

Installation

Local installation

To add tsx to an npm project as a development dependency:

npm install --save-dev tsx

You can reference it directly in the package.json#scripts object (you don't need npx here):

{
    "scripts": {
        "dev": "tsx ./file.ts"
    }
}

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

npx tsx ...

Global installation

If you want to use tsx anywhere on your computer without npx, install it globally:

npm install --global tsx

Then, you can call tsx directly:

tsx ...

Usage

tsx is a Node.js wrapper

tsx wraps around Node.js to enhance it with TypeScript support. Because it's a drop-in replacement for node, it supports all Node.js command-line flags.

# --no-warnings is a Node.js flag
tsx --no-warnings ./file.ts

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

Alternatively, use the TSX_TSCONFIG_PATH environment variable:

TSX_TSCONFIG_PATH=./path/to/tsconfig.custom.json 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).

Ignore files from watch

To exclude files from being watched, pass in a path or glob to the --ignore flag:

tsx watch --ignore ./ignore-me.js --ignore ./ignore-me-too.js ./file.ts

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

Alternatively, use the TSX_DISABLE_CACHE environment variable:

TSX_DISABLE_CACHE=1 tsx ./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 as a Node.js loader, pass it in to the --import flag. This will add TypeScript & ESM support for both Module and CommonJS contexts.

node --import tsx ./file.ts

Or as an environment variable:

NODE_OPTIONS='--import tsx' node ./file.ts

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.

ESM only loader

If you only need to add TypeScript support in a Module context, you can use the ESM loader:

Node.js v20.6.0 and above
node --import tsx/esm ./file.ts
Node.js v20.5.1 and below
node --loader tsx/esm ./file.ts

CommonJS only loader

If you only need to add TypeScript & ESM support in a CommonJS context, you can use the CJS loader:

node --require tsx/cjs ./file.ts

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

#!/usr/bin/env tsx

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

And make the file executable:

chmod +x ./file.ts

Now, you can run the file without passing it into tsx:

$ ./file.ts hello
argv: [ 'hello' ]

VS Code debugging

Setup

Create the following configuration file in your project to setup debugging in VS Code:

.vscode/launch.json

{
    "version": "0.2.0",

    "configurations": [
        /*
        Each config in this array is an option in the debug drop-down
        See below for configurations to add...
        */
    ],
}

Debugging method 1: Run tsx directly from VSCode

  1. Add the following configuration to the configurations array in .vscode/launch.json:

    {
    "name": "tsx",
    "type": "node",
    "request": "launch",

    // Debug current file in VSCode
    "program": "${file}",

    /*
    Path to tsx binary
    Assuming locally installed
    */
    "runtimeExecutable": "${workspaceFolder}/node_modules/.bin/tsx",

    /*
    Open terminal when debugging starts (Optional)
    Useful to see console.logs
    */
    "console": "integratedTerminal",
    "internalConsoleOptions": "neverOpen",

    // Files to exclude from debugger (e.g. call stack)
    "skipFiles": [
        // Node.js internal core modules
        "<node_internals>/**",

        // Ignore all dependencies (optional)
        "${workspaceFolder}/node_modules/**",
    ],
}

  2. In VSCode, open the file you want to run

  3. Go to VSCode's debug panel, select "tsx" in the drop down, and hit the play button (F5).

Debugging method 2: Attach to a running Node.js process

This method works for any Node.js process and it's not specific to tsx

  1. Add the following configuration to the configurations array in .vscode/launch.json:

    {
    "name": "Attach to process",
    "type": "node",
    "request": "attach",
    "port": 9229,
    "skipFiles": [
        // Node.js internal core modules
        "<node_internals>/**",

        // Ignore all dependencies (optional)
        "${workspaceFolder}/node_modules/**",
    ],
}

  2. Run tsx with --inspect-brk in a terminal window:

    tsx --inspect-brk ./your-file.ts

  3. Go to VSCode's debug panel, select "Attach to process" in the drop down, and hit the play button (F5).

See the VSCode documentation on Launch Configuration for more information.

Contributing & Support

If you're interested in contributing, please check out the Contribution Guide. Your collaboration will be greatly appreciated!

If you're encountering a problem, take advantage of my Priority Support service for as little as $25. I'd be happy to help you out! 🙂

FAQ

Why is it named tsx?

tsx stands for "TypeScript execute". Mirroring 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 type check the code it runs?

No. tsx is designed to be a simple TypeScript runner.

If you need type-checking, you can use an IDE like VS Code and it will type-check as you code via IntelliSense. Alternatively, you can run the TypeScript Compiler only for type-checking (e.g. tsc --noEmit) as a linting step.

How is tsx different from ts-node?

tsx and ts-node are both designed for executing TypeScript files in Node.js, but offer different approaches to suit user preferences.

  • Simple installation tsx is offered as a single binary without peer dependencies, and can be used without installation: npx tsx ./script.ts. In comparison, ts-node requires installing TypeScript or SWC as peer dependencies.

  • Zero configuration tsx just works. It doesn't require initial setup or a tsconfig.json file, and doesn't get in the way of running your code.

  • Sensible defaults tsx employs sensible defaults based on file imports and Node.js version, removing the need for certain tsconfig.json settings (that are designed for compilation rather than runtime). In comparison, ts-node relies on TypeScript's defaults (e.g. ES3 target), which may be outdated.

  • Module adaptability tsx automatically adapts between CommonJS and ESM modules, even supporting require() of ESM modules, facilitating a smoother transition as the Node.js ecosystem evolves.

  • Enhancements tsx gracefully handles new JS & TS syntax and features based on the Node.js version. It also supports tsconfig.json paths out of the box.

  • Speed tsx utilizes esbuild to achieve rapid TypeScript compilation. In comparison, ts-node uses the TypeScript compiler by default. Because tsx doesn't type check, it's similar to ts-node --esm --swc (which uses the SWC compiler).

  • Watcher As a DX bonus, tsx also comes with watch mode to help you iterate faster!

For a detailed technical comparison, you can refer to this exhaustive comparison between tsx, ts-node, and other runtimes.

Does it have a configuration file?

No. tsx's integration with Node.js is designed to be simple & seamless. However, it supports a few properties from tsconfig.json to determine how to compile TypeScript files.

Does it have any limitations?

TypeScript & ESM transformations are handled by esbuild, so it shares the same limitations such as:

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

Sponsors

esbuildruntimenodecjscommonjsesmtypescript
esbuildget-tsconfigfsevents
1.0.0

2 years ago