tswatch/readme.md

# @git.zone/tswatch

A powerful, config-driven TypeScript file watcher that automatically recompiles and executes your project when files change. Built for modern TypeScript development with zero-config presets, smart bundling, a built-in dev server with live reload, and deep customization options.

## Issue Reporting and Security

For reporting bugs, issues, or security vulnerabilities, please visit [community.foss.global/](https://community.foss.global/). This is the central community hub for all issue reporting. Developers who sign and comply with our contribution agreement and go through identification can also get a [code.foss.global/](https://code.foss.global/) account to submit Pull Requests directly.

## ✨ Features

- 🔄 **Config-driven architecture** — Define watchers, bundles, and dev server in `.smartconfig.json`
- ⚡ **Zero-config presets** — Get started instantly with `npm`, `element`, `service`, `website`, and `test` presets
- 🧙 **Interactive wizard** — Run `tswatch init` to generate configuration interactively
- 🌐 **Built-in dev server** — Live reload, CORS, compression, SPA fallback out of the box
- 📦 **Smart bundling** — TypeScript, HTML, and assets with esbuild/rolldown/rspack integration
- 🔁 **Debounced execution** — Configurable debounce prevents command spam during rapid file saves
- 🛑 **Process management** — Automatic restart or queue mode for long-running commands
- 🎯 **Glob patterns** — Watch any files with flexible pattern matching
- 🧹 **Graceful shutdown** — Signal-aware process lifecycle with tree-kill for clean teardowns

## 📦 Installation

```bash
# Global installation (recommended for CLI usage)
pnpm install -g @git.zone/tswatch

# As a dev dependency
pnpm install --save-dev @git.zone/tswatch
```

## 🚀 Quick Start

### Using the Wizard

```bash
# Run the interactive wizard to create your configuration
tswatch init
```

The wizard guides you through creating a `.smartconfig.json` configuration with your chosen preset or custom watchers.

### Using Presets

If you already have a configuration, just run:

```bash
tswatch
```

This reads your config from `.smartconfig.json` under the `@git.zone/tswatch` key and starts watching.

## ⚙️ Configuration

tswatch uses `.smartconfig.json` for configuration. Add your config under the `@git.zone/tswatch` key:

```json
{
  "@git.zone/tswatch": {
    "preset": "npm"
  }
}
```

### Available Presets

| Preset | Description |
|--------|-------------|
| `npm` | Watch `ts/` and `test/`, run `npm test` on changes |
| `test` | Watch `ts/` and `test/`, run `npm run test2` on changes |
| `service` | Watch `ts/`, restart `npm run startTs` (ideal for backend services) |
| `element` | Dev server on port 3002 + bundling for web components |
| `website` | Full-stack: backend restart + frontend bundling + asset processing |

### Full Configuration Schema

```json
{
  "@git.zone/tswatch": {
    "preset": "element",

    "server": {
      "enabled": true,
      "port": 3002,
      "serveDir": "./dist_watch/",
      "liveReload": true,
      "domain": "localhost"
    },

    "bundles": [
      {
        "name": "main-bundle",
        "from": "./ts_web/index.ts",
        "to": "./dist_watch/bundle.js",
        "watchPatterns": ["./ts_web/**/*"],
        "triggerReload": true,
        "bundler": "esbuild",
        "production": false
      },
      {
        "name": "html",
        "from": "./html/index.html",
        "to": "./dist_watch/index.html",
        "watchPatterns": ["./html/**/*"],
        "triggerReload": true
      }
    ],

    "watchers": [
      {
        "name": "backend-build",
        "watch": "./ts/**/*",
        "command": "npm run build",
        "restart": false,
        "debounce": 300,
        "runOnStart": true
      },
      {
        "name": "tests",
        "watch": ["./ts/**/*", "./test/**/*"],
        "command": "npm test",
        "restart": true,
        "debounce": 300,
        "runOnStart": true
      }
    ]
  }
}
```

### Configuration Options

#### `ITswatchConfig`

| Option | Type | Description |
|--------|------|-------------|
| `preset` | `string` | Use a preset: `npm`, `test`, `service`, `element`, `website` |
| `watchers` | `IWatcherConfig[]` | Array of watcher configurations |
| `server` | `IServerConfig` | Development server configuration |
| `bundles` | `IBundleConfig[]` | Bundle configurations |

> **Tip:** When a preset is specified alongside explicit `watchers`, `bundles`, or `server`, your explicit values take precedence over the preset defaults.

#### `IWatcherConfig`

| Option | Type | Default | Description |
|--------|------|---------|-------------|
| `name` | `string` | *required* | Name for logging purposes |
| `watch` | `string \| string[]` | *required* | Glob pattern(s) to watch |
| `command` | `string` | — | Shell command to execute on changes |
| `restart` | `boolean` | `true` | Kill previous process before restarting |
| `debounce` | `number` | `300` | Debounce delay in milliseconds |
| `runOnStart` | `boolean` | `true` | Run the command immediately on start |

#### `IServerConfig`

| Option | Type | Default | Description |
|--------|------|---------|-------------|
| `enabled` | `boolean` | *required* | Whether the server is enabled |
| `port` | `number` | `3002` | Server port |
| `serveDir` | `string` | `./dist_watch/` | Directory to serve |
| `liveReload` | `boolean` | `true` | Inject live reload script |
| `domain` | `string` | `localhost` | Domain name for the dev server |

#### `IBundleConfig`

| Option | Type | Default | Description |
|--------|------|---------|-------------|
| `name` | `string` | — | Name for logging purposes |
| `from` | `string` | *required* | Entry point file |
| `to` | `string` | *required* | Output file |
| `watchPatterns` | `string[]` | — | Additional patterns to watch |
| `triggerReload` | `boolean` | `true` | Trigger server reload after bundling |
| `outputMode` | `'bundle' \| 'base64ts'` | `'bundle'` | Output mode for the bundle |
| `bundler` | `'esbuild' \| 'rolldown' \| 'rspack'` | `'esbuild'` | Bundler engine to use |
| `production` | `boolean` | `false` | Enable minification for production builds |
| `includeFiles` | `(string \| { from, to })[]` | — | Additional files to include alongside the bundle |
| `maxLineLength` | `number` | — | Max chars per line for `base64ts` output mode |

## 🛠️ CLI Commands

### `tswatch`

Runs with configuration from `.smartconfig.json`. If no config exists, launches the interactive wizard automatically.

```bash
tswatch
```

### `tswatch init`

Force-run the configuration wizard (creates or overwrites existing config).

```bash
tswatch init
```

## 💻 Programmatic API

### Basic Usage with Inline Config

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

const watcher = new TsWatch({
  watchers: [
    {
      name: 'my-watcher',
      watch: './src/**/*',
      command: 'npm run build',
      restart: true,
      debounce: 300,
      runOnStart: true,
    },
  ],
});

await watcher.start();

// Later: stop watching
await watcher.stop();
```

### Load from Config File

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

// Load configuration from .smartconfig.json
const watcher = TsWatch.fromConfig();

if (watcher) {
  await watcher.start();
}
```

### Using ConfigHandler

```typescript
import { ConfigHandler } from '@git.zone/tswatch';

const configHandler = new ConfigHandler();

// Check if config exists
if (configHandler.hasConfig()) {
  const config = configHandler.loadConfig();
  console.log(config);
}

// Get available presets
const presets = configHandler.getPresetNames();
// => ['npm', 'test', 'service', 'element', 'website']

// Get a specific preset
const npmPreset = configHandler.getPreset('npm');
```

### Using Watcher Directly

For more granular control, use the `Watcher` class:

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

// Create from config object
const watcher = Watcher.fromConfig({
  name: 'my-watcher',
  watch: ['./src/**/*', './lib/**/*'],
  command: 'npm run compile',
  restart: true,
});

await watcher.start();
```

### Using Function Callbacks

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

const watcher = new Watcher({
  name: 'custom-handler',
  filePathToWatch: './src/**/*',
  functionToCall: async () => {
    console.log('Files changed! Running custom logic...');
    // Your custom build/test/deploy logic here
  },
  debounce: 500,
  runOnStart: true,
});

await watcher.start();
```

## 📁 Project Structure Examples

### NPM Package / Node.js Library

```
project/
├── ts/                 # TypeScript source files
├── test/               # Test files
├── package.json        # With "test" script
└── .smartconfig.json   # tswatch config
```

```json
{
  "@git.zone/tswatch": {
    "preset": "npm"
  }
}
```

### Backend Service

```
project/
├── ts/                 # TypeScript source files
├── package.json        # With "startTs" script
└── .smartconfig.json
```

```json
{
  "@git.zone/tswatch": {
    "preset": "service"
  }
}
```

### Web Component / Element

```
project/
├── ts/                 # Backend TypeScript (optional)
├── ts_web/             # Frontend TypeScript
├── html/
│   ├── index.ts        # Web entry point
│   └── index.html
├── dist_watch/         # Output (auto-created)
└── .smartconfig.json
```

```json
{
  "@git.zone/tswatch": {
    "preset": "element"
  }
}
```

Access your project at `http://localhost:3002`

### Full-Stack Website

```
project/
├── ts/                 # Backend TypeScript
├── ts_web/             # Frontend TypeScript
│   └── index.ts
├── html/
│   └── index.html
├── assets/             # Static assets
├── dist_serve/         # Output
└── .smartconfig.json
```

```json
{
  "@git.zone/tswatch": {
    "preset": "website"
  }
}
```

## 🌐 Development Server

The built-in development server (powered by `@api.global/typedserver`'s `UtilityWebsiteServer`) is enabled in `element` and `website` presets:

- 🔄 **Live Reload** — WebSocket-based instant browser refresh on changes (via service worker + devtools injection)
- 🚫 **No Caching** — Prevents browser caching during development (`Cache-Control: no-store, no-cache` headers)
- 🌍 **CORS** — Cross-origin requests enabled
- 🗜️ **Compression** — Brotli + gzip compression for faster loading
- 📱 **SPA Fallback** — Single-page application routing support
- 🔒 **Security Headers** — Cross-origin isolation (`COOP`, `COEP`)
- 📦 **PWA Manifest** — Auto-generated Progressive Web App manifest
- ⚡ **Service Worker** — Built-in service worker version info for cache busting

Default configuration:

| Setting | Default |
|---------|---------|
| Port | `3002` |
| Serve Directory | `./dist_watch/` |
| Live Reload | Enabled |
| Domain | `localhost` |

## 🔧 Configuration Tips

1. **Use presets for common workflows** — They're battle-tested and cover most use cases
2. **Customize with explicit config** — Override preset defaults by adding explicit `watchers`, `bundles`, or `server` config
3. **Debounce wisely** — Default 300ms works well; increase for slower builds
4. **Use `restart: false`** for one-shot commands (like builds) and `restart: true` for long-running processes (like servers)
5. **Multiple bundlers** — Choose between `esbuild` (fastest), `rolldown` (smallest output), or `rspack` (webpack-compatible) per bundle

## License and Legal Information

This repository contains open-source code licensed under the MIT License. A copy of the license can be found in the [license](./license) file.

**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 or third parties, 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 or the guidelines of the respective third-party owners, and any usage must be approved in writing. Third-party trademarks used herein are the property of their respective owners and used only in a descriptive manner, e.g. for an implementation of an API or similar.

### Company Information

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

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