{"id":26509,"library":"ts-directly","title":"ts-directly","description":"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.","status":"active","version":"2.1.2","language":"javascript","source_language":"en","source_url":"https://github.com/Kaciras/ts-directly","tags":["javascript","loader","compiler","node","esm","typescript"],"install":[{"cmd":"npm install ts-directly","lang":"bash","label":"npm"},{"cmd":"yarn add ts-directly","lang":"bash","label":"yarn"},{"cmd":"pnpm add ts-directly","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Optional runtime dependency for colorized error output, always installed with package.","package":"supports-color","optional":true}],"imports":[{"note":"ESM-only; CommonJS require will fail since v2.0.0.","wrong":"const { transform } = require('ts-directly')","symbol":"transform","correct":"import { transform } from 'ts-directly'"},{"note":"Use 'ts-directly/register' with --import flag, not as a module path. The register function is on module object, not exported directly.","wrong":"require('ts-directly/register')","symbol":"register","correct":"module.register('ts-directly', import.meta.url)"},{"note":"The register entry point is imported as a side effect, not assigned to a variable.","wrong":"require('ts-directly/register')","symbol":"default export","correct":"import 'ts-directly/register'"}],"quickstart":{"code":"// Install: pnpm add ts-directly\n// Ensure at least one compiler is installed, e.g., typescript: pnpm add typescript\n\n// File: main.ts\nimport { readFileSync } from 'fs';\nimport { transform } from 'ts-directly';\n\nconst tsCode = readFileSync('example.ts', 'utf8');\ntransform(tsCode, 'example.ts')\n  .then(({ source, format }) => {\n    console.log(format); // 'module' or 'commonjs'\n    console.log(source.substring(0, 100)); // preview\n  });\n\n// Or run directly with Node:\n// node --import ts-directly/register main.ts","lang":"typescript","description":"Shows how to import and use the transform API, and how to register the loader to run TS files directly."},"warnings":[{"fix":"Use the automatic detection or switch to transform() which internally detects the compiler.","message":"detectTypeScriptCompiler export removed in v2.0.0","severity":"breaking","affected_versions":">=2.0.0"},{"fix":"Use import statements or dynamic import() instead of require().","message":"ESM-only: require() will throw ERR_REQUIRE_ESM since v2.0.0","severity":"breaking","affected_versions":">=2.0.0"},{"fix":"Install one of: @swc/core, esbuild, sucrase, or typescript. If multiple are present, the fastest (esbuild > sucrase > swc > tsc) is chosen.","message":"Compiler must be installed separately; missing compiler causes runtime error: 'No TypeScript compiler found'","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Always use full file paths with extensions for aliased imports, or avoid alias for directory resolution.","message":"Paths alias only works for import/require, not for directory indexes or extension-less requires","severity":"gotcha","affected_versions":">=2.1.0"},{"fix":"Use the loader registration if you need import resolution (e.g., .js -> .ts redirection), not just transform().","message":"Single file transform does not handle module resolution; for full ESM loader use --import ts-directly/register","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-05-01T00:00:00.000Z","next_check":"2026-07-30T00:00:00.000Z","problems":[{"fix":"Install one of: @swc/core, esbuild, sucrase, or typescript as a dependency.","cause":"No supported compiler installed in the project.","error":"No TypeScript compiler found"},{"fix":"Use import statements or dynamic import(). If you must use CommonJS, downgrade to v1.x.","cause":"Using require() on an ESM-only package (ts-directly is ESM-only since v2.0.0).","error":"ERR_REQUIRE_ESM"},{"fix":"Set TS_COMPILER to one of: 'swc', 'esbuild', 'sucrase', 'tsc' (case-insensitive).","cause":"The TS_COMPILER env var is set to an unsupported value.","error":"Invalid TS_COMPILER environment variable: 'some-value'"}],"ecosystem":"npm","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null}