0
# @rushstack/eslint-config
1

2
@rushstack/eslint-config is a TypeScript ESLint ruleset designed for large teams and projects. It provides battle-tested configurations optimized for scalability, readability, and maintainability in enterprise development environments. The package offers three distinct profiles along with multiple mixins for additional functionality, designed to work seamlessly with Prettier and modern development workflows.
3

4
## Package Information
5

6
- **Package Name**: @rushstack/eslint-config
7
- **Package Type**: npm
8
- **Language**: JavaScript/TypeScript
9
- **Installation**: `npm install --save-dev @rushstack/eslint-config eslint typescript`
10

11
## Core Imports
12

13
For legacy ESLint configurations:
14

15
```javascript
16
// Required at the top of .eslintrc.js
17
require('@rushstack/eslint-config/patch/modern-module-resolution');
18

19
module.exports = {
20
  extends: ["@rushstack/eslint-config/profile/node"],
21
  parserOptions: { tsconfigRootDir: __dirname }
22
};
23
```
24

25
For flat ESLint configurations (ESLint 9+):
26

27
```javascript
28
import nodeProfile from "@rushstack/eslint-config/flat/profile/node";
29

30
export default [
31
  ...nodeProfile
32
];
33
```
34

35
## Basic Usage
36

37
**Simple Node.js project:**
38

39
```javascript
40
// .eslintrc.js
41
require('@rushstack/eslint-config/patch/modern-module-resolution');
42

43
module.exports = {
44
  extends: ["@rushstack/eslint-config/profile/node"],
45
  parserOptions: { tsconfigRootDir: __dirname }
46
};
47
```
48

49
**Web application with React:**
50

51
```javascript
52
// .eslintrc.js
53
require('@rushstack/eslint-config/patch/modern-module-resolution');
54

55
module.exports = {
56
  extends: [
57
    "@rushstack/eslint-config/profile/web-app",
58
    "@rushstack/eslint-config/mixins/react"
59
  ],
60
  parserOptions: { tsconfigRootDir: __dirname },
61
  settings: {
62
    react: {
63
      version: "18.0"
64
    }
65
  }
66
};
67
```
68

69
**Flat configuration for Node.js:**
70

71
```javascript
72
// eslint.config.js
73
import nodeProfile from "@rushstack/eslint-config/flat/profile/node";
74
import tsdocMixin from "@rushstack/eslint-config/flat/mixins/tsdoc";
75

76
export default [
77
  ...nodeProfile,
78
  ...tsdocMixin
79
];
80
```
81

82
## Architecture
83

84
@rushstack/eslint-config is designed around several key principles:
85

86
- **Profile-based Configuration**: Three foundational profiles (node, node-trusted-tool, web-app) provide base rule sets optimized for different environments
87
- **Mixin System**: Optional enhancements that can be layered on top of profiles for specific functionality (React, TSDoc, etc.)
88
- **Patch System**: Required and optional patches for ESLint compatibility and extended functionality
89
- **Dual Format Support**: Both legacy ESLint configuration and modern flat configuration formats
90
- **Monorepo Friendly**: Self-contained dependencies to avoid peer dependency management overhead
91
- **Explicit Configuration**: No "recommended" templates to avoid precedence issues and configuration conflicts
92

93
## Capabilities
94

95
### Profile Configurations
96

97
Core ESLint configuration profiles that form the foundation of the ruleset. Each profile is optimized for specific runtime environments and security requirements.
98

99
```typescript { .api }
100
// Legacy format exports
101
const profileConfig: {
102
  extends?: string[];
103
  rules: Record<string, any>;
104
  plugins?: string[];
105
  env?: Record<string, boolean>;
106
  parser?: string;
107
  parserOptions?: Record<string, any>;
108
  overrides?: Array<{
109
    files: string[];
110
    rules: Record<string, any>;
111
  }>;
112
};
113

114
// Flat format exports
115
const flatConfig: Array<{
116
  files?: string[];
117
  rules: Record<string, any>;
118
  plugins?: Record<string, any>;
119
  languageOptions?: {
120
    parser?: any;
121
    parserOptions?: Record<string, any>;
122
  };
123
}>;
124
```
125

