tswatch/readme.hints.md

tswatch Project Hints

Core Architecture (v3.x - Config-Driven)

tswatch is now a config-driven TypeScript file watcher. Configuration is read from npmextra.json under the key @git.zone/tswatch.

Key Classes

• TsWatch: Main orchestrator class, accepts ITswatchConfig
• Watcher: Handles individual file watching with debouncing and restart modes
• ConfigHandler: Loads and manages configuration from npmextra.json
• TswatchInit: Interactive wizard for creating configuration

Configuration Structure

{
  "@git.zone/tswatch": {
    "watchers": [
      {
        "name": "backend",
        "watch": "./ts/**/*",
        "command": "npm run startTs",
        "restart": true,
        "debounce": 300,
        "runOnStart": true
      }
    ],
    "server": {
      "enabled": true,
      "port": 3002,
      "serveDir": "./dist_watch/",
      "liveReload": true
    },
    "bundles": [
      {
        "name": "frontend",
        "from": "./html/index.ts",
        "to": "./dist_watch/bundle.js",
        "watchPatterns": ["./ts_web/**/*"],
        "triggerReload": true
      }
    ],
    "preset": "element"
  }
}

Available Presets

• npm: Watch ts/ and test/, run npm test
• test: Watch ts/ and test/, run npm run test2
• service: Watch ts/, run npm run startTs with restart
• element: Dev server on 3002, bundle ts_web, watch html
• website: Full stack with backend restart + frontend bundling + assets

CLI Commands

• tswatch - Run with config (or launch wizard if no config)
• tswatch init - Force run the configuration wizard

Key Implementation Details

• Uses @push.rocks/smartwatch (v6.x) for file watching - class is Smartwatch
• Uses @push.rocks/smartfs (v1.x) for filesystem operations
• Uses @push.rocks/npmextra for reading npmextra.json config
• Uses @push.rocks/smartinteract for the init wizard
• Uses @git.zone/tsbundle for bundling with esbuild
• Uses @api.global/typedserver UtilityWebsiteServer for development server (wraps TypedServer with service worker, PWA manifest, and live reload)

Watcher Features

• Debouncing: Configurable delay before executing (default: 300ms)
• Restart mode: Kill previous process before restarting (configurable)
• Named watchers: All watchers have names for clear logging
• Multiple watch patterns: Can watch multiple glob patterns

Server Features

• Uses UtilityWebsiteServer from @api.global/typedserver (not raw TypedServer)
• Port configurable (default: 3002)
• CORS enabled
• Compression (brotli + gzip)
• Live reload via WebSocket (service worker + devtools injection)
• SPA fallback support
• No-cache headers (prevents browser caching during development)
• PWA manifest auto-generated
• Service worker version info handler
• Domain configurable (default: 'localhost')

Project Structure

• ts/tswatch.classes.tswatch.ts - Main TsWatch class
• ts/tswatch.classes.watcher.ts - Watcher class with debounce/restart
• ts/tswatch.classes.confighandler.ts - Config loading
• ts/tswatch.init.ts - Interactive init wizard
• ts/tswatch.cli.ts - CLI entry point
• ts/interfaces/interfaces.config.ts - Type definitions