ts-directly

library2.1.2jsnpmunverified

TS-Directly (v2.1.2) is a lightweight ESM loader that lets Node.js execute TypeScript files directly using the compiler already installed in the project (SWC, esbuild, sucrase, or tsc). It features automatic compiler detection (preferring the fastest), respects closest tsconfig.json including baseUrl/paths aliases, supports .cts/.mts files and ESNext module output, and exposes a transform API. Unlike ts-node or tsx it does not bundle a compiler, making it ideal for CLI tools that want to reuse existing dependencies. Released monthly on npm, actively maintained with 5 KB minified size and zero extra dependency beyond node loaders.

web-framework

npm install ts-directly

github ↗package ↗

INSTALL

IMPORT

SIG · TS-DIRECTLY

ts-directly

web-frameworkjavascriptv2.1.2

harness data pending

Install & Compatibility

Where this runs

No compatibility data collected yet for this library.

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

transform

✓ import { transform } from 'ts-directly'

✗ const { transform } = require('ts-directly')

ESM-only; CommonJS require will fail since v2.0.0.

✓ module.register('ts-directly', import.meta.url)

✗ require('ts-directly/register')

Use 'ts-directly/register' with --import flag, not as a module path. The register function is on module object, not exported directly.

default export

✓ import 'ts-directly/register'

✗ require('ts-directly/register')

The register entry point is imported as a side effect, not assigned to a variable.

Shows how to import and use the transform API, and how to register the loader to run TS files directly.

// Install: pnpm add ts-directly // Ensure at least one compiler is installed, e.g., typescript: pnpm add typescript // File: main.ts import { readFileSync } from 'fs'; import { transform } from 'ts-directly'; const tsCode = readFileSync('example.ts', 'utf8'); transform(tsCode, 'example.ts') .then(({ source, format }) => { console.log(format); // 'module' or 'commonjs' console.log(source.substring(0, 100)); // preview }); // Or run directly with Node: // node --import ts-directly/register main.ts

Debug

Known issues

breakingdetectTypeScriptCompiler export removed in v2.0.0

fix

Use the automatic detection or switch to transform() which internally detects the compiler.

affects: >=2.0.0

breakingESM-only: require() will throw ERR_REQUIRE_ESM since v2.0.0

fix

Use import statements or dynamic import() instead of require().

affects: >=2.0.0

gotchaCompiler must be installed separately; missing compiler causes runtime error: 'No TypeScript compiler found'

fix

Install one of: @swc/core, esbuild, sucrase, or typescript. If multiple are present, the fastest (esbuild > sucrase > swc > tsc) is chosen.

affects: >=1.0.0

gotchaPaths alias only works for import/require, not for directory indexes or extension-less requires

fix

Always use full file paths with extensions for aliased imports, or avoid alias for directory resolution.

affects: >=2.1.0

gotchaSingle file transform does not handle module resolution; for full ESM loader use --import ts-directly/register

fix

Use the loader registration if you need import resolution (e.g., .js -> .ts redirection), not just transform().

affects: >=1.0.0

Errors

Common errors & fixes

No TypeScript compiler found

No supported compiler installed in the project.

fix

Install one of: @swc/core, esbuild, sucrase, or typescript as a dependency.

ERR_REQUIRE_ESM

Using require() on an ESM-only package (ts-directly is ESM-only since v2.0.0).

fix

Use import statements or dynamic import(). If you must use CommonJS, downgrade to v1.x.

Invalid TS_COMPILER environment variable: 'some-value'

The TS_COMPILER env var is set to an unsupported value.

fix

Set TS_COMPILER to one of: 'swc', 'esbuild', 'sucrase', 'tsc' (case-insensitive).

Upgrade

Version history

2.1.2latest on npm

Audit

Dependencies

supports-coloroptionalOptional runtime dependency for colorized error output, always installed with package.

Agent activity

10 hits · last 30 days

node

Resources

githubhttps://github.com/Kaciras/ts-directly ↗

packagehttps://www.npmjs.com/package/ts-directly ↗