tsc-watch

7.2.0 verified Sat Apr 25 auth: no javascript

tsc-watch is a utility that wraps the TypeScript compiler's --watch mode and adds lifecycle hooks to execute commands on compilation events such as success, failure, or first success. It is commonly used as a drop-in replacement for nodemon in TypeScript projects to restart a Node.js server after successful recompilations. The current stable version is 7.2.0, with a release cadence of several minor versions per year. Key differentiators include built-in support for debounced file emission events, signal handling, and the ability to run arbitrary commands without needing an additional process manager. Unlike plain tsc --watch, tsc-watch provides fine-grained control over development workflows and integrates seamlessly with TypeScript's existing compiler options.

Common errors

error Error: Cannot find module 'tsc-watch/client' ↓

cause Attempting to require or import the programmatic API from the main package instead of 'tsc-watch/client'.

fix

Change import to import TscWatchClient from 'tsc-watch/client' (for ESM) or use dynamic import.

error tsc-watch: command not found ↓

cause tsc-watch is not installed globally or not in node_modules/.bin.

fix

Run 'npm install --save-dev tsc-watch' then use npx tsc-watch or add a script in package.json.

error TypeError: tscWatchClient is not a constructor ↓

cause Using the default import incorrectly, e.g., importing as named or using require incorrectly.

fix

Use import TscWatchClient from 'tsc-watch/client' and then new TscWatchClient(...).

Warnings

breaking Version 6.0.0 dropped CommonJS support; programmatic API is ESM-only. Requiring 'tsc-watch' with require() will fail. ↓

fix Use import or dynamic import in ES modules. For older Node versions, stick with v5.x.

deprecated The --compiler option is deprecated and will be removed in a future version. ↓

fix Use --compileCommand instead.

gotcha onSuccess command is killed with SIGTERM on process exit; if your command spawns child processes, they may not be cleaned up. ↓

fix Ensure your command handles SIGTERM properly or use a process manager like pm2.

gotcha The --onEmit event fires for each emitted file, so a single compilation may trigger multiple commands. This can cause race conditions if commands are not idempotent. ↓

fix Use --onSuccess for one-time actions after compilation, or add debouncing logic in your command.

gotcha tsc-watch requires a peer dependency of TypeScript; using a mismatched TypeScript version may cause unexpected behavior. ↓

fix Ensure typescript is installed and compatible. The peer dependency is '*' so any version should work, but test with your project.

Install

npm install tsc-watch

yarn add tsc-watch

pnpm add tsc-watch

Imports

tsc-watch (CLI)
wrong
```
tsc --watch --onSuccess "node dist/index.js"
```
correct
```
npx tsc-watch --onSuccess "node dist/index.js"
```
tsc-watch is a CLI tool, not a library. It is invoked via npx or installed globally. The wrong pattern shows expecting tsc to support --onSuccess.
default (programmatic API)
wrong
```
const TscWatchClient = require('tsc-watch').default
```
correct
```
import TscWatchClient from 'tsc-watch/client'
```
The programmatic API is exported as a default class from 'tsc-watch/client'. This module is ESM-only since v6.
TscWatchClient (type import)
wrong
```
import { TscWatchClient } from 'tsc-watch'
```
correct
```
import type TscWatchClient from 'tsc-watch/client'
```
For TypeScript users, the type is exported only from 'tsc-watch/client'. Importing from the main package or as named will fail.

Quickstart

Runs TypeScript compiler in watch mode and executes 'node dist/index.js' on every successful compilation, without clearing the terminal.

npx tsc-watch --onSuccess "node dist/index.js" --noClear