Load TypeScript in your tool
tsx's developer API lets libraries, CLIs, and plugin systems load TypeScript files written by their users, such as my-tool.config.ts, without asking users to install a loader or build their files first. It also lets you run your own TypeScript with the node command.
What you can build
Support TypeScript config files
A user's project contains this config:
my-tool.config.ts
export default { port: 3000 } satisfies { port: number }Your tool, with tsx installed as one of its dependencies, loads it:
cli.mjs
import path from 'node:path'
import { pathToFileURL } from 'node:url'
import { tsImport } from 'tsx/esm/api'
const configUrl = pathToFileURL(path.resolve('my-tool.config.ts')).href
const loaded = await tsImport(configUrl, import.meta.url)
// A config that runs as CommonJS arrives with its default export nested one level deeper
const config = loaded.default?.__esModule ? loaded.default.default : loaded.default
console.log(config.port)When the user runs your tool from their project directory, it prints:
3000path.resolve() finds the config in the user's working directory rather than next to your tool. Whether the config runs as CommonJS or ESM depends on its extension and the user's package.json; see module formats. The tsImport() reference covers options such as a custom tsconfig.json.
Load plugins synchronously
When your plugin hook must return synchronously, use tsx.require():
const path = require('node:path')
const tsx = require('tsx/cjs/api')
const plugin = tsx.require(path.resolve('plugins/my-plugin.ts'), __filename)
console.log(plugin.default.name)Plugins load through CommonJS, so they cannot use top-level await. A plugin's export default is available as plugin.default.
Run your own TypeScript sources
While developing a tool in TypeScript, run it with node --import tsx ./src/cli.ts instead of building after every change; see Node.js CLI. Publish built JavaScript so your users do not depend on your TypeScript setup; see Build for distribution.
Why use tsx for loading
- Scoped:
tsImport()andtsx.require()enable TypeScript for the files they load and those files' imports, not for the rest of your application. This is not a security sandbox; see scope and lifetime. - Node.js semantics: files run through Node.js's own module loader, so an ESM config can use top-level
awaitandimport.meta. - CommonJS and ESM: your tool can be either format, and so can your users' files.
- No compiler dependency: tsx transforms files with esbuild and does not need the
typescriptpackage. - Users'
tsconfig.json: tsx readstsconfig.jsonfrom the working directory, so settings such as JSX andpathsapply.tsImport()also accepts a custom path.
Choose an integration
| You need to... | Use | Scope and lifetime |
|---|---|---|
Run an application with node, or configure a tool that launches Node.js | Node.js CLI | Preload tsx before the application starts |
| Enable tsx from a JavaScript entry file | Entry-point import | Register at runtime, then load the application dynamically |
| Load a TypeScript configuration or plugin asynchronously | tsImport() | A fresh loading namespace per call |
| Load TypeScript synchronously | tsx.require() | A shared CommonJS loading namespace with module caching |
Control registration and cleanup for dynamic import() | ESM Register API | Global or namespaced registration with asynchronous cleanup |
Control registration and cleanup for require() | CommonJS Register API | Global or namespaced registration with synchronous cleanup |
Directly running Node.js
For an application, prefer node --import tsx: the launch command makes the runtime setup visible and registers tsx before static imports run. Use an entry-point import when you cannot change the launch command. Explicit registration provides lifecycle control when the application needs to turn a loading enhancement off.
Loading files in third-party packages
Use tsImport() for asynchronous configuration or plugin loading, or tsx.require() when the caller requires a synchronous result. These APIs scope tsx loading rather than enabling it for unrelated application imports. Choose explicit namespaced registration when you also need a reusable namespace and cleanup handle.
Prerequisites
Install tsx in the project that uses these APIs; see installation. If a published package uses tsx at runtime, declare it as a runtime dependency rather than only a development dependency. Check compatibility, including the requirements for ESM registration.
Understanding module types
An asynchronous API does not automatically turn a CommonJS file into an ES module. The loaded file's extension, package scope, and loader determine how it runs; see module formats for execution rules, top-level await, and interoperability.
Scope and lifetime
A namespace is an identifier that scopes tsx loading and module cache identities. Global registration enhances subsequent loads through the selected loading path. Namespaced registration enhances loads made through its handle and their supported dependency-loading paths, rather than unrelated application imports.
Scope is not a security sandbox. Loaded code can modify globals, open files, and perform other process-wide side effects. Built-in modules and shared runtime objects are not isolated. Separate tsx module identities do not mean that every resource or transformation is uncached.
The CommonJS APIs enhance require(), not dynamic import() calls. The ESM registration API enhances the import loading path, not the separate global CommonJS registration. Use the combined tsx preload for applications that need both. tsImport() installs namespaced registrations for both loading paths.
Unregistering stops a registration; it does not unload cached modules, invalidate dependencies, or undo side effects. Keep a registration active while loaded code still needs it for later imports or requires. The individual API references describe their cache behavior and whether they expose cleanup.
These APIs provide module loading, not CLI features such as watch mode or the interactive REPL.
