tsx

TypeScript Execute (tsx): Node.js enhanced with esbuild to run TypeScript & ESM files

weekly downloads23.9M

versionv4.21.0

licenseMIT

categorytoolchain

cliruntimenodecjscommonjsesmtypescripttypescript runner

Overview

tsx is a command-line tool that enhances Node.js to execute TypeScript and ESM files directly without a separate compilation step. It acts as a drop-in replacement for the node command, using esbuild under the hood to transpile TypeScript on-the-fly with near-native JavaScript performance. With over 23 million weekly downloads, tsx has become a standard tool for TypeScript developers who want to skip the build step during development.

The package exists to solve a fundamental pain point in TypeScript development: the friction of compiling code before running it. Traditional workflows require running tsc to generate JavaScript files or configuring complex build pipelines. tsx eliminates this overhead by transpiling files on-demand as they're imported, making the developer experience feel as immediate as working with plain JavaScript.

tsx is particularly popular among developers building Node.js applications, CLI tools, automation scripts, and backend services. It's used both in local development environments for rapid iteration and in production scenarios where deployment simplicity matters. The tool supports CommonJS and ES modules, handles JSX syntax, and respects TypeScript's path mappings and other configuration options.

Unlike compilation-based approaches, tsx doesn't generate intermediate .js files or require watch processes for compilation. It simply runs your TypeScript code directly, making it ideal for prototyping, running one-off scripts, testing, and any scenario where you want TypeScript's type safety without the build step complexity.

Quick Start

typescript

// server.ts - Express server with TypeScript
import express, { Request, Response } from 'express';
import { readFile } from 'fs/promises';
import path from 'path';

interface UserConfig {
  port: number;
  environment: 'development' | 'production';
}

const config: UserConfig = {
  port: Number(process.env.PORT) || 3000,
  environment: process.env.NODE_ENV === 'production' ? 'production' : 'development'
};

const app = express();

app.get('/api/status', async (req: Request, res: Response) => {
  const packageJson = JSON.parse(
    await readFile(path.join(process.cwd(), 'package.json'), 'utf-8')
  );
  
  res.json({
    status: 'running',
    version: packageJson.version,
    environment: config.environment,
    timestamp: new Date().toISOString()
  });
});

app.listen(config.port, () => {
  console.log(`Server running on port ${config.port} in ${config.environment} mode`);
});

// Run with: npx tsx server.ts
// Watch mode: npx tsx watch server.ts
// With env vars: PORT=8080 NODE_ENV=production npx tsx server.ts

Use Cases

Development Scripts and Automation: Run TypeScript build scripts, database seeders, data migration tools, or automation tasks directly without compiling. Instead of maintaining separate compiled versions, execute scripts with tsx ./scripts/seed-database.ts and get immediate feedback.

Local Development with Watch Mode: Use tsx watch to automatically restart your Node.js server or application whenever source files change. This provides a fast feedback loop during development without configuring separate build watchers or nodemon with TypeScript support.

Running Tests and Tooling: Execute TypeScript test files, code generators, or development utilities directly. Many developers use tsx to run test suites or custom tooling without adding compilation steps to their workflow.

Prototyping and Experimentation: Quickly prototype ideas or test TypeScript code snippets without setting up full build configurations. tsx makes it easy to create standalone .ts files and run them immediately, perfect for learning or experimenting with APIs.

Production Deployments: Deploy Node.js applications without a build step by using tsx as the runtime. This simplifies deployment pipelines and reduces build times, though it trades compile-time optimization for deployment simplicity. Popular in containerized environments and serverless functions where startup time matters less than deployment speed.

Pros & Cons

Pros

+Extremely fast transpilation using esbuild, significantly faster than ts-node which uses TypeScript's compiler
+Zero configuration needed for most projects - works immediately with standard TypeScript setups
+Built-in watch mode eliminates need for additional tools like nodemon
+Supports both CommonJS and ESM modules without special flags or configuration
+No intermediate .js files generated, keeping your project directory clean

Cons

−No type checking during execution - you need to run tsc separately for type validation
−Adds runtime overhead compared to pre-compiled JavaScript, though minimal with esbuild
−May not support some advanced TypeScript compiler options that esbuild doesn't implement
−Debugging can be less straightforward than with pre-compiled code due to transpilation layer
−Not a replacement for production builds where bundle size optimization and tree-shaking matter

Alternatives

bunv1.3.9

Bun is a fast all-in-one JavaScript runtime.

toolchainbunbun.js

822K / week

Install

bash

npm install tsx

bash

pnpm add tsx

bash

bun add tsx

Overview

Quick Start

typescript

// server.ts - Express server with TypeScript
import express, { Request, Response } from 'express';
import { readFile } from 'fs/promises';
import path from 'path';

interface UserConfig {
  port: number;
  environment: 'development' | 'production';
}

const config: UserConfig = {
  port: Number(process.env.PORT) || 3000,
  environment: process.env.NODE_ENV === 'production' ? 'production' : 'development'
};

const app = express();

app.get('/api/status', async (req: Request, res: Response) => {
  const packageJson = JSON.parse(
    await readFile(path.join(process.cwd(), 'package.json'), 'utf-8')
  );
  
  res.json({
    status: 'running',
    version: packageJson.version,
    environment: config.environment,
    timestamp: new Date().toISOString()
  });
});

app.listen(config.port, () => {
  console.log(`Server running on port ${config.port} in ${config.environment} mode`);
});

// Run with: npx tsx server.ts
// Watch mode: npx tsx watch server.ts
// With env vars: PORT=8080 NODE_ENV=production npx tsx server.ts

Use Cases

Pros & Cons

Pros

+Extremely fast transpilation using esbuild, significantly faster than ts-node which uses TypeScript's compiler
+Zero configuration needed for most projects - works immediately with standard TypeScript setups
+Built-in watch mode eliminates need for additional tools like nodemon
+Supports both CommonJS and ESM modules without special flags or configuration
+No intermediate .js files generated, keeping your project directory clean

Cons

−No type checking during execution - you need to run tsc separately for type validation
−Adds runtime overhead compared to pre-compiled JavaScript, though minimal with esbuild
−May not support some advanced TypeScript compiler options that esbuild doesn't implement
−Debugging can be less straightforward than with pre-compiled code due to transpilation layer
−Not a replacement for production builds where bundle size optimization and tree-shaking matter