0
# Patch Utilities
1

2
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.
3

4
## Capabilities
5

6
### Modern Module Resolution Patch
7

8
**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.
9

10
```javascript { .api }
11
// Required at the top of .eslintrc.js
12
require('@rushstack/eslint-config/patch/modern-module-resolution');
13

14
module.exports = {
15
  extends: ["@rushstack/eslint-config/profile/node"],
16
  parserOptions: { tsconfigRootDir: __dirname }
17
};
18
```
19

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

25
**This patch:**
26
- Resolves plugin loading issues in monorepo environments
27
- Ensures proper resolution of bundled ESLint plugins
28
- Fixes compatibility issues with newer Node.js module resolution
29
- Prevents "cannot find plugin" errors
30

31
### ESLint Bulk Suppressions Patch
32

33
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.
34

35
```javascript { .api }
36
// Optional - require at the top of .eslintrc.js if needed
37
require('@rushstack/eslint-config/patch/eslint-bulk-suppressions');
38

39
module.exports = {
40
  extends: ["@rushstack/eslint-config/profile/node"],
41
  parserOptions: { tsconfigRootDir: __dirname }
42
};
43
```
44

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

50
**Features:**
51
- Suppress rules across multiple files using configuration
52
- Manage technical debt by tracking suppressed violations
53
- Gradually address violations without blocking development
54
- Centralized suppression management
55

56
**Flat Configuration Support:**
57

58
```javascript { .api }
59
// For flat config users
60
import '@rushstack/eslint-config/flat/patch/eslint-bulk-suppressions';
61

62
export default [
63
  // ... your configuration
64
];
65
```
66

67
**Flat Path**: `@rushstack/eslint-config/flat/patch/eslint-bulk-suppressions`
68

69
### Custom Config Package Names Patch
70

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

73
```javascript { .api }
74
// Optional - require at the top of .eslintrc.js if needed
75
require('@rushstack/eslint-config/patch/custom-config-package-names');
76

77
module.exports = {
78
  extends: ["@rushstack/eslint-config/profile/node"],
79
  parserOptions: { tsconfigRootDir: __dirname }
80
};
81
```
82

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

89
**Features:**
90
- Enables ESLint to resolve configuration packages with non-standard naming patterns
91
- Useful for organizations with custom ESLint configuration package naming conventions
92
- Extends ESLint's built-in configuration resolution logic
93
- Works with both legacy and flat configuration formats
94

95
## Usage Patterns
96

97
### Required Setup (Minimum)
98

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

101
```javascript
102
// .eslintrc.js
103
require('@rushstack/eslint-config/patch/modern-module-resolution');
104

105
module.exports = {
106
  extends: ["@rushstack/eslint-config/profile/node"],
107
  parserOptions: { tsconfigRootDir: __dirname }
108
};
109
```
110

111
### With Bulk Suppressions
112

113
For projects that need to manage ESLint violations incrementally:
114

115
```javascript
116
// .eslintrc.js
117
require('@rushstack/eslint-config/patch/modern-module-resolution');
118
require('@rushstack/eslint-config/patch/eslint-bulk-suppressions');
119

120
module.exports = {
121
  extends: ["@rushstack/eslint-config/profile/node"],
122
  parserOptions: { tsconfigRootDir: __dirname }
123
};
124
```
125

126
### Multiple Patches
127

128
You can combine multiple patches as needed:
129

130
```javascript
131
// .eslintrc.js
132
require('@rushstack/eslint-config/patch/modern-module-resolution');
133
require('@rushstack/eslint-config/patch/eslint-bulk-suppressions');
134
require('@rushstack/eslint-config/patch/custom-config-package-names');
135

136
module.exports = {
137
  extends: ["@rushstack/eslint-config/profile/node"],
138
  parserOptions: { tsconfigRootDir: __dirname }
139
};
140
```
141

142
### Flat Configuration
143

144
For ESLint 9+ flat configuration, use ES6 imports:
145

146
```javascript
147
// eslint.config.js
148
import '@rushstack/eslint-config/flat/patch/eslint-bulk-suppressions';
149
import nodeProfile from "@rushstack/eslint-config/flat/profile/node";
150

151
export default [
152
  ...nodeProfile
153
];
154
```
155

156
## Deprecated Patches
157

158
### patch-eslint6.js (Deprecated)
159

160
```javascript { .api }
161
// DEPRECATED - throws error with migration instructions
162
require('@rushstack/eslint-config/patch-eslint6');
163
```
164

165
**Status**: Deprecated - throws error  
166
**Replacement**: Use `patch/modern-module-resolution` instead  
167
**Error Message**: Directs users to use the modern-module-resolution patch
168

169
## Implementation Details
170

171
```typescript { .api }
172
// Patch modules are require-only with side effects
173
// No direct exports - they modify ESLint's runtime behavior
174

175
// Internal patch interface (not exported)
176
interface PatchBehavior {
177
  // Patches modify global ESLint behavior through side effects
178
  // No return values or exports
179
  readonly sideEffectsOnly: true;
180
}
181
```
182

183
## Requirements and Compatibility
184

185
**Modern Module Resolution:**
186
- **Status**: Required for all @rushstack/eslint-config usage
187
- **Compatibility**: All ESLint versions supported by the package
188
- **Side Effects**: Modifies ESLint's plugin resolution behavior
189
- **Impact**: Prevents "cannot find plugin" errors in monorepo environments
190

191
**ESLint Bulk Suppressions:**
192
- **Status**: Optional - only needed if using bulk suppression features
193
- **Compatibility**: ESLint 8.57.0+ and ESLint 9.25.1+
194
- **Configuration**: Requires additional suppression configuration files
195
- **Use Case**: Large codebases with incremental ESLint adoption
196

197
**Custom Config Package Names:**
198
- **Status**: Optional - only needed for custom package naming
199
- **Use Case**: Organizations with specific ESLint config naming conventions
200
- **Impact**: Enables resolution of non-standard config package names
201

202
## Troubleshooting
203

204
**Common Issues:**
205

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

211
**Correct Patch Order:**
212

213
```javascript
214
// ✅ Correct order
215
require('@rushstack/eslint-config/patch/modern-module-resolution');
216
require('@rushstack/eslint-config/patch/eslint-bulk-suppressions');
217

218
module.exports = {
219
  // ... configuration
220
};
221

222
// ❌ Incorrect - patches after configuration
223
module.exports = {
224
  // ... configuration
225
};
226
require('@rushstack/eslint-config/patch/modern-module-resolution');
227
```