Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslnode 18–226 runs
build_error
glibcnode 18–226 runs
build_error
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
tsm CLI
✓ tsm my-script.ts
✗ node my-script.ts
This is the primary way to execute TypeScript files directly, acting as a drop-in replacement for the `node` command for TS files. It handles `process.argv` and Node.js environment variables correctly.
Node.js --require hook
✓ node --require tsm my-script.tsx
✗ import 'tsm'
Activates `tsm` as a CommonJS `require` hook, allowing Node.js to load and transpile TypeScript files on the fly. This method is typically used for synchronous module loading within a CommonJS context.
Node.js --loader hook
✓ node --loader tsm my-module.jsx
✗ node --experimental-loader tsm my-module.jsx
Activates `tsm` as an ECMAScript Module loader hook. This Node.js API is still experimental (Stability 1) and has undergone breaking changes across Node.js versions (e.g., v16.12.0 and v18.6.0). Ensure `tsm` is up-to-date with your Node.js version.
Demonstrates how to start a simple HTTP server written in TypeScript using `tsm` for direct execution, showcasing basic setup and usage via CLI.
// src/server.ts
import { createServer } from 'http';
const PORT = process.env.PORT ? parseInt(process.env.PORT, 10) : 3000;
createServer((req, res) => {
res.writeHead(200, { 'Content-Type': 'text/plain' });
res.end(`Hello from tsm-powered Node.js server!\nRequest Path: ${req.url}\n`);
}).listen(PORT, () => {
console.log(`Server running at http://localhost:${PORT}/`);
console.log('Try visiting /test or any other path.');
});
// To run this server:
// 1. Install tsm: npm install --save-dev tsm
// 2. Add a script to your package.json: "start": "tsm src/server.ts"
// 3. Run: npm start
// Alternatively, run directly: npx tsm src/server.ts
tsm --version
Debug
Known issues
breakingNode.js ESM loader hooks (`--loader`) are marked `Stability 1: Experimental` and have undergone multiple breaking API changes across Node.js versions.fixAlways ensure `tsm` is updated to the latest version compatible with your specific Node.js minor/patch version, especially when using `--loader`. Consult `tsm` and Node.js changelogs for compatibility.
affects: >=2.1.3
breakingNode.js v18.6.0 introduced a breaking change requiring `shortCircuit: true` in ESM loader `resolve` hook return values. `tsm` versions prior to `2.2.2` will fail on Node.js v18.6.0+.fixUpgrade `tsm` to `v2.2.2` or newer to ensure compatibility with Node.js `>=18.6.0`.
affects: <2.2.2
breakingNode.js v16.12.0 updated the ESM loader API (e.g., `resolve` hook signature). `tsm` versions prior to `2.1.3` may not function correctly with Node.js `>=16.12.0` when using `--loader`.fixUpgrade `tsm` to `v2.1.3` or newer. `tsm v2.1.3` was designed to support both the old and new API designs for backward compatibility.
affects: <2.1.3
gotchaUsing `require()` for JavaScript files containing ESM syntax (`import`/`export`) will throw `ERR_REQUIRE_ESM` errors in Node.js. `tsm` provides a fix for this, but it's a common Node.js interop challenge.fixEnsure `tsm` is at `v2.1.1` or newer and is active (via `tsm` CLI or `node --require tsm`). Best practice is to avoid `require()`ing ESM `.js` files; use dynamic `import()` or ensure consistent module types.
affects: Fixed in `>=2.1.1` for `tsm`'s handling. Still a general Node.js issue if `tsm` is not active.
gotcha`tsm` relies on `esbuild` for its core transpilation. Major `esbuild` updates (e.g., v0.14.x in `tsm v2.2.0`, v0.15.x in `tsm v2.3.0`) can introduce subtle behavioral changes, new feature support (like `satisfies` operator), or new limitations.fixReview `esbuild` changelogs when upgrading `tsm` across versions that bump `esbuild` major/minor. Ensure your TypeScript syntax and desired target features are supported by the `esbuild` version bundled with `tsm`.
affects: All versions (behavior dependent on bundled `esbuild` version)
Errors
Common errors & fixes
Error [ERR_REQUIRE_ESM]: require() of ES Module ... not supported.
Attempting to `require()` a JavaScript file that contains ESM syntax (`import`/`export`) in a CommonJS context without `tsm`'s specific handling, or using an older `tsm` version.
fixEnsure `tsm` is installed and active (either via `tsm` CLI or `node --require tsm`). Upgrade `tsm` to `v2.1.1` or newer, which addresses this interop issue.
(node:...) ExperimentalWarning: The ESM loader API is experimental and subject to change.
This warning is issued by Node.js itself, indicating that the `--loader` hook API, which `tsm` utilizes for ESM support, is still experimental and not stable.
fixThis is an expected warning when using `tsm` with `node --loader`. It indicates the underlying Node.js API is unstable. Ensure `tsm` is always up-to-date with your Node.js version to mitigate potential breaking changes in the loader API.
TypeError: Loader hook of type 'resolve' must not return 'undefined'
Node.js `v18.6.0` and later versions require the `resolve` hook in ESM loaders to explicitly return `shortCircuit: true` for certain paths or it will throw this error. Older `tsm` versions do not include this.
fixUpgrade `tsm` to `v2.2.2` or newer, which includes the necessary `shortCircuit: true` handling for Node.js `>=18.6.0`.
Audit
Dependencies
No dependency data recorded yet.