Case Sensitive Paths Webpack Plugin

A Webpack plugin that enforces case-sensitive module path matching across all platforms. Prevents build failures caused by incorrect file path casing that works on case-insensitive filesystems (like Windows/macOS) but fails on case-sensitive systems (like Linux).

Package Information

• Package Name: case-sensitive-paths-webpack-plugin
• Package Type: npm
• Language: JavaScript
• Installation: npm install --save-dev case-sensitive-paths-webpack-plugin
• Webpack Compatibility: Compatible with Webpack 4 and 5
• Node.js Compatibility: Requires Node.js 4 or higher

Core Imports

const CaseSensitivePathsPlugin = require('case-sensitive-paths-webpack-plugin');

Basic Usage

Add the plugin to your Webpack configuration:

const CaseSensitivePathsPlugin = require('case-sensitive-paths-webpack-plugin');

module.exports = {
  plugins: [
    new CaseSensitivePathsPlugin()
  ]
};

With configuration options:

module.exports = {
  plugins: [
    new CaseSensitivePathsPlugin({
      debug: true,
      logger: console,
      useBeforeEmitHook: false
    })
  ]
};

Architecture

The CaseSensitivePathsPlugin is built around several key architectural components:

Path Validation Workflow

1. Module Resolution Hook: Integrates with Webpack's module factory to intercept path resolution
2. Recursive Path Checking: Validates entire path hierarchy from root to target file
3. Case Sensitivity Validation: Compares requested path case with actual filesystem case
4. Error Reporting: Integrates with Webpack's error system for build failure reporting

Caching System

• Path Cache: Map<string, string[]> stores directory contents to minimize filesystem reads
• Cache Priming: Initializes cache with current working directory on first use
• Performance Tracking: Counts filesystem operations for debugging and optimization

Hook Integration Points

• Normal Module Factory Hook (default): Validates paths during module resolution
• Before Emit Hook (optional): Alternative validation during compilation emit phase
• Webpack Version Compatibility: Supports both legacy plugin API and modern hooks API

Error Handling Strategy

• Non-blocking for Missing Files: Allows Webpack to handle missing file errors
• Case Mismatch Detection: Identifies and reports specific case discrepancies
• Detailed Error Messages: Provides exact path comparison showing incorrect vs correct casing

Capabilities

Plugin Constructor

Creates a new instance of the case-sensitive paths plugin for Webpack.

/**
 * Creates a new CaseSensitivePathsPlugin instance
 * @param {Object} options - Configuration options
 * @param {boolean} options.debug - Enable debug logging (default: false)
 * @param {Object} options.logger - Custom logger with .log() method (default: console) 
 * @param {boolean} options.useBeforeEmitHook - Use emit hook instead of normal module factory hook (default: false)
 */
function CaseSensitivePathsPlugin(options);

Usage Examples:

// Basic usage with no options
const plugin = new CaseSensitivePathsPlugin();

// With debug enabled
const plugin = new CaseSensitivePathsPlugin({
  debug: true
});

// With custom logger
const plugin = new CaseSensitivePathsPlugin({
  debug: true,
  logger: {
    log: (message) => console.log(`[PLUGIN] ${message}`)
  }
});

Apply Method

The main Webpack plugin interface method that registers the plugin with the compiler.

/**
 * Registers the plugin with the Webpack compiler
 * @param {Object} compiler - Webpack compiler instance
 */
CaseSensitivePathsPlugin.prototype.apply(compiler);

Reset Method

Resets the plugin's internal state including path cache and filesystem operation counter.

/**
 * Resets internal state including path cache and filesystem operation counter
 */
CaseSensitivePathsPlugin.prototype.reset();

Path Validation Methods

Internal methods for validating file path case sensitivity.

/**
 * Reads directory contents with caching
 * @param {string} dir - Directory path to read
 * @param {Function} callback - Callback function to receive file list
 */
CaseSensitivePathsPlugin.prototype.getFilenamesInDir(dir, callback);

/**
 * Recursively checks if a file path exists with correct case sensitivity
 * @param {string} filepath - File path to check
 * @param {Function} callback - Callback function to receive result
 */
CaseSensitivePathsPlugin.prototype.fileExistsWithCase(filepath, callback);

/**
 * Initializes the path cache with the current working directory
 * @param {Function} callback - Callback function called when priming is complete
 */
CaseSensitivePathsPlugin.prototype.primeCache(callback);

Configuration Options

interface PluginOptions {
  /** Enable debug logging to show directory reads and filesystem operations count */
  debug?: boolean;
  /** Custom logger object with .log() method for debug output */
  logger?: { log: (message: string) => void };
  /** Use the emit hook instead of the normal module factory hook for checking paths */
  useBeforeEmitHook?: boolean;
}

Error Handling

The plugin integrates with Webpack's error reporting system:

• Error Format: [CaseSensitivePathsPlugin] \incorrect-path` does not match the corresponding path on disk `correct-path``
• Error Location: Errors are added to webpack's compilation errors array
• Non-existent Files: Files that don't exist are allowed to pass through for webpack to handle

Example Error Output:

ERROR in [CaseSensitivePathsPlugin] `/src/Components/Button.js` does not match the corresponding path on disk `/src/components/button.js`

Platform Compatibility

• Cross-platform: Works on Windows, macOS, and Linux
• Case-insensitive filesystems: Provides validation even on systems that don't enforce case sensitivity
• Unicode support: Handles international characters with NFC normalization
• Webpack versions: Compatible with both Webpack 4 and 5

Implementation Details

• Caching: Uses internal path cache to minimize filesystem operations
• Performance: Tracks filesystem operations count for debugging
• Path validation: Recursively validates entire path structure, not just individual files
• Hook integration: Plugs into Webpack's module resolution process
• Memory management: Provides reset functionality to clear internal state

Types

// Main plugin class
class CaseSensitivePathsPlugin {
  constructor(options?: PluginOptions);
  apply(compiler: Object): void;
  reset(): void;
  
  // Internal properties
  options: PluginOptions;
  logger: Object;
  pathCache: Map<string, string[]>;
  compiler: Object;
  fsOperations: number;
  primed: boolean;
}

// Configuration options interface
interface PluginOptions {
  debug?: boolean;
  logger?: { log: (message: string) => void };
  useBeforeEmitHook?: boolean;
}