{"id":18872,"library":"tsc-watch","title":"tsc-watch","description":"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.","status":"active","version":"7.2.0","language":"javascript","source_language":"en","source_url":"ssh://git@github.com/gilamran/tsc-watch","tags":["javascript","TypeScript","typescript"],"install":[{"cmd":"npm install tsc-watch","lang":"bash","label":"npm"},{"cmd":"yarn add tsc-watch","lang":"bash","label":"yarn"},{"cmd":"pnpm add tsc-watch","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"tsc-watch runs the TypeScript compiler (tsc) under the hood and requires it as a peer dependency.","package":"typescript","optional":false},{"reason":"Used internally to spawn child processes with proper cross-platform signal handling.","package":"cross-spawn","optional":false},{"reason":"Used to kill child process trees on exit to clean up spawned commands.","package":"ps-tree","optional":false},{"reason":"Parses command strings into arrays for safe spawning.","package":"string-argv","optional":false}],"imports":[{"note":"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.","wrong":"tsc --watch --onSuccess \"node dist/index.js\"","symbol":"tsc-watch (CLI)","correct":"npx tsc-watch --onSuccess \"node dist/index.js\""},{"note":"The programmatic API is exported as a default class from 'tsc-watch/client'. This module is ESM-only since v6.","wrong":"const TscWatchClient = require('tsc-watch').default","symbol":"default (programmatic API)","correct":"import TscWatchClient from 'tsc-watch/client'"},{"note":"For TypeScript users, the type is exported only from 'tsc-watch/client'. Importing from the main package or as named will fail.","wrong":"import { TscWatchClient } from 'tsc-watch'","symbol":"TscWatchClient (type import)","correct":"import type TscWatchClient from 'tsc-watch/client'"}],"quickstart":{"code":"npx tsc-watch --onSuccess \"node dist/index.js\" --noClear","lang":"typescript","description":"Runs TypeScript compiler in watch mode and executes 'node dist/index.js' on every successful compilation, without clearing the terminal."},"warnings":[{"fix":"Use import or dynamic import in ES modules. For older Node versions, stick with v5.x.","message":"Version 6.0.0 dropped CommonJS support; programmatic API is ESM-only. Requiring 'tsc-watch' with require() will fail.","severity":"breaking","affected_versions":">=6.0.0"},{"fix":"Use --compileCommand instead.","message":"The --compiler option is deprecated and will be removed in a future version.","severity":"deprecated","affected_versions":">=6.0.0"},{"fix":"Ensure your command handles SIGTERM properly or use a process manager like pm2.","message":"onSuccess command is killed with SIGTERM on process exit; if your command spawns child processes, they may not be cleaned up.","severity":"gotcha","affected_versions":"all"},{"fix":"Use --onSuccess for one-time actions after compilation, or add debouncing logic in your command.","message":"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.","severity":"gotcha","affected_versions":"all"},{"fix":"Ensure typescript is installed and compatible. The peer dependency is '*' so any version should work, but test with your project.","message":"tsc-watch requires a peer dependency of TypeScript; using a mismatched TypeScript version may cause unexpected behavior.","severity":"gotcha","affected_versions":"all"}],"env_vars":null,"last_verified":"2026-04-25T00:00:00.000Z","next_check":"2026-07-24T00:00:00.000Z","problems":[{"fix":"Change import to import TscWatchClient from 'tsc-watch/client' (for ESM) or use dynamic import.","cause":"Attempting to require or import the programmatic API from the main package instead of 'tsc-watch/client'.","error":"Error: Cannot find module 'tsc-watch/client'"},{"fix":"Run 'npm install --save-dev tsc-watch' then use npx tsc-watch or add a script in package.json.","cause":"tsc-watch is not installed globally or not in node_modules/.bin.","error":"tsc-watch: command not found"},{"fix":"Use import TscWatchClient from 'tsc-watch/client' and then new TscWatchClient(...).","cause":"Using the default import incorrectly, e.g., importing as named or using require incorrectly.","error":"TypeError: tscWatchClient is not a constructor"}],"ecosystem":"npm","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null}