File Watching

Development-focused file watching system for automatic CSS regeneration when source files change, providing hot reload functionality for UnoCSS development workflows.

Capabilities

Get Watcher

Creates or returns existing chokidar file system watcher for monitoring file changes during development.

/**
 * Creates or returns existing chokidar file system watcher
 * @param options - CLI options containing patterns and working directory
 * @returns Promise resolving to FSWatcher instance for file monitoring
 */
function getWatcher(options?: CliOptions): Promise<FSWatcher>;

Usage Examples:

// Note: getWatcher may not be directly exported from main package entry
import { getWatcher } from "@unocss/cli";

// Create watcher for HTML files
const watcher = await getWatcher({
  patterns: ["src/**/*.html"],
  cwd: process.cwd(),
});

// Listen for file changes
watcher.on('change', (path) => {
  console.log(`File changed: ${path}`);
});

watcher.on('add', (path) => {
  console.log(`File added: ${path}`);
});

watcher.on('unlink', (path) => {
  console.log(`File removed: ${path}`);
});

// Close watcher when done
process.on('SIGINT', () => {
  watcher.close();
});

Watch Configuration

The watcher is configured with sensible defaults for web development:

• Ignored directories: Automatically ignores node_modules and .git directories
• Permission handling: Ignores permission errors that might occur on some systems
• Initial scan: Skips initial file scan (ignoreInitial: true) to avoid triggering on startup
• Singleton pattern: Returns the same watcher instance for efficiency

Integration with Build Process

When watch mode is enabled in the build function, the following workflow occurs:

1. Initial Build: Performs complete CSS generation from all files
2. Watcher Setup: Creates file system watcher for specified patterns
3. Configuration Monitoring: Also watches UnoCSS configuration files for changes
4. Change Detection: Monitors both source files and configuration files
5. Debounced Rebuilds: Uses debouncing to prevent excessive rebuilds
6. Cache Management: Updates file cache when files change
7. Automatic Regeneration: Rebuilds CSS automatically when changes are detected

Watch Mode Examples

import { build } from "@unocss/cli";

// Basic watch mode
await build({
  patterns: ["src/**/*.{html,js,ts}"],
  outFile: "dist/uno.css",
  watch: true,
});

// Watch with custom configuration
await build({
  patterns: ["src/**/*.html", "components/**/*.jsx"],
  outFile: "public/styles.css",
  watch: true,
  config: "uno.config.js",
  preflights: true,
});

Manual Watcher Usage

For advanced use cases, you can create and manage watchers manually:

import { getWatcher } from "@unocss/cli";
import { debounce } from "perfect-debounce";

// Create custom watcher setup
const watcher = await getWatcher({
  patterns: ["src/**/*.{html,js,vue}"],
  cwd: "/path/to/project",
});

// Custom debounced rebuild function
const debouncedRebuild = debounce(async () => {
  console.log("Rebuilding CSS...");
  // Your custom rebuild logic here
}, 100);

// Handle different file events
watcher.on('all', (event, path) => {
  console.log(`${event}: ${path}`);
  
  if (event === 'change' || event === 'add') {
    debouncedRebuild();
  }
});

// Graceful shutdown
process.on('SIGTERM', () => {
  watcher.close();
});

File Change Handling

The watch system handles different types of file changes appropriately:

Source File Changes

• File Added: Adds new file to cache and triggers rebuild
• File Modified: Updates cached content and triggers rebuild
• File Deleted: Removes file from cache and triggers rebuild

Configuration File Changes

• Config Modified: Reloads UnoCSS configuration and triggers full rebuild
• Config Added: Starts monitoring new configuration file
• Config Deleted: Falls back to default configuration

Logging and Feedback

The watch system provides detailed console feedback:

UnoCSS v66.5.0
✨ UnoCSS in watch mode...
ℹ Watching for changes in src/**/*.html, src/**/*.js

change src/index.html
✅ 15 utilities generated to dist/uno.css

add src/components/button.html  
✅ 23 utilities generated to dist/uno.css

uno.config.js changed, setting new config
✅ 23 utilities generated to dist/uno.css

Performance Considerations

• Debouncing: File changes are debounced (100ms) to prevent excessive rebuilds
• Selective Processing: Only processes files that have actually changed
• Efficient Caching: Maintains in-memory file cache to avoid unnecessary disk reads
• Singleton Watcher: Reuses watcher instances to minimize resource usage