Dev Cache Reloader

A small development helper that forces modules to reload cleanly when files change, covering both CommonJS and ESM flows.

Capabilities

Clears cached CommonJS modules

• When loadCommonJS reads a fixture that increments a module-level counter, two calls without refresh return the same counter value, but inserting refresh([absolutePath]) between calls forces the next load to re-run the module and increment the counter again. @test

Busts ESM imports

• With an ESM fixture that exports its own last-modified timestamp, calling loadESM twice without refresh yields the same value; after writing a new timestamp to disk and calling refresh([absolutePath]), the following loadESM resolves to the updated export. @test

Tracks refresh activity

• After two refresh calls (one with a single file, one with two files including a duplicate), getStats reports totalRefreshes of 2 and the three unique absolute paths in sorted order. @test

Implementation

@generates

API

export type RefreshResult = {
  refreshed: string[];
  timestamp: number;
};

export interface CacheReloaderOptions {
  /**
   * Resolves a caller-provided path (relative or absolute) to an absolute path
   * before cache busting.
   */
  resolvePath(file: string): string;
  /** Optional callback when refresh completes */
  onRefresh?: (refreshed: string[]) => void;
}

export function createCacheReloader(options: CacheReloaderOptions): {
  /** Refresh caches for the provided files (absolute after resolution). */
  refresh(paths: string[]): RefreshResult;
  /** Require a CommonJS module after ensuring caches are clear. */
  loadCommonJS<T = unknown>(path: string): T;
  /** Dynamically import an ESM module with cache busting applied. */
  loadESM<T = unknown>(path: string): Promise<T>;
  /** Return cumulative refresh statistics. */
  getStats(): {
    totalRefreshes: number;
    uniquePaths: string[];
  };
};

Dependencies { .dependencies }

@tailwindcss/node { .dependency }

Provides Node-focused cache clearing utilities and an auto-registered loader that appends cache-busting identifiers to ESM imports.