‏ts-exec: اجرای TypeScript تو Node.js بدون غافلگیری تو پروداکشن

ts-exec یه موتور اجرای TypeScript هست که اجازه می‌ده فایل‌های .ts و .tsx رو بدون مرحلهٔ build مستقیم تو Node.js اجرا کنی. روی SWC (یه کامپایلر سریع نوشته‌شده با Rust) ساخته شده، ESM رو کامل پشتیبانی می‌کنه و برای Node.js نسخهٔ 24 به بالاست. کل کدش کمتر از ۲۰۰ خطه و از پروژهٔ Amaro خود Node.js الهام گرفته. اجراش هم ساده‌ست: node --import=@poppinss/ts-exec ./src/index.ts.

سازنده‌ها می‌گن ابزارهای فعلی هرکدوم یه مشکل دارن. ts-node دیگه فعالانه نگهداری نمی‌شه و سنگین شده. tsx مدرن و سریعه، ولی importهای بدون پسوند و import یه پوشه رو تو توسعه قبول می‌کنه. مشکل اینه که Node.js بعد از کامپایل پسوند صریح فایل می‌خواد و import پوشه رو اصلاً پیدا نمی‌کنه. یعنی کد تو توسعه سالم اجرا می‌شه ولی تو پروداکشن با خطای Cannot find module می‌ترکه.

ts-exec دقیقاً همین شکاف رو می‌بنده. همهٔ قابلیت‌های TypeScript مثل enum، legacy decorators (یعنی همون decoratorهای قدیمی که خیلی فریم‌ورک‌ها هنوز بهشون وابسته‌ن) و JSX رو داره، ولی از قوانین module resolution خود Node.js سفت‌وسخت پیروی می‌کنه. نمونهٔ مقاله این فرق رو نشون می‌ده:

// Extension-less import
import { User } from './models/user'

// Explicit extension
import { User } from './models/user.ts'

خط اول با tsx کار می‌کنه ولی بعد از کامپایل خراب می‌شه، خط دوم با ts-exec هم تو توسعه و هم بعد از کامپایل کار می‌کنه. برای استفاده از پسوند .ts تو importها باید گزینهٔ rewriteRelativeImportExtensions رو تو tsconfig.json روشن کنی تا TypeScript موقع کامپایل .ts رو به .js تبدیل کنه. بدون اون باید طبق روش قدیمی TypeScript از همون اول .js بنویسی.

برای subpath import aliasها که تو package.json تعریف می‌شن، مسیرها باید همیشه به خروجی .js اشاره کنن، چون کامپایلر هیچ‌وقت package.json رو بازنویسی نمی‌کنه و rewriteRelativeImportExtensions فقط روی importهای نسبی (شروع با ./ یا ../) اثر داره. فایل‌هایی که با require لود می‌شن (مثلاً از طریق createRequire) هم کامپایل می‌شن، ولی فایل‌های .jsx و .tsx همیشه ES module حساب می‌شن و نمی‌تونن از module.exports استفاده کنن.

نکات کلیدی:

• نصب با npm i -D @poppinss/ts-exec و اجرا با node --import=@poppinss/ts-exec
• روی SWC ساخته شده، کمتر از ۲۰۰ خط کد و برای Node.js 24 به بالا
• importهای بدون پسوند و import پوشه رو قبول نمی‌کنه تا کد بعد از کامپایل خراب نشه
• برخلاف tsx از legacy decorators پشتیبانی می‌کنه
• برای پسوند .ts تو importها گزینهٔ rewriteRelativeImportExtensions لازمه
• tsconfig.json رو خودکار می‌خونه و فایل کانفیگ جدا نمی‌خواد