@git.zone/tsrun

Run TypeScript files instantly — no build step, no config, no friction ⚡

Execute TypeScript programs on-the-fly with zero configuration. Whether you're writing quick scripts, prototyping ideas, or orchestrating complex multi-project workflows, tsrun gets out of your way and lets you focus on code.

Issue Reporting and Security

For reporting bugs, issues, or security vulnerabilities, please visit community.foss.global/. This is the central community hub for all issue reporting. Developers who sign and comply with our contribution agreement and go through identification can also get a code.foss.global/ account to submit Pull Requests directly.

Table of Contents

• What is tsrun?
• Installation
• CLI Usage
• Programmatic API
  • runPath()
  • runCli()
  • spawnPath()
• API Quick Reference
• Features
• Common Use Cases
• Migrating from 2.x
• Troubleshooting
• License and Legal Information

What is tsrun?

tsrun is a lightweight TypeScript execution tool that lets you run .ts files directly — just like running JavaScript with node, but for TypeScript. Under the hood, it uses tsx for lightning-fast transpilation, so there's no compilation step, no tsconfig fiddling, and no waiting around.

It also doubles as a programmatic library with full process control — spawn TypeScript processes, capture their output, set timeouts, and cancel them with AbortController. Perfect for build scripts, task runners, and orchestration tools.

Installation

Global (recommended for CLI usage):

pnpm install -g @git.zone/tsrun

As a project dependency (for programmatic API):

pnpm install @git.zone/tsrun

🚀 CLI Usage

Run any TypeScript file:

tsrun myScript.ts

Arguments pass through transparently, just like node:

tsrun deploy.ts production --verbose --dry-run

Your script gets the process.argv layout that node gives a script: the Node executable, the absolute script path, then your arguments. Read them with process.argv.slice(2); argument parsers such as @push.rocks/smartcli work unchanged:

// deploy.ts
// process.argv -> [process.execPath, '/path/to/deploy.ts', 'production', '--verbose', '--dry-run']
const [env] = process.argv.slice(2);     // "production"
const verbose = process.argv.includes('--verbose');
const dryRun = process.argv.includes('--dry-run');

console.log(`Deploying to ${env}...`);

💻 Programmatic API

tsrun exports three functions tailored for different execution needs.

runPath() — Simple Execution

Runs a TypeScript file and waits for it to complete. The simplest way to execute scripts programmatically.

import { runPath } from '@git.zone/tsrun';

// Run a script (path relative to cwd)
await runPath('./scripts/build.ts');

// Resolve path relative to the calling file
await runPath('./build.ts', import.meta.url);

// Run in a different working directory (spawns a child process)
await runPath('./build.ts', import.meta.url, { cwd: '/path/to/project' });

How it works:

• Without cwd — executes in-process using tsx's ESM loader (fast, zero overhead)
• With cwd — spawns an isolated child process with the given working directory; a relative path without import.meta.url resolves against that directory

Arguments: the script sees process.argv as [process.execPath, <absolute script path>, ...userArgs], where the script path is the path you passed, made absolute the way node does it, and the user arguments are the ones the calling process received. That is what makes a cli.ts.js development entry work:

// cli.ts.js, started as `node cli.ts.js plan --dry-run`
import * as tsrun from '@git.zone/tsrun';
await tsrun.runPath('./cli.child.js', import.meta.url);
// cli.child.ts reads process.argv.slice(2) -> ['plan', '--dry-run']

runCli() — CLI Mode

Runs with process.argv integration, as if the script were invoked from the command line. This is what the tsrun CLI binary uses internally. Without a path, runCli() takes the script from process.argv[2] and the user arguments after it, the way tsrun <script> ...args is invoked. With a path, the user arguments are the calling process's own (process.argv.slice(2)). Either way the script sees [process.execPath, <absolute script path>, ...userArgs].

import { runCli } from '@git.zone/tsrun';

// Forwards this process's user arguments to the script
await runCli('./script.ts');

// With custom working directory
await runCli('./script.ts', { cwd: '/path/to/project' });

spawnPath() — Advanced Process Control

Returns immediately with a process handle, giving you full control over stdio, timeouts, and cancellation.

import { spawnPath } from '@git.zone/tsrun';

const proc = spawnPath('./task.ts', import.meta.url, {
  timeout: 30000,                    // Kill after 30s
  cwd: '/path/to/project',
  env: { NODE_ENV: 'production' },   // Merged with process.env
  args: ['--verbose'],               // process.argv.slice(2) in the script
  stdio: 'pipe',                     // Default: capture stdout/stderr
});

// Stream stdout
proc.stdout?.on('data', (chunk) => {
  console.log(chunk.toString());
});

// Wait for exit
const exitCode = await proc.exitCode;

AbortController support:

const controller = new AbortController();
const proc = spawnPath('./task.ts', import.meta.url, {
  signal: controller.signal,
});

// Cancel from outside
setTimeout(() => controller.abort(), 5000);

try {
  await proc.exitCode;
} catch (err) {
  console.log('Process was cancelled');
}

Graceful termination:

const proc = spawnPath('./server.ts', import.meta.url);

// Sends SIGTERM, waits 5s, then SIGKILL if still running
await proc.terminate();

API Quick Reference

Function	Execution	Returns	Best For
runPath()	In-process (or child with cwd)	Promise<void>	Simple script execution, sequential workflows
runCli()	In-process (or child with cwd)	Promise<void>	CLI-like invocation with argv integration
spawnPath()	Always child process	ITsrunChildProcess	Output capture, timeouts, cancellation, parallel tasks

Decision guide:

