96 |
97 |
98 |
123 |
--------------------------------------------------------------------------------
/docs/.vitepress/theme/index.ts:
--------------------------------------------------------------------------------
1 | import { h } from 'vue';
2 | import DefaultTheme from 'vitepress/theme';
3 | import AsideSponsors from './components/AsideSponsors.vue';
4 | import './styles.css';
5 |
6 | export default {
7 | extends: DefaultTheme,
8 | Layout: () => h(
9 | DefaultTheme.Layout,
10 | null,
11 | {
12 | 'aside-ads-before': () => h(AsideSponsors),
13 | },
14 | ),
15 | };
16 |
--------------------------------------------------------------------------------
/docs/.vitepress/theme/styles.css:
--------------------------------------------------------------------------------
1 | @tailwind base;
2 | @tailwind components;
3 | @tailwind utilities;
4 |
5 | .button {
6 | @apply
7 | inline-block
8 | py-2
9 | px-6
10 | rounded-full
11 | !no-underline
12 | !transition-colors
13 | duration-200
14 | ;
15 | }
16 |
17 | .dark .dark-zebra-pattern {
18 | background-image: repeating-linear-gradient(
19 | 45deg,
20 | transparent,
21 | transparent 10px,
22 | rgb(0 0 0/ 0.05) 10px,
23 | rgb(0 0 0/ 0.05) 20px
24 | );
25 | }
26 |
--------------------------------------------------------------------------------
/docs/compilation.md:
--------------------------------------------------------------------------------
1 | # Compilation
2 |
3 | Compiling your TypeScript files to JavaScript is not handled by _tsx_, but it's a necessary step in most setups.
4 |
5 | ::: info Should I publish TypeScript files?
6 |
7 | No. While _tsx_ is capable of running TypeScript files in dependencies if need be (e.g. monorepos), it's highly discouraged to publish uncompiled TypeScript. Source files require a specific compilation configuration in `tsconfig.json` which may not be read, and [TypeScript performance will degrade](https://x.com/atcb/status/1705675335814271157).
8 | :::
9 |
10 | ## Compiling an npm package
11 |
12 | npm packages are distinguished from applications by defining package entry-points in `package.json`.
13 |
14 | [pkgroll](https://github.com/privatenumber/pkgroll) is the recommended bundler for projects using _tsx_. It's developed by the same author and used to compile _tsx_.
15 |
16 | Given your source files are in the `src` directory, it automatically infers how to build your package based on the entry points defined in `package.json` by outputting them to the `dist` directory.
17 |
18 | ### Setup
19 |
20 | ::: details Basic setup
21 |
22 | Set your entry-point in [`exports`](https://nodejs.org/api/packages.html#exports):
23 |
24 | ```json5
25 | // package.json
26 | {
27 | "exports": "./dist/index.mjs"
28 | }
29 | ```
30 | :::
31 |
32 | ::: details Dual package (CJS & ESM)
33 |
34 | Set your CommonJS & Module entry-points in [`exports`](https://nodejs.org/api/packages.html#exports):
35 |
36 | ```json5
37 | // package.json
38 | {
39 | "main": "./dist/index.cjs",
40 | "module": "./dist/index.mjs",
41 | "types": "./dist/index.d.cts",
42 |
43 | "exports": {
44 | "require": {
45 | "types": "./dist/index.d.cts",
46 | "default": "./dist/index.cjs"
47 | },
48 | "import": {
49 | "types": "./dist/index.d.mts",
50 | "default": "./dist/index.mjs"
51 | }
52 | }
53 | }
54 | ```
55 | :::
56 |
57 | ::: details Command-line package
58 |
59 | Set your CLI entry-point in [`bin`](https://docs.npmjs.com/cli/v10/configuring-npm/package-json#bin):
60 |
61 | ```json5
62 | // package.json
63 | {
64 | "bin": "./dist/cli.mjs"
65 | }
66 | ```
67 | :::
68 |
69 | ### Build
70 | In your directory, simply run `pkgroll`:
71 |
72 | ::: code-group
73 | ```sh [npm]
74 | $ npx pkgroll
75 | ```
76 |
77 | ```sh [pnpm]
78 | $ pnpm pkgroll
79 | ```
80 |
81 | ```sh [yarn]
82 | $ yarn pkgroll
83 | ```
84 | :::
85 |
86 | Optionally, add a `build` script for convenience:
87 | ```json
88 | // package.json
89 | {
90 | // Optional: build script
91 | "scripts": {// [!code ++]
92 | "build": "pkgroll"// [!code ++]
93 | }// [!code ++]
94 | }
95 | ```
96 |
97 |
98 |
--------------------------------------------------------------------------------
/docs/contact.md:
--------------------------------------------------------------------------------
1 | # Contact
2 |
3 |
6 |
7 |
8 |
--------------------------------------------------------------------------------
/docs/dev-api/entry-point.md:
--------------------------------------------------------------------------------
1 | # Entry-point
2 |
3 | Import `tsx` at the top of your entry-file:
4 | ```js
5 | import 'tsx'
6 |
7 | // Now you can load TS files
8 | await import('./file.ts')
9 | ```
10 |
11 |
12 | Note, because of the order of static import evaluatation in ESM, the enhancement only works on [dynamic imports after registeration](https://nodejs.org/docs/latest-v22.x/api/module.html#:~:text=dynamic%20import()%20must%20be%20used%20for%20any%20code%20that%20should%20be%20run%20after%20the%20hooks%20are%20registered).
13 |
14 | ::: danger
15 | Enhancing Node.js by loading _tsx_ from within your source code at run-time can be unexpected for collaborators who aren’t aware of it.
16 |
17 | When possible, it's recommended to use a more visible method, such as passing it as a [CLI flag](/dev-api/node-cli).
18 | :::
19 |
20 |
21 | ## Advanced usage
22 |
23 | ### CommonJS mode only
24 |
25 | Require `tsx/cjs` at the top of your entry-file:
26 |
27 | ```js
28 | require('tsx/cjs')
29 |
30 | // Now you can load TS files
31 | require('./file.ts')
32 | ```
33 |
34 | ### Module mode only
35 |
36 | Import `tsx/esm` at the top of your entry-file:
37 |
38 | ```js
39 | import 'tsx/esm'
40 |
41 | // Now you can load TS files
42 | await import('./file.ts')
43 | ```
44 |
--------------------------------------------------------------------------------
/docs/dev-api/index.md:
--------------------------------------------------------------------------------
1 | # Developer API
2 | The Developer API allows you to enhance Node.js with _tsx_ without needing to use the `tsx` command.
3 |
4 | Note that CLI features such as [_Watch mode_](/watch-mode.md) and the [REPL](/usage#repl) will not be available.
5 |
6 | ## Use-cases
7 |
8 | ### Directly running `node`
9 |
10 | Sometimes, you may need to run `node` directly but still want to use _tsx_. Instead of using the `tsx` command, you can pass it to Node with [`node --import tsx`](/dev-api/node-cli) or you can do [`import 'tsx'`](/dev-api/entry-point) at the top of your script. This is helpful when you need more control over the Node.js environment, are integrating with tools that specifically call `node`, or simply prefer using the `node` command.
11 |
12 | ### 3rd party packages
13 |
14 | Some third-party packages need to load TypeScript files, like configuration files, without affecting the entire runtime environment. The [`tsImport()` API](/dev-api/ts-import) allows these packages to load TypeScript files natively, without causing side effects to the environment.
15 |
16 | ## Understanding module types
17 |
18 | Understanding the Node.js module types, CommonJS (CJS) and ES Module (ESM), can be helpful when using the Developer API.
19 |
20 | ESM is the modern standard, indicated by the file extensions `.mjs` for JavaScript and `.mts` for TypeScript. CommonJS, the older format, uses the file extensions `.cjs` for JavaScript and `.cts` for TypeScript. When the file extension is ambiguous, such as `.js` or `.ts`, [`package.json#type`](https://nodejs.org/api/packages.html#type) is used to determine the module type. If `type` is set to `module`, the files are treated as ES Modules. If `type` is set to `commonjs` or not set at all, the files are treated as CommonJS modules.
21 |
22 | Although both module types can coexist in the same environment, they have distinct scopes and behaviors. _tsx_ offers APIs to enhance both CommonJS and ES modules selectively. Being aware of these distinctions and knowing which module type you are using will allow you to make informed decisions when opting into these enhancements.
23 |
--------------------------------------------------------------------------------
/docs/dev-api/node-cli.md:
--------------------------------------------------------------------------------
1 | # Node.js CLI
2 |
3 | To use the `node` command directly with _tsx_, pass it as a flag:
4 |
5 | ```sh
6 | node --import tsx ./file.ts
7 | ```
8 |
9 | ::: details (Deprecated) Node.js v20.5.1 and below
10 |
11 | Older Node.js versions use a deprecated API `--loader` instead of `--import`.
12 |
13 | ```sh
14 | node --loader tsx ./file.ts
15 | ```
16 | :::
17 |
18 | ## Custom `tsconfig.json` path
19 |
20 | To specify a custom path to `tsconfig.json`, use an environment variable:
21 |
22 | ```sh
23 | TSX_TSCONFIG_PATH=./path/to/tsconfig.custom.json node --import tsx ./file.ts
24 | ```
25 |
26 | ## Binaries
27 |
28 | If you don't have direct access to the `node` command, use the Node.js [`NODE_OPTIONS` environment variable](https://nodejs.org/api/cli.html#node_optionsoptions) to pass in the flag:
29 |
30 | ```sh
31 | NODE_OPTIONS='--import tsx' npx some-binary
32 | ```
33 |
34 | ## Advanced usage
35 |
36 | ### CommonJS mode only
37 |
38 | To use _tsx_ for CommonJS files only:
39 |
40 | ```sh
41 | node --require tsx/cjs ./file.ts
42 | ```
43 |
44 | ### Module mode only
45 |
46 | To use _tsx_ for Module files only:
47 |
48 | ```sh
49 | node --import tsx/esm ./file.ts
50 | ```
51 |
--------------------------------------------------------------------------------
/docs/dev-api/register-cjs.md:
--------------------------------------------------------------------------------
1 | # CommonJS Register API
2 |
3 | The CommonJS Register API allows you to manually register the enhancement at runtime. But note, this only affects CommonJS modules (`.cjs`/`.cts`, and `.js`/`.ts` when `package.json#type` is unset or `commonjs`).
4 |
5 | ::: warning Caveats
6 |
7 | - `import()` calls in the loaded files are not enhanced because they're handled by Node's ESM hook. Use with the [`ESM Register API`](/dev-api/register-esm).
8 | - Because it compiles ESM syntax to run in CommonJS mode, top-level await is not supported
9 | :::
10 |
11 | ## Usage
12 | ```js
13 | const tsx = require('tsx/cjs/api')
14 |
15 | // Register tsx enhancement
16 | const unregister = tsx.register()
17 |
18 | const loaded = require('./file.ts')
19 |
20 | // Unregister when needed
21 | unregister()
22 | ```
23 |
24 | ### Scoped registration
25 |
26 | If you want to register without affecting the entire runtime environment, you can add a namespace.
27 |
28 | When a namespace is provided, it will return a private `require()` method for you to load files with:
29 | ```js
30 | const tsx = require('tsx/cjs/api')
31 |
32 | const api = tsx.register({
33 | // Pass in a unique namespace
34 | namespace: Date.now().toString()
35 | })
36 |
37 | // Pass in the request and the current file path
38 | const loaded = api.require('./file.ts', __filename)
39 |
40 | api.unregister()
41 | ```
42 |
--------------------------------------------------------------------------------
/docs/dev-api/register-esm.md:
--------------------------------------------------------------------------------
1 | # ESM Register API
2 |
3 | The ESM Register API allows you to manually register the enhancement at runtime. But note, this only affects ESM (`.mjs`/`.mts`, and `.js`/`.ts` when `package.json#type` is `module`).
4 |
5 | ## Usage
6 | ```js
7 | import { register } from 'tsx/esm/api'
8 |
9 | // Register tsx enhancement
10 | const unregister = register()
11 |
12 | await import('./file.ts')
13 |
14 | // Unregister when needed
15 | unregister()
16 | ```
17 |
18 | ### Scoped registration
19 |
20 | If you want to register without affecting the entire runtime environment, you can add a namespace.
21 |
22 | When a namespace is provided, it will return a private `import()` method for you to load files with:
23 |
24 | ```js
25 | import { register } from 'tsx/esm/api'
26 |
27 | const api = register({
28 | // Pass in a unique namespace
29 | namespace: Date.now().toString()
30 | })
31 |
32 | // Pass in the request and the current file path
33 | // Since this is namespaced, it will not cache hit from prior imports
34 | const loaded = await api.import('./file.ts', import.meta.url)
35 |
36 | // This is using the same namespace as above, so it will yield a cache hit
37 | const loaded2 = await api.import('./file.ts', import.meta.url)
38 |
39 | api.unregister()
40 | ```
41 |
42 | ### Tracking loaded files
43 |
44 | Detect files that get loaded with the `onImport` hook. This can be useful when you want to track dependencies when setting up a watcher.
45 |
46 | ```ts
47 | register({
48 | onImport: (file: string) => {
49 | console.log(file) // 'file:///foo.ts'
50 | }
51 | })
52 | ```
53 |
--------------------------------------------------------------------------------
/docs/dev-api/ts-import.md:
--------------------------------------------------------------------------------
1 | # `tsImport()`
2 |
3 | Native dynamic `import()` function to import TypeScript files (supports [top-level await](https://v8.dev/features/top-level-await)).
4 |
5 | Use this function for importing TypeScript files without adding TypeScript support to the entire runtime.
6 |
7 | The current file path must be passed in as the second argument to resolve the import context.
8 |
9 | Since this is designed for one-time use, it does not cache loaded modules.
10 |
11 | ## Usage
12 |
13 | ### ESM
14 |
15 | ```js
16 | import { tsImport } from 'tsx/esm/api'
17 |
18 | const loaded = await tsImport('./file.ts', import.meta.url)
19 |
20 | // If tsImport is used to load file.ts again,
21 | // it does not yield a cache-hit and re-loads it
22 | const loadedAgain = await tsImport('./file.ts', import.meta.url)
23 | ```
24 |
25 | If you'd like to leverage module caching, see the [ESM scoped registration](/dev-api/register-esm.md) section.
26 |
27 | ### CommonJS
28 |
29 | ```js
30 | const { tsImport } = require('tsx/esm/api')
31 |
32 | const loaded = await tsImport('./file.ts', __filename)
33 | ```
34 |
35 | ## `tsconfig.json`
36 |
37 | ### Custom `tsconfig.json` path
38 | ```ts
39 | tsImport('./file.ts', {
40 | parentURL: import.meta.url,
41 | tsconfig: './custom-tsconfig.json'
42 | })
43 | ```
44 |
45 | ### Disable `tsconfig.json` lookup
46 | ```ts
47 | tsImport('./file.ts', {
48 | parentURL: import.meta.url,
49 | tsconfig: false
50 | })
51 | ```
52 |
53 | ## Tracking loaded files
54 |
55 | Detect files that get loaded with the `onImport` hook:
56 |
57 | ```ts
58 | tsImport('./file.ts', {
59 | parentURL: import.meta.url,
60 | onImport: (file: string) => {
61 | console.log(file)
62 | // file:///foo.ts
63 | }
64 | })
65 | ```
66 |
--------------------------------------------------------------------------------
/docs/dev-api/tsx-require.md:
--------------------------------------------------------------------------------
1 | # `tsx.require()`
2 |
3 | Native `require()` function enhanced with TypeScript & ESM support.
4 |
5 | Use this function for importing TypeScript files in CommonJS mode without adding TypeScript support to the entire runtime.
6 |
7 | Note, the current file path must be passed in as the second argument to resolve the import context.
8 |
9 | ::: warning Caveats
10 |
11 | - `import()` calls in the loaded files are not enhanced. Use [`tsImport()`](/dev-api/ts-import) instead.
12 | - Because it compiles ESM syntax to run in CommonJS mode, top-level await is not supported
13 | :::
14 |
15 | ## Usage
16 |
17 | ### CommonJS
18 |
19 | ```js
20 | const tsx = require('tsx/cjs/api')
21 |
22 | const tsLoaded = tsx.require('./file.ts', __filename)
23 | const tsFilepath = tsx.require.resolve('./file.ts', __filename)
24 | ```
25 |
26 | ### ESM
27 |
28 | ```js
29 | import { require } from 'tsx/cjs/api'
30 |
31 | const tsLoaded = require('./file.ts', import.meta.url)
32 | const tsFilepath = require.resolve('./file.ts', import.meta.url)
33 | ```
34 |
35 | ## Tracking loaded files
36 |
37 | Because the CommonJS API tracks loaded modules in `require.cache`, you can use it to identify loaded files for dependency tracking. This can be useful when implementing a watcher.
38 |
39 | ```js
40 | const resolvedPath = tsx.require.resolve('./file', import.meta.url)
41 |
42 | const collectDependencies = module => [
43 | module.filename,
44 | ...module.children.flatMap(collectDependencies)
45 | ]
46 |
47 | console.log(collectDependencies(tsx.require.cache[resolvedPath]))
48 | // ['/file.ts', '/foo.ts', '/bar.ts']
49 | ```
50 |
--------------------------------------------------------------------------------
/docs/getting-started.md:
--------------------------------------------------------------------------------
1 | # Getting started
2 |
3 | ### Prerequisites
4 |
5 | Before you can start using _tsx_, ensure that you have [Node.js installed](https://nodejs.org/en/download/). _tsx_ is designed to be compatible with all [maintained versions](https://endoflife.date/nodejs) of Node.js.
6 |
7 | ## Quickstart
8 |
9 | `tsx` can be executed with [npx](https://docs.npmjs.com/cli/commands/npx/)—a tool to run npm packages without installing them.
10 |
11 | In your command-line, simply pass in a TypeScript file you'd like to run. It's that simple!
12 |
13 | ```sh
14 | npx tsx ./script.ts
15 | ```
16 |
17 | ## Project installation
18 |
19 | To install `tsx` as a project development dependency, run the following command in your project directory:
20 |
21 | ::: code-group
22 | ```sh [npm]
23 | $ npm install -D tsx
24 | ```
25 |
26 | ```sh [pnpm]
27 | $ pnpm add -D tsx
28 | ```
29 |
30 | ```sh [yarn]
31 | $ yarn add -D tsx
32 | ```
33 | :::
34 |
35 | #### Using `tsx`
36 |
37 | Once installed, you can invoke it with your package manager while in the project directory:
38 |
39 | ::: code-group
40 | ```sh [npm]
41 | $ npx tsx ./file.ts
42 | ```
43 |
44 | ```sh [pnpm]
45 | $ pnpm tsx ./file.ts
46 | ```
47 |
48 | ```sh [yarn]
49 | $ yarn tsx ./file.ts
50 | ```
51 | :::
52 |
53 | #### Using it in `package.json#scripts`
54 |
55 | Project commands are usually organized in the [`package.json#scripts`](https://docs.npmjs.com/cli/v10/using-npm/scripts) object.
56 |
57 | In the `scripts` object, you can reference `tsx` directly without `npx`:
58 |
59 | ```js
60 | // package.json
61 | {
62 | "scripts": {
63 | "start": "tsx ./file.ts"// [!code highlight]
64 | }
65 | }
66 | ```
67 |
68 | ## Global installation
69 |
70 | If you want to use `tsx` anywhere on your computer (without [`npx`](https://docs.npmjs.com/cli/commands/npx/)), install it globally:
71 |
72 | ::: code-group
73 | ```sh [npm]
74 | $ npm install -g tsx
75 | ```
76 |
77 | ```sh [pnpm]
78 | $ pnpm add -g tsx
79 | ```
80 |
81 | ```sh [yarn]
82 | Yarn 2 doesn't support global installation
83 | https://yarnpkg.com/migration/guide#use-yarn-dlx-instead-of-yarn-global
84 | ```
85 | :::
86 |
87 | This allows you to call `tsx` directly:
88 |
89 | ```sh
90 | tsx file.ts
91 | ```
92 |
--------------------------------------------------------------------------------
/docs/learn.md:
--------------------------------------------------------------------------------
1 | # Learning resources
2 |
3 | TypeScript can be difficult to get started with and _tsx_ is all about lowering that barrier of entry.
4 |
5 | Here are some great resources for your reference.
6 |
7 | ::: info
8 |
9 | This page is currently a work in progress.
10 |
11 | If you're a TypeScript educator or you know any TS courses that use tsx, [let us know](/contact)!
12 | :::
13 |
14 | ## Documentation
15 |
16 | - [TypeScript documentation](https://www.typescriptlang.org/docs/)
17 |
18 | - [Node.js documentation](https://nodejs.org/docs/latest/api/)
19 |
--------------------------------------------------------------------------------
/docs/node-enhancement.md:
--------------------------------------------------------------------------------
1 | # Node.js enhancement
2 |
3 | ## Swap `node` for `tsx`
4 |
5 | `tsx` is a drop-in replacement for `node`, meaning you can use it the exact same way (supports all [command-line flags](https://nodejs.org/api/cli.html)).
6 |
7 | If you have an existing `node` command, simply substitute it with `tsx`.
8 |
9 | ```sh
10 | node --no-warnings --env-file=.env ./file.js
11 | ```
12 |
6 | 
9 | 
6 | 
21 | 
22 | 
30 |
31 | 
17 |