Patch Utilities

Patch utilities provide essential functionality for ESLint configuration resolution and extended features. These utilities modify ESLint's behavior at runtime and must be required before your ESLint configuration is loaded.

Capabilities

Modern Module Resolution Patch

Required patch that fixes ESLint module resolution issues for proper compatibility with the ruleset. This patch must be required at the top of your .eslintrc.js file before any other configuration.

// Required at the top of .eslintrc.js
require('@rushstack/eslint-config/patch/modern-module-resolution');

module.exports = {
  extends: ["@rushstack/eslint-config/profile/node"],
  parserOptions: { tsconfigRootDir: __dirname }
};

Path: @rushstack/eslint-config/patch/modern-module-resolution
Status: Required for all configurations
Behavior: Side-effect only (no exports)
Purpose: Patches ESLint's module resolution to support modern dependency resolution patterns

This patch:

• Resolves plugin loading issues in monorepo environments
• Ensures proper resolution of bundled ESLint plugins
• Fixes compatibility issues with newer Node.js module resolution
• Prevents "cannot find plugin" errors

ESLint Bulk Suppressions Patch

Optional patch that enables ESLint bulk suppression functionality, allowing you to suppress multiple ESLint violations across your codebase using configuration files rather than inline comments.

// Optional - require at the top of .eslintrc.js if needed
require('@rushstack/eslint-config/patch/eslint-bulk-suppressions');

module.exports = {
  extends: ["@rushstack/eslint-config/profile/node"],
  parserOptions: { tsconfigRootDir: __dirname }
};

Path: @rushstack/eslint-config/patch/eslint-bulk-suppressions
Status: Optional
Behavior: Side-effect only (no exports)
Purpose: Enables bulk suppression of ESLint rules via external configuration

Features:

• Suppress rules across multiple files using configuration
• Manage technical debt by tracking suppressed violations
• Gradually address violations without blocking development
• Centralized suppression management

Flat Configuration Support:

// For flat config users
import '@rushstack/eslint-config/flat/patch/eslint-bulk-suppressions';

export default [
  // ... your configuration
];

Flat Path: @rushstack/eslint-config/flat/patch/eslint-bulk-suppressions

Custom Config Package Names Patch

Optional patch that enables support for custom ESLint configuration package naming patterns, useful for organizations with specific naming conventions for their ESLint configurations.

// Optional - require at the top of .eslintrc.js if needed
require('@rushstack/eslint-config/patch/custom-config-package-names');

module.exports = {
  extends: ["@rushstack/eslint-config/profile/node"],
  parserOptions: { tsconfigRootDir: __dirname }
};

Path: @rushstack/eslint-config/patch/custom-config-package-names
Status: Optional
Behavior: Side-effect only (no exports)
Purpose: Supports custom naming patterns for ESLint configuration packages
Implementation: Internally requires @rushstack/eslint-patch/custom-config-package-names

Features:

• Enables ESLint to resolve configuration packages with non-standard naming patterns
• Useful for organizations with custom ESLint configuration package naming conventions
• Extends ESLint's built-in configuration resolution logic
• Works with both legacy and flat configuration formats

Usage Patterns

Required Setup (Minimum)

Every project using @rushstack/eslint-config must include the modern-module-resolution patch:

// .eslintrc.js
require('@rushstack/eslint-config/patch/modern-module-resolution');

module.exports = {
  extends: ["@rushstack/eslint-config/profile/node"],
  parserOptions: { tsconfigRootDir: __dirname }
};

With Bulk Suppressions

For projects that need to manage ESLint violations incrementally:

// .eslintrc.js
require('@rushstack/eslint-config/patch/modern-module-resolution');
require('@rushstack/eslint-config/patch/eslint-bulk-suppressions');

module.exports = {
  extends: ["@rushstack/eslint-config/profile/node"],
  parserOptions: { tsconfigRootDir: __dirname }
};

Multiple Patches

You can combine multiple patches as needed:

// .eslintrc.js
require('@rushstack/eslint-config/patch/modern-module-resolution');
require('@rushstack/eslint-config/patch/eslint-bulk-suppressions');
require('@rushstack/eslint-config/patch/custom-config-package-names');

module.exports = {
  extends: ["@rushstack/eslint-config/profile/node"],
  parserOptions: { tsconfigRootDir: __dirname }
};

Flat Configuration

For ESLint 9+ flat configuration, use ES6 imports:

// eslint.config.js
import '@rushstack/eslint-config/flat/patch/eslint-bulk-suppressions';
import nodeProfile from "@rushstack/eslint-config/flat/profile/node";

export default [
  ...nodeProfile
];

Deprecated Patches

patch-eslint6.js (Deprecated)

// DEPRECATED - throws error with migration instructions
require('@rushstack/eslint-config/patch-eslint6');

Status: Deprecated - throws error
Replacement: Use patch/modern-module-resolution instead
Error Message: Directs users to use the modern-module-resolution patch

Implementation Details

// Patch modules are require-only with side effects
// No direct exports - they modify ESLint's runtime behavior

// Internal patch interface (not exported)
interface PatchBehavior {
  // Patches modify global ESLint behavior through side effects
  // No return values or exports
  readonly sideEffectsOnly: true;
}

Requirements and Compatibility

Modern Module Resolution:

• Status: Required for all @rushstack/eslint-config usage
• Compatibility: All ESLint versions supported by the package
• Side Effects: Modifies ESLint's plugin resolution behavior
• Impact: Prevents "cannot find plugin" errors in monorepo environments

ESLint Bulk Suppressions:

• Status: Optional - only needed if using bulk suppression features
• Compatibility: ESLint 8.57.0+ and ESLint 9.25.1+
• Configuration: Requires additional suppression configuration files
• Use Case: Large codebases with incremental ESLint adoption

Custom Config Package Names:

• Status: Optional - only needed for custom package naming
• Use Case: Organizations with specific ESLint config naming conventions
• Impact: Enables resolution of non-standard config package names

Troubleshooting

Common Issues:

1. "Cannot find plugin" errors: Ensure modern-module-resolution patch is required first
2. Patch not found: Verify the correct path is used (patch/ not just filename)
3. Order matters: Patches must be required before configuration objects
4. Flat config: Use import syntax instead of require for flat configurations

Correct Patch Order:

// ✅ Correct order
require('@rushstack/eslint-config/patch/modern-module-resolution');
require('@rushstack/eslint-config/patch/eslint-bulk-suppressions');

module.exports = {
  // ... configuration
};

// ❌ Incorrect - patches after configuration
module.exports = {
  // ... configuration
};
require('@rushstack/eslint-config/patch/modern-module-resolution');