git.zone/tswatch
2
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

update readme

Browse Source
This commit is contained in:
Juergen Kunz
2025-07-10 14:33:10 +00:00
parent 488bd65933
commit ecd76bc8aa
2 changed files with 202 additions and 128 deletions
Download Patch File Download Diff File Expand all files Collapse all files

44
readme.hints.md
View File

@@ -0,0 +1,44 @@
# tswatch Project Hints
## Core Architecture
- tswatch is a TypeScript file watcher with multiple operation modes
- Main class `TsWatch` orchestrates different watch modes
- `Watcher` class handles individual file watching and command execution
## Available Watch Modes
1. **npm/node** (default): Runs `npm test` on changes
2. **test**: Runs `npm run test2` on changes
3. **element**: Web component development with dev server on port 3002
4. **service**: Runs `npm run startTs` for service projects
5. **website**: Full website mode with bundling and asset processing
6. **echo**: Test mode that runs `npm -v` (for testing)
## Key Implementation Details
- Uses `@push.rocks/smartchok` for file watching
- Uses `@git.zone/tsbundle` for bundling with esbuild
- Uses `@api.global/typedserver` for development server in element mode
- Element/website modes watch multiple `ts*/` directories
- All modes support both command execution and function callbacks
## CLI Entry Points
- `cli.js` -> Main CLI entry point
- `ts/tswatch.cli.ts` -> CLI implementation with smartcli
- Default command triggers npm mode
## Project Structure Expectations
- `ts/` - Backend TypeScript files
- `ts_web/` - Frontend TypeScript files (element/website modes)
- `html/` - HTML templates (element/website modes)
- `assets/` - Static assets (website mode only)
- `dist_watch/` - Output for element mode
- `dist_serve/` - Output for website mode
## Development Server Details
- Port: 3002
- Features: CORS, gzip compression, live reload injection
- Only available in element mode via `typedserver` property
## Common Issues to Watch For
- The test mode runs `test2` script, not `test`
- Website mode restarts the entire server process on backend changes
- Element mode rebuilds and reloads on any ts* folder change

270
readme.md
View File

