{"id":12199,"library":"tsm","title":"tsm: TypeScript Module Loader","description":"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.","status":"active","version":"2.3.0","language":"javascript","source_language":"en","source_url":"https://github.com/lukeed/tsm","tags":["javascript","esm","loader","typescript","loader hook","require hook","experimental-loader"],"install":[{"cmd":"npm install tsm","lang":"bash","label":"npm"},{"cmd":"yarn add tsm","lang":"bash","label":"yarn"},{"cmd":"pnpm add tsm","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"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.","wrong":"node my-script.ts","symbol":"tsm CLI","correct":"tsm my-script.ts"},{"note":"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.","wrong":"import 'tsm'","symbol":"Node.js --require hook","correct":"node --require tsm my-script.tsx"},{"note":"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.","wrong":"node --experimental-loader tsm my-module.jsx","symbol":"Node.js --loader hook","correct":"node --loader tsm my-module.jsx"}],"quickstart":{"code":"// src/server.ts\nimport { createServer } from 'http';\n\nconst PORT = process.env.PORT ? parseInt(process.env.PORT, 10) : 3000;\n\ncreateServer((req, res) => {\n  res.writeHead(200, { 'Content-Type': 'text/plain' });\n  res.end(`Hello from tsm-powered Node.js server!\\nRequest Path: ${req.url}\\n`);\n}).listen(PORT, () => {\n  console.log(`Server running at http://localhost:${PORT}/`);\n  console.log('Try visiting /test or any other path.');\n});\n\n// To run this server:\n// 1. Install tsm: npm install --save-dev tsm\n// 2. Add a script to your package.json: \"start\": \"tsm src/server.ts\"\n// 3. Run: npm start\n// Alternatively, run directly: npx tsm src/server.ts","lang":"typescript","description":"Demonstrates how to start a simple HTTP server written in TypeScript using `tsm` for direct execution, showcasing basic setup and usage via CLI."},"warnings":[{"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.","message":"Node.js ESM loader hooks (`--loader`) are marked `Stability 1: Experimental` and have undergone multiple breaking API changes across Node.js versions.","severity":"breaking","affected_versions":">=2.1.3"},{"fix":"Upgrade `tsm` to `v2.2.2` or newer to ensure compatibility with Node.js `>=18.6.0`.","message":"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+.","severity":"breaking","affected_versions":"<2.2.2"},{"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.","message":"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`.","severity":"breaking","affected_versions":"<2.1.3"},{"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.","message":"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.","severity":"gotcha","affected_versions":"Fixed in `>=2.1.1` for `tsm`'s handling. Still a general Node.js issue if `tsm` is not active."},{"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`.","message":"`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.","severity":"gotcha","affected_versions":"All versions (behavior dependent on bundled `esbuild` version)"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"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.","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.","error":"Error [ERR_REQUIRE_ESM]: require() of ES Module ... not supported."},{"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.","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.","error":"(node:...) ExperimentalWarning: The ESM loader API is experimental and subject to change."},{"fix":"Upgrade `tsm` to `v2.2.2` or newer, which includes the necessary `shortCircuit: true` handling for Node.js `>=18.6.0`.","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.","error":"TypeError: Loader hook of type 'resolve' must not return 'undefined'"}],"ecosystem":"npm"}