@salama/hot-import

Pure hot module reloading for TypeScript/JavaScript projects with zero framework dependencies.

Features

• ✅ Zero Dependencies - Only uses Node.js built-ins
• ✅ Framework Agnostic - Works with any TS/JS project
• ✅ Transparent Proxies - Always reference latest module versions
• ✅ Circular Import Safe - Handles circular dependencies properly
• ✅ Cross Platform - Windows and Unix path handling
• ✅ Cache Busting - Automatic timestamp-based cache invalidation
• ✅ TypeScript Support - Runtime TypeScript compilation with full type safety
• ✅ Direct .ts imports - No pre-compilation required

Installation

npm install @salama/hot-import

Basic Usage

import { hotImport } from '@salama/hot-import';

// Your imports automatically become "hot" - they always reference the latest version
const { MyClass } = await hotImport('./myModule.js', import.meta.url);

// MyClass always points to the latest version when file changes
const instance = new MyClass();

API

hotImport<T>(modulePath: string, importerMetaUrl: string): Promise<T>

Import a module with hot reloading capability.

• modulePath - Relative path to the module
• importerMetaUrl - Use import.meta.url from the calling file
• Returns a proxy that always references the latest module exports

refreshModule(modulePath: string, importerMetaUrl: string): Promise<void>

Manually refresh a specific module.

notifyFileChanged(filePath: string): Promise<void>

Notify the system that a file has changed (for file watcher integration).

moduleRegistry: Map<string, ModuleInfo>

Access to the internal module registry for debugging.

Example

JavaScript Files

// math.js
export class Calculator {
  add(a, b) {
    return a + b;
  }
}

// main.js
import { hotImport } from '@salama/hot-import';

const { Calculator } = await hotImport('./math.js', import.meta.url);
const calc = new Calculator();

// When you modify math.js, Calculator automatically uses the new version
console.log(calc.add(2, 3)); // Always uses latest implementation

TypeScript Files (NEW!)

// math.ts
export class Calculator {
  add(a: number, b: number): number {
    return a + b;
  }
  
  multiply(a: number, b: number): number {
    return a * b;
  }
}

// main.ts
import { hotImport } from '@salama/hot-import';

// Direct .ts import - compiles automatically!
const { Calculator } = await hotImport('./math.ts', import.meta.url);
const calc = new Calculator();

// When you modify math.ts, Calculator automatically recompiles and updates
console.log(calc.add(2, 3)); // 5
console.log(calc.multiply(4, 5)); // 20

File Watcher Integration

import { notifyFileChanged } from '@salama/hot-import';
import { watch } from 'fs';

watch('./src', { recursive: true }, (eventType, filename) => {
  if (filename && (filename.endsWith('.js') || filename.endsWith('.ts'))) {
    notifyFileChanged(filename);
  }
});

License

MIT