Security News
ESLint is Now Language-Agnostic: Linting JSON, Markdown, and Beyond
ESLint has added JSON and Markdown linting support with new officially-supported plugins, expanding its versatility beyond JavaScript.
TypeScript Execute (tsx): Node.js enhanced with esbuild to run TypeScript & ESM files
The tsx npm package is a CLI tool for running TypeScript and TSX files directly without pre-compilation. It's essentially a TypeScript execution and REPL for node.js, similar to how `node` works for JavaScript. It allows developers to quickly run scripts and prototypes written in TypeScript, including support for TSX (TypeScript with JSX syntax), which is commonly used in React development.
Execute TypeScript files directly
Allows you to run a TypeScript file directly from the command line without needing to compile it first. This is particularly useful for quick scripts or during development.
tsx script.ts
REPL mode
Launches a REPL (Read-Eval-Print Loop) where you can type and execute TypeScript code interactively. This is useful for testing small snippets of code quickly.
tsx
Support for TSX
Enables execution of TSX files, which is TypeScript with JSX syntax. This is particularly useful for React developers who want to test components or scripts that include JSX.
tsx component.tsx
ts-node is a very popular package that offers similar functionality to tsx. It provides the ability to execute TypeScript files directly and use TypeScript in a REPL environment. ts-node is widely used in the TypeScript community for development and scripting. Compared to tsx, ts-node has been around longer and has a larger user base, but both aim to simplify the TypeScript development workflow by removing the compilation step.
esbuild-runner offers a way to run TypeScript (and JavaScript) files using the esbuild bundler/compiler. It's focused on providing extremely fast compilation and execution, leveraging esbuild's performance. While esbuild-runner and tsx share the goal of simplifying the execution of TypeScript files, esbuild-runner emphasizes speed and is part of the broader ecosystem around the esbuild project.
TypeScript Execute (tsx): The easiest way to run TypeScript in Node.js
tsconfig.json
paths
[!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!
tsx
is a CLI command you can use just like you would use node
:
Before | After |
---|---|
|
|
Use it to enhance your Node.js experience:
Just run TypeScript code without configuration
Seamless integration between CommonJS and ES Modules
You'll never get the following error again:
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.
Try it out without setup using npx! Just pass in a TypeScript file:
npx tsx ./script.ts
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 ...
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 file.ts
Now you can replace node ...
with tsx ...
in all your commands!
node
out for tsx
tsx is an enhanced version of Node.js. If you have a node ...
command, you can replace the node
with tsx
and it will just work.
Because it's a drop-in replacement for node
, it supports all Node.js command-line flags.
# Old command
node --no-warnings --env-file=.env ./file.js
# New command
tsx --no-warnings --env-file=.env ./file.js
tsconfig.json
pathBy 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
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).
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
--clear-screen=false
to disable clearing the screen on rerunStart a TypeScript REPL by running with no arguments:
tsx
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
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.
If you only need to add TypeScript support in a Module context, you can use the ESM loader:
node --import tsx/esm ./file.ts
node --loader tsx/esm ./file.ts
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
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' ]
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...
*/
],
}
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/**",
],
}
In VSCode, open the file you want to run
Go to VSCode's debug panel, select "tsx" in the drop down, and hit the play button (F5).
This method works for any Node.js process and it's not specific to tsx
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/**",
],
}
Run tsx with --inspect-brk
in a terminal window:
tsx --inspect-brk ./your-file.ts
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.
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! 🙂
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".
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.
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.
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.
TypeScript & ESM transformations are handled by esbuild, so it shares the same limitations such as:
eval()
is not preservedtsconfig.json
properties are supportedemitDecoratorMetadata
is not supportedFor details, refer to esbuild's JavaScript caveats and TypeScript caveats documentation.
FAQs
TypeScript Execute (tsx): Node.js enhanced with esbuild to run TypeScript & ESM files
The npm package tsx receives a total of 2,209,325 weekly downloads. As such, tsx popularity was classified as popular.
We found that tsx demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 1 open source maintainer collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
ESLint has added JSON and Markdown linting support with new officially-supported plugins, expanding its versatility beyond JavaScript.
Security News
Members Hub is conducting large-scale campaigns to artificially boost Discord server metrics, undermining community trust and platform integrity.
Security News
NIST has failed to meet its self-imposed deadline of clearing the NVD's backlog by the end of the fiscal year. Meanwhile, CVE's awaiting analysis have increased by 33% since June.