@git.zone/tswatch

watch typescript projects during development

readme.md for @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/. 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/ account to submit Pull Requests directly.

โœจ Features

๐Ÿ“ฆ Installation

# 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

# 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:

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:

{
  "@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

{
  "@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.

tswatch

tswatch init

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

tswatch init

๐Ÿ’ป Programmatic API

Basic Usage with Inline Config

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

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

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

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

Using ConfigHandler

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:

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

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
{
  "@git.zone/tswatch": {
    "preset": "npm"
  }
}

Backend Service

project/
โ”œโ”€โ”€ ts/                 # TypeScript source files
โ”œโ”€โ”€ package.json        # With "startTs" script
โ””โ”€โ”€ .smartconfig.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
{
  "@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
{
  "@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:

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

This repository contains open-source code licensed under the MIT License. A copy of the license can be found in the 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

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.

changelog.md for @git.zone/tswatch

2026-03-24 - 3.3.2 - fix(config)

migrate project metadata and documentation to .smartconfig.json

2026-03-24 - 3.3.1 - fix(config)

switch configuration loading and saving from npmextra.json to smartconfig.json

2026-03-10 - 3.3.0 - feat(server)

use UtilityWebsiteServer for dev server, add domain option, update docs, and bump dependencies

2026-03-03 - 3.2.1 - fix(watcher)

ensure child processes are killed and awaited during shutdown; improve cleanup handlers; bump smartshell dependency to ^3.3.2

2026-02-24 - 3.2.0 - feat(bundle)

add configurable bundle output modes and bundler options (support base64ts, production builds, includeFiles, maxLineLength) and route non-default outputs to a CustomBundleHandler

2026-02-05 - 3.1.0 - feat(dev-server)

add no-cache headers to built-in development server; update docs and bump dependencies

2026-01-24 - 3.0.1 - fix(deps)

downgrade @push.rocks/smartinteract to ^2.0.16

2026-01-24 - 3.0.0 - BREAKING CHANGE(tswatch)

refactor tswatch to a config-driven design (load config from npmextra.json) and add interactive init wizard; change TsWatch public API and enhance Watcher behavior

2025-12-11 - 2.3.13 - fix(@push.rocks/smartwatch)

Update @push.rocks/smartwatch dependency to ^6.3.0

2025-12-11 - 2.3.12 - fix(smartwatch)

Bump @push.rocks/smartwatch from ^6.2.4 to ^6.2.5

2025-12-11 - 2.3.11 - fix(typedserver)

Add cross-origin security headers to element mode dev server

2025-12-11 - 2.3.10 - fix(dependencies)

Bump dependency versions: @types/node to ^25.0.0 and @push.rocks/smartwatch to ^6.2.4

2025-12-11 - 2.3.9 - fix(smartwatch)

Bump @push.rocks/smartwatch dependency to ^6.2.3

2025-12-11 - 2.3.8 - fix(@push.rocks/smartwatch)

Bump @push.rocks/smartwatch dependency to ^6.2.2

2025-12-10 - 2.3.7 - fix(smartwatch)

Bump @push.rocks/smartwatch dependency to ^6.2.1

2025-12-10 - 2.3.6 - fix(dependencies)

Bump @types/node to ^24.10.2 and @push.rocks/smartwatch to ^6.2.0

2025-12-08 - 2.3.5 - fix(dependencies)

Update @push.rocks/smartwatch dependency to ^6.1.1

2025-12-08 - 2.3.4 - fix(dependencies.@push.rocks/smartwatch)

Bump @push.rocks/smartwatch dependency to ^6.1.0

2025-12-08 - 2.3.3 - fix(dependencies)

Bump dependencies: @api.global/typedserver to ^7.11.1 and @push.rocks/smartwatch to ^6.0.0

2025-12-08 - 2.3.2 - fix(smartwatch)

Bump @push.rocks/smartwatch dependency to ^5.1.0

2025-12-08 - 2.3.1 - fix(element)

Enable SPA fallback in element dev server

2025-12-08 - 2.3.0 - feat(typedserver)

Enable compression for element development server and update @api.global/typedserver dependency

2025-12-08 - 2.2.5 - fix(typedserver)

Update @api.global/typedserver to ^7.10.2 and remove deprecated compression options from TypedServer initialization

2025-12-04 - 2.2.4 - fix(dependencies)

Bump dependency versions: @api.global/typedserver, @git.zone/tsbundle, @push.rocks/smartfs, @push.rocks/taskbuffer

2025-12-04 - 2.2.3 - fix(tswatch.classes.watcher)

Convert directory watch paths to glob patterns for smartwatch compatibility

2025-12-01 - 2.2.2 - fix(core)

Replace smartchok/smartfile with smartwatch/smartfs, update watcher and plugins, and bump dependencies

2025-07-29 - 2.2.1 - fix(exports)

Fix package.json exports field syntax

2025-07-29 - 2.2.0 - feat(exports)

Modernize package exports and expose watcher class

2025-07-29 - 2.1.3 - fix(documentation)

Update and align documentation with internal CLI and project structure

2025-06-26 - 2.1.2 - fix(dependencies)

Update @push.rocks/smartchok dependency to ^1.1.1

2025-06-26 - 2.1.1 - fix(deps)

Update dependency versions and test import paths for enhanced stability

2025-01-29 - 2.1.0 - feat(CI)

Add Continuous Integration workflows for Gitea with Docker-based setup

2025-01-29 - 2.0.39 - fix(package.json)

Add pnpm overrides configuration for peek-readable package

2025-01-29 - 2.0.38 - fix(core)

Updated dependencies and added assetsHandler instantiation

2024-12-09 - 2.0.37 - fix(core)

Refactor TsWatch class to improve website execution handling

2024-12-09 - 2.0.36 - fix(dependencies)

Update @push.rocks/smartshell dependency version

2024-12-09 - 2.0.35 - fix(core)

Fixed website watch mode execution method

2024-12-04 - 2.0.34 - fix(TsWatch)

Fix reloading issue for tsfolder changes in element mode.

2024-12-04 - 2.0.33 - fix(core)

Improve async handling in TsWatch class for element and website modes

2024-12-04 - 2.0.32 - fix(core)

Minor improvements and dependency updates

2024-12-04 - 2.0.31 - fix(Watcher)

Add missing logger message in Watcher class for start method

2024-12-04 - 2.0.30 - fix(cli)

Fix incorrect watch mode and update npm test command.

2024-12-04 - 2.0.29 - fix(core)

No changes detected in the codebase.

2024-12-04 - 2.0.28 - fix(tswatch)

Add logging to notify folder watcher creation and building processes

2024-12-04 - 2.0.27 - fix(core)

Refactor watch mode commands and exports

2024-12-04 - 2.0.26 - fix(core)

Refactor watch modes and update dependencies

2024-10-27 - 2.0.25 - fix(typescript)

Remove unnecessary reference types in TypeScript declaration files

2024-10-27 - 2.0.24 - fix(core)

Remove .gitlab-ci.yml and update dependencies in package.json

2024-01-28 to 2024-01-09 - 2.0.14 to 2.0.23 - Core

Several updates to the core functionality.

2023-09-21 to 2023-01-28 - 2.0.8 to 2.0.13 - Core

Core system updates and fixes.

2023-03-31 to 2022-08-04 - 2.0.0 to 2.0.7 - Core

Enhanced core operations.

2022-05-04 - 1.0.81 - Core

Introduction of a breaking change in the core system.

2022-04-21 to 2022-03-18 - 1.0.62 to 1.0.80 - Core

Routine updates to core operations.

2022-03-14 to 2022-03-18 - 1.0.61 to 1.0.75 - Core

Further adjustments to core functionality.

2021-08-17 to 2020-07-07 - 1.0.46 to 1.0.60 - Core

Core component updates.

2020-07-04 to 2020-05-22 - 1.0.39 to 1.0.45 - Core

Incremental updates to core systems.

2020-03-13 to 2020-03-05 - 1.0.30 to 1.0.38 - Core

Stabilizing and refining core functions.

2019-10-14 to 2019-10-12 - 1.0.21 to 1.0.29 - Core

Tweaks and enhancements to the core mechanics.

2019-05-28 to 2019-05-06 - 1.0.10 to 1.0.20 - Core

Core module enhancements and fixes.

2019-05-06 to 2019-05-08 - 1.0.5 to 1.0.9 - Core

Regular updates ensuring core integrity.

2018-10-28 - 1.0.1 to 1.0.3 - Core

Initial setup and fixes to the core.