tsx 3.4.2 → 3.5.1

package/README.md

@@ -1,6 +1,6 @@
 # tsx
 
-_TypeScript Execute (tsx)_: Node.js enhanced with [esbuild](https://esbuild.github.io/) to run TypeScript & ESM files
+> _TypeScript Execute (`tsx`)_: Node.js enhanced with [esbuild](https://esbuild.github.io/) to run TypeScript & ESM files
 
 ### Features
 - Blazing fast on-demand TypeScript & ESM compilation
@@ -11,6 +11,22 @@ _TypeScript Execute (tsx)_: Node.js enhanced with [esbuild](https://esbuild.gith
 - TypeScript REPL
 - Tested on Linux & Windows with Node.js v12~18
 
+<sub>Support this project by ⭐️ starring and sharing it. [Follow me](https://github.com/privatenumber) to see what other cool projects I'm working on! ❤️</sub>
+
+## 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](https://esbuild.github.io/) so it's insanely fast.
+
+Want to just run TypeScript code? Try tsx:
+
+```sh
+npx tsx ./script.ts
+```
+
+How does it compare to [ts-node](https://github.com/TypeStrong/ts-node)? Checkout the [comparison](https://github.com/privatenumber/ts-runtime-comparison).
+
+
 ## Install
 
 ### Local installation
@@ -36,13 +52,13 @@ npx tsx ...
 
 ### Global installation
 
-If you want to use it in any arbitrary project without [npx](https://docs.npmjs.com/cli/v8/commands/npx), install it globally:
+If you want to use it in any arbitrary project without [`npx`](https://docs.npmjs.com/cli/v8/commands/npx), install it globally:
 
 ```sh
 npm install --global tsx
 ```
 
-You can call `tsx` directly:
+Then, you can call `tsx` directly:
 
 ```sh
 tsx ...
@@ -59,26 +75,26 @@ tsx ./file.ts
 ```
 
 ### Watch mode
-Run file and automatically re-run on changes.
+Run file and automatically re-run on changes:
+
+```sh
+tsx watch ./file.ts
+```
 
 All imported files are watched except from the following directories:
 `node_modules`, `bower_components`, `vendor`, `dist`, and `.*` (hidden directories).
 
 Press <kbd>Return</kbd> to manually re-run.
 
-```sh
-tsx watch ./file.ts
-```
-
 ### REPL
-Start a TypeScript REPL by running with no arguments.
+Start a TypeScript REPL by running with no arguments:
 
 ```sh
 tsx
 ```
 
 ### Cache
-Modules transformations are cached in the system cache directory ([`TMPDIR`](https://en.wikipedia.org/wiki/TMPDIR)). Transforms are cached by content hash so duplicate dependencies are not re-transformed.
+Modules transformations are cached in the system cache directory ([`TMPDIR`](https://en.wikipedia.org/wiki/TMPDIR)). Transforms are cached by content hash, so duplicate dependencies are not re-transformed.
 
 Set the `--no-cache` flag to disable the cache:
 
@@ -88,11 +104,11 @@ 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.
+`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 into the [`--loader`](https://nodejs.org/api/esm.html#loaders) flag.
+To use `tsx` with Node.js, pass it to the [`--loader`](https://nodejs.org/api/esm.html#loaders) flag.
 
-> Note: Node.js's experimental feature warnings will not be suppressed when used as a loader
+> Note: Node.js's experimental feature warnings will not be suppressed when used as a loader.
 
 ```sh
 # As a CLI flag
@@ -102,15 +118,15 @@ node --loader tsx ./file.ts
 NODE_OPTIONS='--loader tsx' node ./file.ts
 ```
 
-> Tip: In rare circumstances, you might be limited to use the [`-r, --require`](https://nodejs.org/api/cli.html#-r---require-module) flag.
+> Tip: In rare circumstances, you might be limited to using the [`-r, --require`](https://nodejs.org/api/cli.html#-r---require-module) flag.
 >
-> You can use [`@esbuild-kit/cjs-loader`](https://github.com/esbuild-kit/cjs-loader) but transformations will only be applied to `require()`.
+> You can use [`@esbuild-kit/cjs-loader`](https://github.com/esbuild-kit/cjs-loader), but transformations will only be applied to `require()`.
 
 ## Dependencies
 
 - [@esbuild-kit/esm-loader](https://github.com/esbuild-kit/esm-loader) - Node.js Loader to transform TypeScript to ESM.
 
-- [@esbuild-kit/cjs-loader](https://github.com/esbuild-kit/cjs-loader) - Node.js `requie()` hook to transform TypeScript & ESM to CommonJS.
+- [@esbuild-kit/cjs-loader](https://github.com/esbuild-kit/cjs-loader) - Node.js `require()` hook to transform TypeScript & ESM to CommonJS.
 
 
 ## FAQ
@@ -126,8 +142,10 @@ It's recommended to run TypeScript separately as a command (`tsc --noEmit`) or v
 
 They are both tools to run TypeScript files.
 
-The main difference is that `tsx` is powered by [esbuild](https://esbuild.github.io/) for blazing fast TypeScript compilation. Whereas `ts-node` uses the TypeScript compiler, [which is not as fast](https://esbuild.github.io/faq/#:~:text=typescript%20benchmark).
+The main difference is that `tsx` is powered by [esbuild](https://esbuild.github.io/) for blazing fast TypeScript compilation, whereas `ts-node` uses the TypeScript compiler, [which is not as fast](https://esbuild.github.io/faq/#:~:text=typescript%20benchmark).
+
+Because esbuild doesn't do type checking, `tsx` is more equivalent to `ts-node --esm --transpileOnly`.
 
-Because esbuild doesn't do type checking, `tsx` is more equivalent to `ts-node --transpileOnly`.
+[Here's an exhaustive comparison](https://github.com/privatenumber/ts-runtime-comparison) between `tsx` vs `ts-node` (and other runtimes).
 
 If you migrated from `ts-node`, please share your performance gains [here](https://github.com/esbuild-kit/tsx/discussions/10)!