ts-watch

1.0.8 verified Fri May 01 auth: no javascript

ts-watch is a wrapper around the TypeScript compiler (tsc) that adds a --onSuccess COMMAND argument to run a command after every successful compilation. It is a fork of tsc-watch with fixes for macOS compatibility. Version 6.2.0 is the latest stable release, with periodic updates. Unlike raw tsc --watch, it provides lifecycle hooks (onSuccess, onFirstSuccess, onFailure, onCompilationComplete) to restart servers or run tests. It uses the locally installed TypeScript compiler and does not modify compilation behavior.

Common errors

error sh: ts-watch: command not found ↓

cause ts-watch is not installed or not in PATH when running directly.

fix

Use npx ts-watch or add a script in package.json: "scripts": { "watch": "ts-watch ..." } then run npm run watch.

error error TS6369: Option '--build' must be the first command line argument ↓

cause ts-watch passes --watch to tsc, which conflicts with --build. Fixed in v6.0.5.

fix

Upgrade to ts-watch@>=6.0.5: npm install --save-dev ts-watch@latest

error TypeError: Cannot read property 'onSuccess' of undefined ↓

cause Using ts-watch programmatically via require('ts-watch') which does not export anything.

fix

Use ts-watch as a CLI tool, not a library. Remove require('ts-watch') and use the command line.

Warnings

breaking ts-watch is a fork of tsc-watch. Migration: replace 'tsc-watch' with 'ts-watch' in package.json scripts and update imports. ↓

fix If previously using tsc-watch, uninstall it: npm uninstall tsc-watch and install ts-watch: npm install --save-dev ts-watch. Then change all references in scripts from 'tsc-watch' to 'ts-watch'.

gotcha ts-watch requires TypeScript to be installed. If using global tsc, the local project must also have TypeScript as a devDependency. ↓

fix Ensure TypeScript is installed: npm install --save-dev typescript

gotcha The --onSuccess command is terminated before a new compilation starts. Long-running processes (e.g., servers) may not restart properly if they don't handle SIGTERM. ↓

fix Ensure your server process can be gracefully terminated. Use a process manager like 'wait-on' or 'concurrently' if needed.

deprecated Very old versions (1.x) may not support --onFirstSuccess or --onFailure. Upgrade to v6+. ↓

fix Upgrade to latest: npm install --save-dev ts-watch@latest

Install

npm install ts-watch

yarn add ts-watch

pnpm add ts-watch

Imports

ts-watch (CLI)
wrong
```
require('ts-watch')
```
correct
```
npx ts-watch
```
ts-watch is a CLI tool, not a library. Use it via npm scripts or npx. There is no programmatic API.
run onSuccess
```
ts-watch --onSuccess "node dist/index.js"
```
The --onSuccess command runs after a successful compilation. It is terminated before the next run.
run onFirstSuccess
```
ts-watch --onFirstSuccess "echo first success"
```
Available since v3.0. Runs only on the first successful compilation after watch starts.
run onFailure
```
ts-watch --onFailure "echo compilation failed"
```
Available since v4.0. Runs when compilation fails.

Quickstart

Installs ts-watch, sets up a basic TypeScript project with a simple file, and demonstrates running ts-watch to watch for changes and execute the output on success.

npm install --save-dev ts-watch typescript
mkdir src
cat > src/index.ts << 'EOF'
const greeting: string = "Hello, world!";
console.log(greeting);
EOF
cat > tsconfig.json << 'EOF'
{
  "compilerOptions": {
    "outDir": "./dist",
    "strict": true
  },
  "include": ["src"]
}
EOF
# Run ts-watch with onSuccess to execute the compiled file
npx ts-watch --project tsconfig.json --onSuccess "node dist/index.js"