• 🎯 Just run a script? → runPath()
• 🔧 Need argv pass-through? → runCli()
• 🎛️ Need stdout/stderr, timeout, or cancel? → spawnPath()
• ⚡ Parallel execution across projects? → runPath() with cwd or spawnPath()

ITsrunChildProcess Interface

The object returned by spawnPath():

Property / Method	Type	Description
childProcess	ChildProcess	Direct access to Node's ChildProcess
stdout	Readable | null	Stdout stream (null if stdio is 'inherit')
stderr	Readable | null	Stderr stream (null if stdio is 'inherit')
exitCode	Promise<number>	Resolves with exit code when process ends
kill(signal?)	(signal?: NodeJS.Signals) => boolean	Send a signal to the process
terminate()	() => Promise<void>	Graceful shutdown: SIGTERM → 5s → SIGKILL

ISpawnOptions

Options for spawnPath():

Option	Type	Default	Description
cwd	string	process.cwd()	Working directory for the child process
env	Record<string, string>	{}	Extra env vars (merged with process.env)
args	string[]	[]	CLI arguments, read by the script as process.argv.slice(2)
stdio	'pipe' | 'inherit'	'pipe'	Stdio configuration
timeout	number	—	Auto-kill after N milliseconds
signal	AbortSignal	—	External cancellation support

Features

✨ Zero Configuration — Point and shoot. No tsconfig required, no build step, no setup.

⚡ Lightning Fast — Powered by tsx (esbuild under the hood) for near-instant TypeScript execution.

🔄 Transparent Arguments — CLI args reach your scripts in Node's standard process.argv layout.

📦 Dual Interface — Use as a CLI tool or import as a library with full TypeScript types.

🔀 Custom Working Directory — Run scripts in isolated child processes with different cwds.

🎛️ Full Process Control — spawnPath() gives you streams, timeouts, cancellation, and graceful shutdown.

🛡️ Signal Forwarding — SIGINT/SIGTERM/SIGHUP are properly forwarded to child processes.

Common Use Cases

Quick Scripts & Prototyping

# Write TypeScript, run it immediately
tsrun seed-database.ts
tsrun generate-report.ts --format csv
tsrun cleanup-temp-files.ts

Sequential Build Pipeline

import { runPath } from '@git.zone/tsrun';

const steps = ['./lint.ts', './test.ts', './build.ts', './deploy.ts'];

for (const step of steps) {
  console.log(`▶ Running ${step}...`);
  await runPath(step, import.meta.url);
  console.log(`✓ Done`);
}

Parallel Multi-Project Builds

import { runPath } from '@git.zone/tsrun';

await Promise.all([
  runPath('./build.ts', undefined, { cwd: '/workspace/frontend' }),
  runPath('./build.ts', undefined, { cwd: '/workspace/backend' }),
  runPath('./build.ts', undefined, { cwd: '/workspace/shared' }),
]);

Long-Running Tasks with Monitoring

import { spawnPath } from '@git.zone/tsrun';

const proc = spawnPath('./data-migration.ts', import.meta.url, {
  timeout: 300000,  // 5 minute max
  env: { LOG_LEVEL: 'verbose' },
});

let lines = 0;
proc.stdout?.on('data', (chunk) => {
  lines++;
  if (lines % 100 === 0) console.log(`Processed ${lines} lines...`);
});

try {
  await proc.exitCode;
  console.log('Migration completed!');
} catch (err) {
  console.error('Migration failed:', err.message);
  process.exit(1);
}

Migrating from 2.x

tsrun 2.x cut process.argv down to the user arguments, so process.argv[0] was the first user argument and process.argv.slice(2) lost the first two. tsrun now gives every script Node's standard layout:

• Read user arguments from process.argv.slice(2) instead of process.argv or process.argv[0].
• Remove code that detects the old layout, such as checks whether process.argv[0] is the Node executable.

Troubleshooting

"Cannot find module" errors

Use import.meta.url for path resolution relative to the calling file:

// ❌ Relative to cwd — fragile
await runPath('./script.ts');

// ✅ Relative to current file — reliable
await runPath('./script.ts', import.meta.url);

Process hangs

When using spawnPath(), always await the exitCode promise:

const proc = spawnPath('./script.ts', import.meta.url);
await proc.exitCode; // Don't forget this!

Timeout only works with spawnPath()

runPath() executes in-process and doesn't support timeouts. Use spawnPath() instead:

const proc = spawnPath('./script.ts', import.meta.url, { timeout: 5000 });
await proc.exitCode;

tsrun: command not found

Install globally or use npx:

pnpm install -g @git.zone/tsrun
# or
npx @git.zone/tsrun myScript.ts

License and Legal Information

This repository contains open-source code licensed under the MIT License. A copy of the license can be found in the license file.

Please note: The MIT License does not grant permission to use the trade names, trademarks, service marks, or product names of the project, except as required for reasonable and customary use in describing the origin of the work and reproducing the content of the NOTICE file.

Trademarks

This project is owned and maintained by Task Venture Capital GmbH. The names and logos associated with Task Venture Capital GmbH and any related products or services are trademarks of Task Venture Capital GmbH or third parties, and are not included within the scope of the MIT license granted herein.

Use of these trademarks must comply with Task Venture Capital GmbH's Trademark Guidelines or the guidelines of the respective third-party owners, and any usage must be approved in writing. Third-party trademarks used herein are the property of their respective owners and used only in a descriptive manner, e.g. for an implementation of an API or similar.

Company Information

Task Venture Capital GmbH
Registered at District Court Bremen HRB 35230 HB, Germany

For any legal inquiries or further information, please contact us via email at hello@task.vc.

By using this repository, you acknowledge that you have read this section, agree to comply with its terms, and understand that the licensing of the code does not imply endorsement by Task Venture Capital GmbH of any derivative works.