@retrigger/core

Ultra-fast file system watcher with native performance for Node.js development tools

Replace slow JavaScript-based file watchers with native Rust performance. Get 100-400x faster hot reload times in your webpack and Vite projects.

🚀 Quick Start

npm install @retrigger/core

Webpack

// webpack.config.js
const { RetriggerWebpackPlugin } = require('@retrigger/core');

module.exports = {
  plugins: [
    new RetriggerWebpackPlugin({
      watchPaths: ['./src', './config'],
      verbose: process.env.NODE_ENV === 'development',
    }),
  ],
};

Vite

// vite.config.js
import { createRetriggerVitePlugin } from '@retrigger/core';

export default {
  plugins: [
    createRetriggerVitePlugin({
      watchPaths: ['./src'],
      enableAdvancedHMR: true,
    }),
  ],
};

📈 Performance

| Metric | Standard Watchers | Retrigger | Improvement | | ------------------ | ----------------- | --------- | ----------- | | Hot reload latency | 500-2000ms | <5ms | 100-400x | | CPU usage (idle) | 5-15% | <1% | 5-15x | | Memory usage | 50-200MB | 10-30MB | 2-7x |

🛠️ Configuration

Webpack Plugin Options

new RetriggerWebpackPlugin({
  // Directories to watch for changes
  watchPaths: ['./src', './config'],

  // Enable detailed logging
  verbose: false,

  // Debounce time for file events (ms)
  debounceMs: 50,

  // Enable Hot Module Replacement
  enableHMR: true,

  // Use SharedArrayBuffer for ultra-fast communication
  useSharedBuffer: true,

  // SharedArrayBuffer size (bytes)
  sharedBufferSize: 2 * 1024 * 1024, // 2MB

  // Maximum events to batch together
  maxEventBatch: 200,

  // Enable advanced dependency-aware invalidation
  enableAdvancedInvalidation: true,

  // Watch options
  watchOptions: {
    recursive: true,
    exclude_patterns: [
      '**/node_modules/**',
      '**/.git/**',
      '**/dist/**',
      '**/build/**',
    ],
    include_patterns: ['**/*.{js,jsx,ts,tsx,vue,svelte}'],
    enable_hashing: true,
    hash_block_size: 4096,
  },
});

Vite Plugin Options

createRetriggerVitePlugin({
  // Directories to watch
  watchPaths: ['./src'],

  // Enable verbose logging
  verbose: false,

  // Debounce time (ms) - lower for Vite
  debounceMs: 10,

  // Enable source map updates
  enableSourceMapUpdate: true,

  // Use SharedArrayBuffer for speed
  useSharedBuffer: true,

  // Enable advanced HMR with dependency tracking
  enableAdvancedHMR: true,

  // HMR invalidation strategy
  hmrInvalidationStrategy: 'smart', // 'conservative' | 'smart' | 'aggressive'

  // Watch options (same as webpack)
  watchOptions: {
    /* ... */
  },
});

🎯 Features

Core Benefits

• Native Performance: Rust-powered file watching with SIMD-optimized hashing
• Zero Dependencies: No heavy JavaScript file watcher dependencies
• Cross-Platform: Works on Linux, macOS, and Windows
• TypeScript Support: Full TypeScript definitions included
• Graceful Degradation: Falls back to JavaScript mode if native components unavailable

Advanced Features

• SharedArrayBuffer Communication: Sub-millisecond event propagation
• Dependency-Aware Invalidation: Only rebuild what actually changed
• Performance Monitoring: Built-in metrics and optimization tracking
• Multiple Build Tool Support: Works with webpack, Vite, Rspack, and more

📊 Monitoring

Performance Stats Endpoint

When using the Vite plugin, access real-time stats at:

• http://localhost:3000/__retrigger_stats - Basic performance metrics
• http://localhost:3000/__retrigger_hmr_stats - Advanced HMR statistics

Programmatic Access

// Get performance statistics
const stats = await retriggerPlugin.getPerformanceStats();
console.log(`Events processed: ${stats.total_events}`);
console.log(`Average latency: ${stats.averageEventLatency}ms`);

🔧 Troubleshooting

Common Issues

High CPU Usage

// Reduce CPU usage by excluding more directories
new RetriggerWebpackPlugin({
  watchOptions: {
    exclude_patterns: [
      '**/node_modules/**',
      '**/dist/**',
      '**/coverage/**',
      '**/.next/**',
      '**/.nuxt/**',
    ],
  },
});

Slow Initial Scan

// Disable hashing for faster startup
new RetriggerWebpackPlugin({
  watchOptions: {
    enable_hashing: false,
  },
});

Memory Usage

// Reduce SharedArrayBuffer size
new RetriggerWebpackPlugin({
  sharedBufferSize: 512 * 1024, // 512KB instead of 2MB
  maxEventBatch: 50, // Process fewer events at once
});

📝 TypeScript

Full TypeScript support is included:

import {
  RetriggerWebpackPlugin,
  createRetriggerVitePlugin,
  type FileEvent,
  type WatchOptions,
} from '@retrigger/core';

const plugin = new RetriggerWebpackPlugin({
  watchPaths: ['./src'],
  verbose: true,
});

🏗️ Requirements

• Node.js: 16.0.0 or higher
• Operating System: Linux, macOS, or Windows
• Architecture: x64, ARM64 (Apple Silicon supported)

🤝 Contributing

This package is part of the larger Retrigger project. See the main repository for contribution guidelines.

📄 License

MIT License - see LICENSE file for details.

Made with ⚡ by developers, for developers who value performance.