@git.zone/tswatch

A development tool for watching and re-compiling TypeScript projects automatically upon detecting changes.

Install

To install @git.zone/tswatch, ensure that you have a Node.js environment set up with npm. You can install the package globally or locally within a project using npm:

npm install @git.zone/tswatch

This command will install the package and enable you to use the tswatch command in your terminal to watch TypeScript projects.

Usage

@git.zone/tswatch is a powerful tool designed to streamline your development workflow by monitoring your TypeScript files and automatically recompiling them when changes are detected. This utility is particularly helpful during the development phase of a TypeScript project, ensuring your project remains up-to-date, reflecting the latest changes seamlessly.

Getting Started with tswatch

To get started, we will explore setting up a basic watcher, integrating tswatch into a Node.js environment, utilizing advanced features, and handling multiple watchers.

Setting Up a Basic Watcher

Step 1: Basic Command-Line Interface Usage

After installing @git.zone/tswatch, you can start a watcher on your TypeScript project using its command-line interface (CLI). Here's how to initiate a watcher for different project types:

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

(async () => {
  await runCli();
})();

The CLI supports several commands to watch different project types such as element, npm, service, and website. Here's how to use them:

• NPM Projects: Watch a Node.js NPM project:

  tswatch npm
  

  This command will start a watcher for your node module projects. Whenever changes are detected, the specified npm scripts are executed.

• Element Projects: Watch an element-based architecture:

  tswatch element
  

  This command sets up a development server with live reloading and bundles TypeScript files to a dist_watch directory.

• Service Projects: Watch a service project:

  tswatch service
  

  Watches TypeScript files in a service pattern, restarting the service when changes are detected.

• Website Projects: Perfect for full website projects:

  tswatch website
  

  Similar to element projects but specifically designed for full websites, recompiling TypeScript files for web deployment scenarios.

Step 2: Integration into a Node.js Environment

You can integrate @git.zone/tswatch directly into a Node.js project for automatic file watching and recompiling:

import { TsWatch } from '@git.zone/tswatch';

const startWatch = async () => {
  // Initialize watch instance for a node project
  const watchInstance = new TsWatch('node');
  await watchInstance.start();
};

// Optionally, stop the watcher gracefully
const stopWatch = async (watchInstance: TsWatch) => {
  await watchInstance.stop();
};

This setup will establish a node environment watch, automatically recompiling files as changes occur.

Advanced Usage: Enhancing Workflow with tswatch

Starting a TypedServer with Watch Integration

For projects requiring a development server, integrate typedserver for handling HTTP server tasks:

import { TsWatch } from '@git.zone/tswatch';

const startTypedServer = async () => {
  const watchInstance = new TsWatch('element');
  await watchInstance.start();

  // Serve a local directory using a typedserver with CORS and compression
  const server = watchInstance.typedserver;
  if (server) {
    await server.start();
  }
};

This code watches for changes and serves the project locally, providing reload capabilities for smooth development.

Step 3: Custom Watchers

Beyond built-in commands, you can create custom watchers for detailed control over file monitoring and execution responses:

import { Watcher } from '@git.zone/tswatch';

const customWatcherSetup = async () => {
  const customWatcher = new Watcher({
    filePathToWatch: '/path/to/watch',
    commandToExecute: 'npm run custom-script',
  });

  // Start and stop the custom watcher as needed
  await customWatcher.start();
  await customWatcher.stop();
};

Define specific file paths and custom shell commands with the options provided by the Watcher class.

Step 4: Handling Multiple Watchers

To handle multiple directories or file sets, use the ObjectMap utility, efficiently managing multiple Watcher instances within the TsWatch framework:

import { TsWatch } from '@git.zone/tswatch';

const setupMultipleWatchers = async () => {
  const tsWatchInstance = new TsWatch('node');
  
  // View active watchers through instance mapping
  tsWatchInstance.watcherMap.forEach(watcher => {
    console.log(`Watcher listening on: ${watcher.toString()}`);
  });

  // Initiate all watchers
  await tsWatchInstance.start();
};

Incorporate this setup for efficiently managing complex projects with varied sources and parallel build tasks.

Handling Timeout and Cleanup

@git.zone/tswatch includes functions to manage process exits and timeout scenarios robustly:

import { Watcher } from '@git.zone/tswatch';

const watcherWithTimeout = () => {
  new Watcher({
    filePathToWatch: './src/',
    timeout: 10000, // 10 seconds timeout
    commandToExecute: 'echo "Task completed"',
  }).start();
};

The timeout option ensures processes don't run indefinitely, aiding development and potential automated testing scenarios.

Conclusion

By providing flexible configurations, a robust CLI, and deep integration capabilities, @git.zone/tswatch serves as a comprehensive solution for automating and optimizing your TypeScript development processes. Whether managing server-side environments or advanced web apps, using this tool will ensure your projects are always ready with the latest changes.

Explore the various features and tailor the tool to fit your unique project requirements, leading to faster and more efficient development workflows.

License and Legal Information

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

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 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, and any usage must be approved in writing by Task Venture Capital GmbH.

Company Information

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

For any legal inquiries or if you require 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.