@@ -1,183 +1,213 @@
# @git.zone/tswatch
A development tool for watching and re-compiling TypeScript projects automatically upon detecting changes.
A TypeScript file watcher that automatically recompiles and executes your project when files change. Designed to streamline development workflows for various TypeScript project types.
## Install
## Features
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:
- 🔄 **Automatic recompilation** on file changes
- 🚀 **Multiple project modes**: npm packages, web elements, services, and websites
- 🌐 **Built-in development server** with live reload for web projects
- ⚡ **Fast bundling** with esbuild integration
- 🛠️ **Flexible CLI and programmatic API**
- 📦 **Zero configuration** for standard project structures
## Prerequisites
- Node.js (v14 or higher)
- pnpm (recommended) or npm
## Installation
Install `@git.zone/tswatch` globally or as a development dependency:
```bash
npm install @git.zone/tswatch
# Global installation
pnpm install -g @git.zone/tswatch
# As a dev dependency
pnpm install --save-dev @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:
```typescript
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:
## Quick Start
```bash
# Watch and run tests on changes (default behavior)
tswatch
# Watch a web element project with dev server
tswatch element
# Watch a service project
tswatch service
```
## CLI Commands
### `tswatch` or `tswatch npm`
Watches TypeScript files and runs `npm test` on changes. This is the default mode.
```bash
tswatch
# or explicitly
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`
Sets up a development environment for web components/elements:
- Starts a dev server on port 3002
- Bundles TypeScript to `dist_watch/`
- Enables live reload
- Watches all `ts*/` folders
```bash
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 `./ts/` and runs `npm run startTs` on changes. Ideal for backend services.
```bash
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`
Full website development mode:
- Bundles TypeScript files to `dist_serve/`
- Processes HTML files
- Handles assets
- Runs `npm run startTs` for server-side code
```bash
tswatch website
```
Similar to element projects but specifically designed for full websites, recompiling TypeScript files for web deployment scenarios.
### `tswatch test`
Runs `npm run test2` whenever files change. Useful for projects with custom test scripts.
#### Step 2: Integration into a Node.js Environment
```bash
tswatch test
```
You can integrate `@git.zone/tswatch` directly into a Node.js project for automatic file watching and recompiling:
## Project Structure
tswatch expects certain project structures depending on the mode:
### NPM/Node Projects
```
project/
├── ts/ # TypeScript source files
├── test/ # Test files
└── package.json # With "test" script
```
### Element Projects
```
project/
├── ts/ # Backend TypeScript
├── ts_web/ # Frontend TypeScript
├── html/ # HTML templates
│ └── index.ts # Entry point
└── dist_watch/ # Output directory (auto-created)
```
### Website Projects
```
project/
├── ts/ # Backend TypeScript
├── ts_web/ # Frontend TypeScript
│ └── index.ts # Entry point
├── html/ # HTML files
│ └── index.html
├── assets/ # Static assets
└── dist_serve/ # Output directory
```
## Programmatic API
### Basic Usage
```typescript
import { TsWatch } from '@git.zone/tswatch';
const startWatch = async () => {
// Initialize watch instance for a node project
const watchInstance = new TsWatch('node');
await watchInstance.start();
};
// Create and start a watcher
const watcher = new TsWatch('node');
await watcher.start();
// Optionally, stop the watcher gracefully
const stopWatch = async (watchInstance: TsWatch) => {
await watchInstance.stop();
};
// Stop when done
await watcher.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:
```typescript
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:
### Custom Watchers
```typescript
import { Watcher } from '@git.zone/tswatch';
const customWatcherSetup = async () => {
const customWatcher = new Watcher({
filePathToWatch: '/path/to/watch',
commandToExecute: 'npm run custom-script',
filePathToWatch: './src',
commandToExecute: 'npm run build',
timeout: 5000 // Optional timeout in ms
});
// 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:
### Using Function Callbacks
```typescript
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()}`);
const watcher = new Watcher({
filePathToWatch: './src',
functionToCall: async () => {
console.log('Files changed!');
// Your custom logic here
}
});
// Initiate all watchers
await tsWatchInstance.start();
};
```
Incorporate this setup for efficiently managing complex projects with varied sources and parallel build tasks.
## Development Server
#### Handling Timeout and Cleanup
Element mode includes a built-in development server:
`@git.zone/tswatch` includes functions to manage process exits and timeout scenarios robustly:
- **Port**: 3002
- **Features**: CORS enabled, gzip compression, live reload
- **Serve directory**: `./dist_watch/`
```typescript
import { Watcher } from '@git.zone/tswatch';
Access your project at `http://localhost:3002` when running in element mode.
const watcherWithTimeout = () => {
new Watcher({
filePathToWatch: './src/',
timeout: 10000, // 10 seconds timeout
commandToExecute: 'echo "Task completed"',
}).start();
};
## Configuration Tips
1. **TypeScript Config**: Ensure your `tsconfig.json` is properly configured for your target environment
2. **Package Scripts**: Define appropriate scripts in `package.json`:
- `test`: For npm mode
- `startTs`: For service/website modes
- `build`: For general compilation
3. **File Organization**: Keep TypeScript files in `ts/` (backend) and `ts_web/` (frontend) directories
## Common Use Cases
### Developing a Node.js Library
```bash
tswatch npm
```
Automatically runs tests when you modify source files.
The `timeout` option ensures processes don't run indefinitely, aiding development and potential automated testing scenarios.
### Building a Web Component
```bash
tswatch element
```
Get instant feedback with live reload while developing custom elements.
### Conclusion
### Creating a Backend Service
```bash
tswatch service
```
Automatically restart your service on code changes.
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.
### Full-Stack Web Application
```bash
tswatch website
```
Handle both frontend and backend compilation with asset processing.
## License and Legal Information