tsc-watch

What is tsc-watch?

The tsc-watch npm package is a utility that allows you to run the TypeScript compiler (tsc) in watch mode and execute custom scripts when certain events occur, such as when compilation starts, succeeds, or fails. This is particularly useful for automating tasks during development, such as running tests or restarting a server.

What are tsc-watch's main functionalities?

Run TypeScript compiler in watch mode

This feature allows you to run the TypeScript compiler in watch mode, which means it will automatically recompile your TypeScript files whenever they change. The `--onSuccess` flag specifies a command to run whenever the compilation succeeds. In this example, it runs a Node.js script located at `./dist/index.js`.

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

Run custom scripts on compilation failure

This feature allows you to specify a command to run whenever the TypeScript compilation fails. In this example, it simply echoes 'Compilation Failed!' to the console.

tsc-watch --onFailure "echo Compilation Failed!"

Run custom scripts on compilation start

This feature allows you to specify a command to run whenever the TypeScript compilation starts. In this example, it echoes 'Compilation Started!' to the console.

tsc-watch --onCompilationStarted "echo Compilation Started!"

Other packages similar to tsc-watch

nodemon

Nodemon is a utility that monitors for any changes in your source and automatically restarts your server. It is language-agnostic and can be used with any executable, not just TypeScript. Unlike tsc-watch, nodemon does not handle TypeScript compilation by itself; you would need to use it in conjunction with the TypeScript compiler.

ts-node-dev

ts-node-dev is a development tool that combines ts-node and nodemon. It watches for changes in TypeScript files and restarts the Node.js process automatically. Unlike tsc-watch, ts-node-dev directly executes TypeScript files without needing a separate compilation step.

webpack

Webpack is a module bundler that can be configured to watch for changes in your files and recompile your project. With the appropriate loaders, it can handle TypeScript files. Webpack is more complex and powerful than tsc-watch, offering features like code splitting and hot module replacement.

README

The TypeScript compiler with --onSuccess argument

tsc-watch starts a TypeScript compiler with --watch parameter, there are 5 new arguments.

• --onSuccess COMMAND - The COMMAND will be executed on every successful TypeScript compilation.
• --onFirstSuccess COMMAND - The COMMAND will be executed only one time, on the first successful TypeScript compilation.
• --onFailure COMMAND - The COMMAND will be executed on failed TypeScript compilation.
• --noColors - tsc-watch colors the output with green on success, and in red on failiure. Add this argument to prevent that.
• --noClear - In watch mode the tsc compiler clears the screen before reporting, using this option will prevent that.
• --compiler PATH - The PATH will be used instead of typescript compiler. Defaults typescript/bin/tsc.

Install

npm install tsc-watch --save-dev

Usage

From Command-Line

## Compiles the server.ts into the dist folder and run it
tsc-watch server.ts --outDir ./dist --onSuccess "node ./dist/server.js" --onFailure "echo Beep! Compilation Failed" --compiler typescript/bin/tsc

## With tsconfig.json
tsc-watch --onSuccess "node ./dist/server.js" --onFailure "echo Beep! Compilation Failed" --compiler typescript/bin/tsc

From Code

The client is implemented as an instance of Node.JS's EventEmitter, with the following events:

• first_success - Emitted upon first successful compilation.
• subsequent_success - Emitted upon every subsequent successful compilation.
• compile_errors - Emitted upon every failing compilation.

Once subscribed to the relevant events, start the client by running watch.start()

To kill the client, run watch.kill()

Example usage:

const watch = require('tsc-watch/client');

watch.on('first_success', () => {
  console.log('First success!');
});

watch.on('subsequent_success', () => {
  // Your code goes here...
});

watch.on('compile_errors', () => {
  // Your code goes here...
});

watch.start();

try {
  // do something...
} catch (e) {
  watch.kill(); // Fatal error, kill the compiler instance.
}

Notes:

• The (onSuccess) COMMAND will not run if the compilation failed.
• Any child process (COMMAND) will be terminated before creating a new one.
• tsc-watch is using the currently installed TypeScript compiler.
• tsc-watch is not changing the compiler, just adds the new arguments, compilation is the same, and all other arguments are the same.
• tsc-watch was created to allow an easy dev process with TypeScript. Commonly used to restart a node server.

Changelog

v1.1.32 - 27/11/2018

• Added --noClear command to prevent clearing the screen after each compilation