Skip to main content

9. TSX TypeScript Execution

Status: Accepted Date: 2025-01-28 Deciders: Development Team

Context​

We need to execute TypeScript scripts directly without a separate compilation step. The monorepo is heavily TypeScript-based and we want type checking benefits in scripts while maintaining development velocity.

Requirements:

  • Direct TypeScript execution in development
  • Type checking during script execution
  • No separate compilation step required
  • Fast startup times for scripts
  • Support for modern TypeScript features

Alternatives considered:

  • ts-node - slower, more configuration
  • Pre-compilation with tsc - extra build step
  • esbuild-register - faster but less type checking
  • bun - not mature enough for production use

Decision​

Use tsx for TypeScript script execution.

Consequences​

Positive:

  • Immediate script execution without compilation
  • Type safety in all scripts
  • Faster development iteration
  • Simplified package.json scripts
  • Consistent execution environment
  • Fast execution with minimal overhead
  • Full TypeScript type checking during execution
  • Zero configuration required
  • Compatible with all modern TypeScript features
  • Excellent performance compared to ts-node

Negative:

  • Runtime dependency on tsx
  • Slightly slower than pre-compiled JavaScript
  • Not suitable for production execution (use compiled JS)

Mitigation:

  • Use tsx only for development scripts and CLI tools
  • Production deployments use compiled JavaScript
  • Document tsx usage patterns for team consistency
  • Keep tsx version pinned for stability