tsx 4.x

Complete instructions

Verified against tsx@4.23.13 on 2026-09-07. 2 of 2 examples executed.

tsx

Scope

This skill targets tsx ^4.0.0. It covers the documented package entry points and Developer APIs, plus the CLI features shown by the research. tsx is a drop-in node replacement that adds TypeScript support, CommonJS/ESM interoperability, tsconfig.json paths, and esbuild-based transformation. It does not perform type checking.

The runnable examples below are standalone Bun scripts. The package-entry, tsImport, and enhanced-require smoke tests were not retained because they failed when run standalone under the supplied Bun environment; see Standalone-runtime limitation.

v4 corrections

• Use the TSX_ environment-variable prefix. ESBK_ is the v3-era prefix and is not the v4 prefix.
• v4 supports Node.js LTS versions 18 and newer. Do not target Node.js versions below 18.
• v4 added resolver support for .tsx and .jsx.
• CommonJS import specifiers may contain queries.
• Transformation warnings are emitted through stderr.

CLI usage

Install it as a development dependency with npm install -D tsx, then run a TypeScript file with tsx file.ts. The general command shape is:

tsx [tsx flags] ./file.ts [flags & arguments for file.ts]

A package script can use tsx ./file.ts, and npx tsx ./script.ts also works without a local installation.

The equivalent Node integration is node --import tsx ./file.ts.

Package entry points

The package entry point automatically registers TypeScript loading for subsequent imports:

import 'tsx'

const loaded = await import('./file.ts')

For CommonJS-only mode, use require('tsx/cjs'). For module-only mode, use import 'tsx/esm'.

The package entry point is a loader setup, not a value-oriented API. Use it when the surrounding runtime can perform the subsequent TypeScript import. The standalone smoke test from the earlier draft failed under the supplied Bun execution environment with a missing ./cjs/index.cjs module, so this skill does not claim that smoke test is portable to that environment.

Dynamic ESM loading: tsx/esm/api

tsx/esm/api exports named tsImport. It dynamically imports a TypeScript module, with the second argument supplying import context:

import { tsImport } from 'tsx/esm/api'

const loaded = await tsImport('./file.ts', import.meta.url)

The options form accepts parentURL and can select a custom tsconfig:

const loaded = await tsImport('./file.ts', {
  parentURL: import.meta.url,
  tsconfig: './custom-tsconfig.json'
})

The documented options also include tsconfig: false and an onImport callback receiving the imported file path.

Do not use a built-in module as a portability smoke test for this API. The earlier standalone example calling tsImport('node:path', import.meta.url) failed under the supplied Bun environment because the generated tsx://... module could not be resolved. The research does not establish a standalone Bun-compatible substitute.

Enhanced CommonJS loading: tsx/cjs/api

tsx/cjs/api exports a named enhanced require function. Its documented usage supplies the request and parent path:

import { require } from 'tsx/cjs/api'

const loaded = require('./file.ts', import.meta.url)

The function also exposes .resolve and .cache:

const filepath = require.resolve('./file.ts', import.meta.url)

The earlier standalone example using node:path failed under the supplied Bun environment while invoking the enhanced loader. It is therefore not presented as a runnable standalone example. The documented API remains the relevant shape for a compatible Node/CommonJS integration.

Scoped CJS registration

tsx/cjs/api exports register. It returns an unregister cleanup function, or a scoped API containing require and unregister:

const tsx = require('tsx/cjs/api')
const unregister = tsx.register()
const loaded = require('./file.ts')
unregister()

Use the cleanup function when the registration is no longer needed.

import { register } from 'tsx/cjs/api'
import assert from 'node:assert/strict'

const unregister = register()

assert.equal(typeof unregister, 'function')
unregister()

Scoped ESM registration

tsx/esm/api also exports register. It returns an unregister cleanup function, or a scoped API containing import and unregister:

import { register } from 'tsx/esm/api'

const unregister = register()
await import('./file.ts')
unregister()

import { register } from 'tsx/esm/api'
import assert from 'node:assert/strict'

const unregister = register()

assert.equal(typeof unregister, 'function')
unregister()

CLI-only features

These features are exercised by the tsx command itself rather than by the Developer API:

• Watch mode: tsx watch ./file.ts
• Watch includes: --include ./other-dep.txt and --include "./other-deps/*"
• Watch exclusions: --exclude "./data/**/*"
• Disable watch-screen clearing with --clear-screen=false
• The TypeScript REPL, entered by running tsx with no script
• Node's enhanced test runner, invoked with tsx --test

Watch mode reruns when dependencies change. The Developer API does not provide watch mode or the REPL. describe, it, and expect are not available in a directly executed script; test files use the tool's test-runner integration instead.

Standalone-runtime limitation

In the supplied standalone Bun execution, these documented loading operations did not produce runnable examples:

• importing the package entry point failed with a missing ./cjs/index.cjs module;
• tsImport failed while resolving its generated tsx://... module;
• enhanced require failed while loading the built-in-module smoke test.

Those failures are runtime-specific observations from the required standalone execution, not evidence that the documented Node integration shapes should be changed. Registration itself was independently runnable, so those examples are retained.

Does not cover

This skill does not cover the full CLI flag set, watch-mode dependency semantics beyond the documented include/exclude options, REPL behavior, tsx --test test discovery, TypeScript compiler type checking, undocumented loader internals, Bun-specific compatibility beyond the observed standalone failures, or configuration details not shown in the supplied research.