tsm: TypeScript Module Loader

2.3.0 · active · verified Sun Apr 19

tsm is a TypeScript Module Loader for Node.js, currently at version 2.3.0, enabling seamless execution of TypeScript and modern JavaScript files directly within Node.js environments without a separate compilation step. It leverages `esbuild` for high-performance transformations, allowing developers to run `.ts`, `.tsx`, `.mts`, and `.cts` files out-of-the-box. The package is actively maintained, with recent releases addressing compatibility with newer Node.js versions and `esbuild` updates, indicating a responsive release cadence. Its key differentiators include comprehensive support for multiple Node.js execution paradigms: direct CLI invocation (`tsm script.ts`), the `--require` hook for CommonJS environments, and the experimental `--loader` hook for ECMAScript Modules. tsm also handles complex interop scenarios, such as requiring ESM `.js` files, and supports modern TypeScript features like the `satisfies` operator, making it a robust solution for developing Node.js applications with TypeScript by simplifying the developer experience.

Common errors

```
Error [ERR_REQUIRE_ESM]: require() of ES Module ... not supported.
```
cause 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.

fix Ensure `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.
```
cause 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.

fix This 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'
```
cause 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.

fix Upgrade `tsm` to `v2.2.2` or newer, which includes the necessary `shortCircuit: true` handling for Node.js `>=18.6.0`.

Warnings

breaking Node.js ESM loader hooks (`--loader`) are marked `Stability 1: Experimental` and have undergone multiple breaking API changes across Node.js versions.
Fix: Always 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.
breaking Node.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+.
Fix: Upgrade `tsm` to `v2.2.2` or newer to ensure compatibility with Node.js `>=18.6.0`.
breaking Node.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`.
Fix: Upgrade `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.
gotcha Using `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.
Fix: Ensure `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.
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.
Fix: Review `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`.

Install

npm install tsm npm
yarn add tsm yarn
pnpm add tsm pnpm

Imports

tsm CLI
wrong:
```
node my-script.ts
```
correct:
```
tsm 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
wrong:
```
import 'tsm'
```
correct:
```
node --require tsm my-script.tsx
```
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
wrong:
```
node --experimental-loader tsm my-module.jsx
```
correct:
```
node --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.

Quickstart

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

view raw JSON →