{"_id":"@matthd/tsx","name":"@matthd/tsx","dist-tags":{"latest":"1.0.0"},"versions":{"1.0.0":{"name":"@matthd/tsx","version":"1.0.0","description":"TypeScript Execute (tsx): Node.js enhanced with esbuild to run TypeScript & ESM files matthd v16 node","keywords":["esbuild","runtime","node","cjs","commonjs","esm","typescript"],"license":"MIT","repository":{"type":"git","url":"git+https://github.com/Matthd/tsx.git"},"author":{"name":"Hiroki Osame","email":"hiroki.osame@gmail.com"},"type":"module","bin":{"tsx":"dist/cli.mjs"},"exports":{"./package.json":"./package.json",".":"./dist/loader.mjs","./cjs":"./dist/cjs/index.cjs","./esm":"./dist/esm/index.mjs","./cli":"./dist/cli.mjs","./source-map":"./dist/source-map.cjs","./suppress-warnings":"./dist/suppress-warnings.cjs","./preflight":"./dist/preflight.cjs","./repl":"./dist/repl.mjs"},"engines":{"node":">=16.0.0"},"dependencies":{"esbuild":"~0.19.10","get-tsconfig":"^4.7.2","fsevents":"~2.3.3"},"optionalDependencies":{"fsevents":"~2.3.3"},"gitHead":"a5daa7cb4a1eb526b78d3873575319fe3c39ce0b","bugs":{"url":"https://github.com/Matthd/tsx/issues"},"homepage":"https://github.com/Matthd/tsx#readme","_id":"@matthd/tsx@1.0.0","_nodeVersion":"16.20.2","_npmVersion":"8.19.4","dist":{"integrity":"sha512-2MSP6BiuTvVxM4xSwDzTzxykeabHUKudA32GHkfnmjDMfjDxOJMV8y6epUlMx8Ns90asEMLoAz8JfstxFEH8mw==","shasum":"9226c1700b7f11bb0919f6a673252c39f506f13a","tarball":"https://registry.npmjs.org/@matthd/tsx/-/tsx-1.0.0.tgz","fileCount":37,"unpackedSize":391515,"signatures":[{"keyid":"SHA256:jl3bwswu80PjjokCgh0o2w5c2U4LhQAE57gj9cz1kzA","sig":"MEYCIQCsHjNv4DcEgUhl8nO+pS8ffH+CBrrIvH83BbPjcn2jnQIhAJfQDcmT/dHjXAx9rMTxbwc84lMReddTSmdRDtvKxgjM"}]},"_npmUser":{"name":"matthd","email":"matthias.dieudonne@gmail.com"},"directories":{},"maintainers":[{"name":"matthd","email":"matthias.dieudonne@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages","tmp":"tmp/tsx_1.0.0_1712061978770_0.4762207170333195"},"_hasShrinkwrap":false}},"time":{"created":"2024-04-02T12:46:18.635Z","1.0.0":"2024-04-02T12:46:18.977Z","modified":"2024-04-02T12:46:19.295Z"},"maintainers":[{"name":"matthd","email":"matthias.dieudonne@gmail.com"}],"description":"TypeScript Execute (tsx): Node.js enhanced with esbuild to run TypeScript & ESM files matthd v16 node","homepage":"https://github.com/Matthd/tsx#readme","keywords":["esbuild","runtime","node","cjs","commonjs","esm","typescript"],"repository":{"type":"git","url":"git+https://github.com/Matthd/tsx.git"},"author":{"name":"Hiroki Osame","email":"hiroki.osame@gmail.com"},"bugs":{"url":"https://github.com/Matthd/tsx/issues"},"license":"MIT","readme":"# tsx \n\n_TypeScript Execute (tsx)_: The easiest way to run TypeScript in Node.js\n\n### Features\n- Super fast!\n- TypeScript REPL\n- Supports `tsconfig.json` [`paths`](https://www.typescriptlang.org/tsconfig#paths)\n- Works in both [CommonJS and ESM packages](https://nodejs.org/api/packages.html#type)\n\n> [!TIP]\n> **Build your TypeScript projects?**\n>\n> Try [ pkgroll](https://github.com/privatenumber/pkgroll)—the zero-config package bundler used by _tsx_!\n>\n> _pkgroll_ is a thin Rollup wrapper that makes it so simple for your package to support CommonJS, ESM, & TypeScript.\n>\n> If you love tsx, you'll love pkgroll too!\n\n
\n\n

\n\t\n\t\t\n\t\t\t\n\t\t\t\n\t\t\t\"Premium\n\t\t\n\t\n

\n\n## About\n`tsx` is a CLI command (alternative to `node`) for running TypeScript & ESM in both `commonjs` & `module` package types.\n\ntsx is for you if you want:\n- A command to _just run_ TypeScript code without configuration\n- Something so fast it's unnoticeable\n- Seamless integration across ESM and CJS dependencies\n\n\tIf you're getting the following error, give tsx a try!\n\n\t```\n\tError [ERR_REQUIRE_ESM]: require() of ES Module from ./file.js not supported.\n\tInstead change the require of in ./file.js to a dynamic import() which is available in all CommonJS modules.\n\t```\n\n### ⚡️ Quick start\nTry it out without setup! Just pass in a TypeScript file:\n\n```sh\nnpx tsx ./script.ts\n```\n\n## Installation\n\n### Local installation\n\nTo add tsx to an npm project as a development dependency:\n```sh\nnpm install --save-dev tsx\n```\n\nYou can reference it directly in the `package.json#scripts` object (you don't need `npx` here):\n```json5\n{\n \"scripts\": {\n \"dev\": \"tsx ./file.ts\"\n }\n}\n```\n\nTo use the binary, you can call it with [`npx`](https://docs.npmjs.com/cli/v8/commands/npx) while in the project directory:\n\n```sh\nnpx tsx ...\n```\n\n### Global installation\n\nIf you want to use tsx anywhere on your computer without [`npx`](https://docs.npmjs.com/cli/v8/commands/npx), install it globally:\n\n```sh\nnpm install --global tsx\n```\n\nThen, you can call `tsx` directly:\n\n```sh\ntsx ...\n```\n\n## Usage\n\n### tsx is a Node.js wrapper\n\n_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](https://nodejs.org/docs/latest-v20.x/api/cli.html).\n\n```sh\n# --no-warnings is a Node.js flag\ntsx --no-warnings ./file.ts\n```\n\n### Run TypeScript / ESM / CJS module\n\nPass in a file to run:\n\n```sh\ntsx ./file.ts\n```\n\n#### Custom `tsconfig.json` path\nBy default, `tsconfig.json` will be detected from the current working directory.\n\nTo set a custom path, use the `--tsconfig` flag:\n\n```sh\ntsx --tsconfig ./path/to/tsconfig.custom.json ./file.ts\n```\n\nAlternatively, use the `TSX_TSCONFIG_PATH` environment variable:\n\n```sh\nTSX_TSCONFIG_PATH=./path/to/tsconfig.custom.json tsx ./file.ts\n```\n\n### Watch mode\nRun file and automatically rerun on changes:\n\n```sh\ntsx watch ./file.ts\n```\n\nAll imported files are watched except from the following directories:\n`node_modules`, `bower_components`, `vendor`, `dist`, and `.*` (hidden directories).\n\n#### Ignore files from watch\n\nTo exclude files from being watched, pass in a path or glob to the `--ignore` flag:\n```sh\ntsx watch --ignore ./ignore-me.js --ignore ./ignore-me-too.js ./file.ts\n```\n\n#### Tips\n- Press Return to manually rerun\n- Pass in `--clear-screen=false` to disable clearing the screen on rerun\n\n### REPL\nStart a TypeScript REPL by running with no arguments:\n\n```sh\ntsx\n```\n\n### Cache\nModules 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.\n\nSet the `--no-cache` flag to disable the cache:\n\n```sh\ntsx --no-cache ./file.ts\n```\n\nAlternatively, use the `TSX_DISABLE_CACHE` environment variable:\n\n```sh\nTSX_DISABLE_CACHE=1 tsx ./file.ts\n```\n\n### Node.js Loader\n\n`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.\n\nTo use `tsx` as a Node.js loader, pass it in to the [`--import`](https://nodejs.org/api/module.html#enabling) flag. This will add TypeScript & ESM support for both Module and CommonJS contexts.\n\n```sh\nnode --import tsx ./file.ts\n```\n\nOr as an environment variable:\n```sh\nNODE_OPTIONS='--import tsx' node ./file.ts\n```\n\n> **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.\n\n#### ESM only loader\n\nIf you only need to add TypeScript support in a Module context, you can use the ESM loader:\n\n##### Node.js v20.6.0 and above\n```sh\nnode --import tsx/esm ./file.ts\n```\n\n##### Node.js v20.5.1 and below\n\n```sh\nnode --loader tsx/esm ./file.ts\n```\n\n#### CommonJS only loader\nIf you only need to add TypeScript & ESM support in a CommonJS context, you can use the CJS loader:\n\n```sh\nnode --require tsx/cjs ./file.ts\n```\n\n### Hashbang\n\nIf you prefer to write scripts that doesn't need to be passed into tsx, you can declare it in the [hashbang](https://bash.cyberciti.biz/guide/Shebang).\n\nSimply add `#!/usr/bin/env tsx` at the top of your file:\n\n_file.ts_\n```ts\n#!/usr/bin/env tsx\n\nconsole.log('argv:', process.argv.slice(2))\n```\n\nAnd make the file executable:\n```sh\nchmod +x ./file.ts\n```\n\nNow, you can run the file without passing it into tsx:\n```sh\n$ ./file.ts hello\nargv: [ 'hello' ]\n```\n\n### VS Code debugging\n\n#### Setup\n\nCreate the following configuration file in your project to setup debugging in VS Code:\n\n`.vscode/launch.json`\n```json5\n{\n \"version\": \"0.2.0\",\n\n \"configurations\": [\n /*\n Each config in this array is an option in the debug drop-down\n See below for configurations to add...\n */\n ],\n}\n```\n\n#### Debugging method 1: Run tsx directly from VSCode\n\n1. Add the following configuration to the `configurations` array in `.vscode/launch.json`:\n\t```json5\n\t{\n\t \"name\": \"tsx\",\n\t \"type\": \"node\",\n\t \"request\": \"launch\",\n\n\t // Debug current file in VSCode\n\t \"program\": \"${file}\",\n\n\t /*\n\t Path to tsx binary\n\t Assuming locally installed\n\t */\n\t \"runtimeExecutable\": \"${workspaceFolder}/node_modules/.bin/tsx\",\n\n\t /*\n\t Open terminal when debugging starts (Optional)\n\t Useful to see console.logs\n\t */\n\t \"console\": \"integratedTerminal\",\n\t \"internalConsoleOptions\": \"neverOpen\",\n\n\t // Files to exclude from debugger (e.g. call stack)\n\t \"skipFiles\": [\n\t // Node.js internal core modules\n\t \"/**\",\n\n\t // Ignore all dependencies (optional)\n\t \"${workspaceFolder}/node_modules/**\",\n\t ],\n\t}\n\t```\n\n2. In VSCode, open the file you want to run\n\n3. Go to VSCode's debug panel, select \"tsx\" in the drop down, and hit the play button (F5).\n\n#### Debugging method 2: Attach to a running Node.js process\n\n> This method works for any Node.js process and it's not specific to tsx\n\n1. Add the following configuration to the `configurations` array in `.vscode/launch.json`:\n\t```json\n\t{\n\t \"name\": \"Attach to process\",\n\t \"type\": \"node\",\n\t \"request\": \"attach\",\n\t \"port\": 9229,\n\t \"skipFiles\": [\n\t // Node.js internal core modules\n\t \"/**\",\n\n\t // Ignore all dependencies (optional)\n\t \"${workspaceFolder}/node_modules/**\",\n\t ],\n\t}\n\t```\n2. Run tsx with `--inspect-brk` in a terminal window:\n\n\t```sh\n\ttsx --inspect-brk ./your-file.ts \n\t```\n\n3. Go to VSCode's debug panel, select \"Attach to process\" in the drop down, and hit the play button (F5).\n\nSee the [VSCode documentation on _Launch Configuration_](https://code.visualstudio.com/docs/nodejs/nodejs-debugging#_launch-configuration) for more information.\n\n## Contributing & Support\n\nIf you're interested in contributing, please check out the [Contribution Guide](/CONTRIBUTING.md). Your collaboration will be greatly appreciated!\n\nIf you're encountering a problem, take advantage of my [_Priority Support_ service](https://github.com/sponsors/privatenumber) for as little as $25. I'd be happy to help you out! 🙂\n\n## FAQ\n\n### Why is it named _tsx_?\n\n`tsx` stands for \"TypeScript execute\". Mirroring [`npx`](https://docs.npmjs.com/cli/v8/commands/npx), which stands for \"Node.js package execute\".\n\nThe 3-character package name offers an elegant developer experience, allowing usage like: `npx tsx ...`.\n\nUnfortunately, it overlaps with React's [TSX/JSX](https://www.typescriptlang.org/docs/handbook/jsx.html), which stands for \"TypeScript XML\".\n\n### Does it type check the code it runs?\n\nNo. tsx is designed to be a simple TypeScript runner.\n\nIf you need type-checking, you can use an IDE like [VS Code](https://code.visualstudio.com) and it will type-check as you code via [IntelliSense](https://code.visualstudio.com/docs/languages/typescript). Alternatively, you can run the TypeScript Compiler only for type-checking (e.g. `tsc --noEmit`) as a linting step.\n\n### How is `tsx` different from [`ts-node`](https://github.com/TypeStrong/ts-node)?\n\n`tsx` and `ts-node` are both designed for executing TypeScript files in Node.js, but offer different approaches to suit user preferences.\n\n- **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.\n\n- **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.\n\n- **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](https://www.typescriptlang.org/tsconfig#target)), which may be outdated.\n\n- **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.\n\n- **Enhancements** tsx gracefully handles [new JS & TS syntax](https://esbuild.github.io/content-types/) and features based on the Node.js version. It also supports [`tsconfig.json` paths](https://www.typescriptlang.org/tsconfig#paths) out of the box.\n\n- **Speed** tsx utilizes [esbuild](https://esbuild.github.io/faq/#:~:text=typescript%20benchmark) 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](https://github.com/TypeStrong/ts-node#swc-1)).\n\n- **Watcher** As a DX bonus, tsx also comes with watch mode to help you iterate faster!\n\nFor a detailed technical comparison, you can refer to this [exhaustive comparison](https://github.com/privatenumber/ts-runtime-comparison) between `tsx`, `ts-node`, and other runtimes.\n\n### Does it have a configuration file?\n\nNo. 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.\n\n### Does it have any limitations?\n\nTypeScript & ESM transformations are handled by [esbuild](https://esbuild.github.io/), so it shares the same limitations such as:\n\n- Compatibility with code executed via `eval()` is not preserved\n- Only [certain `tsconfig.json` properties](https://esbuild.github.io/content-types/#tsconfig-json) are supported\n- [`emitDecoratorMetadata`](https://www.typescriptlang.org/tsconfig#emitDecoratorMetadata) is not supported \n\nFor details, refer to esbuild's [JavaScript caveats](https://esbuild.github.io/content-types/#javascript-caveats) and [TypeScript caveats](https://esbuild.github.io/content-types/#typescript-caveats) documentation.\n\n## Sponsors\n\n

\n\t\n\t\t\n\t\n

\n\n","readmeFilename":"README.md"}