126
[Profile Configurations](./profiles.md)
127

128
### Mixin Configurations
129

130
Optional configuration extensions that add specialized functionality to base profiles. Mixins must be loaded after profiles in the extends array.
131

132
```typescript { .api }
133
// Legacy mixin structure
134
const mixinConfig: {
135
  plugins?: string[];
136
  settings?: Record<string, any>;
137
  overrides: Array<{
138
    files: string[];
139
    rules: Record<string, any>;
140
  }>;
141
};
142

143
// Flat mixin structure  
144
const flatMixinConfig: Array<{
145
  files?: string[];
146
  plugins?: Record<string, any>;
147
  rules: Record<string, any>;
148
  settings?: Record<string, any>;
149
}>;
150
```
151

152
[Mixin Configurations](./mixins.md)
153

154
### Patch Utilities
155

156
Essential utilities for ESLint configuration resolution and extended functionality. The modern-module-resolution patch is required for proper operation.
157

158
```typescript { .api }
159
// Patch modules (require-only, no exports)
160
require('@rushstack/eslint-config/patch/modern-module-resolution');
161
require('@rushstack/eslint-config/patch/eslint-bulk-suppressions');
162
require('@rushstack/eslint-config/patch/custom-config-package-names');
163
```
164

165
[Patch Utilities](./patches.md)
166

167
### Deprecated Entry Points
168

169
Legacy entry points that throw errors and redirect users to updated paths for better organization and clarity.
170

171
```typescript { .api }
172
// Deprecated entry points (throw errors with migration instructions)
173
require('@rushstack/eslint-config'); // Error: Use profile paths instead
174
require('@rushstack/eslint-config/react'); // Error: Use mixins/react instead  
175
require('@rushstack/eslint-config/patch-eslint6'); // Error: Use patch/modern-module-resolution instead
176
```
177

178
**Deprecated Paths:**
179
- `@rushstack/eslint-config` → Use `@rushstack/eslint-config/profile/[node|web-app|node-trusted-tool]`
180
- `@rushstack/eslint-config/react` → Use `@rushstack/eslint-config/mixins/react`
181
- `@rushstack/eslint-config/patch-eslint6` → Use `@rushstack/eslint-config/patch/modern-module-resolution`
182

183
## Types
184

185
```typescript { .api }
186
interface ESLintConfig {
187
  extends?: string[];
188
  rules: Record<string, RuleConfig>;
189
  plugins?: string[];
190
  env?: Record<string, boolean>;
191
  parser?: string;
192
  parserOptions?: {
193
    tsconfigRootDir?: string;
194
    project?: string | string[];
195
    ecmaVersion?: number;
196
    sourceType?: 'module' | 'script';
197
  };
198
  overrides?: Array<{
199
    files: string[];
200
    rules: Record<string, RuleConfig>;
201
  }>;
202
  settings?: Record<string, any>;
203
}
204

205
interface FlatESLintConfig {
206
  files?: string[];
207
  ignores?: string[];
208
  rules: Record<string, RuleConfig>;
209
  plugins?: Record<string, any>;
210
  languageOptions?: {
211
    parser?: any;
212
    parserOptions?: Record<string, any>;
213
    globals?: Record<string, boolean>;
214
  };
215
  settings?: Record<string, any>;
216
}
217

218
type RuleConfig = 
219
  | 'off' | 'warn' | 'error'
220
  | 0 | 1 | 2
221
  | ['off' | 'warn' | 'error' | 0 | 1 | 2, ...any[]];
222

223
interface ReactSettings {
224
  react: {
225
    version: string;
226
  };
227
}
228
```