0
# Mixin Configurations
1

2
Mixin configurations provide optional enhancements that can be layered on top of base profiles to add specialized functionality. Mixins must be loaded after the profile in the `extends` array and are designed to override or extend specific rules without conflicting with the base configuration.
3

4
## Capabilities
5

6
### Friendly Locals Mixin
7

8
Requires explicit type declarations for local variables to improve code readability and maintainability. This mixin restores TypeScript's explicit typing requirements that were relaxed in the base profiles for easier adoption.
9

10
```javascript { .api }
11
// Legacy format
12
module.exports = {
13
  extends: [
14
    "@rushstack/eslint-config/profile/node",
15
    "@rushstack/eslint-config/mixins/friendly-locals" // Must come after profile
16
  ],
17
  parserOptions: { tsconfigRootDir: __dirname }
18
};
19

20
// Flat format
21
import nodeProfile from "@rushstack/eslint-config/flat/profile/node";
22
import friendlyLocalsMixin from "@rushstack/eslint-config/flat/mixins/friendly-locals";
23
export default [...nodeProfile, ...friendlyLocalsMixin];
24
```
25

26
**Path**: `@rushstack/eslint-config/mixins/friendly-locals`  
27
**Flat Path**: `@rushstack/eslint-config/flat/mixins/friendly-locals`  
28
**Purpose**: Requires explicit type declarations for local variables  
29
**Impact**: Overrides `@typescript-eslint/typedef` rule to require `variableDeclaration: true`
30

31
**Code Impact Example:**
32

33
```typescript
34
// Without friendly-locals (allowed)
35
const item = provider.getItem(provider.title);
36
const index = item.fetchIndex();
37

38
// With friendly-locals (required)
39
const item: ISalesReport = provider.getItem(provider.title);
40
const index: Map<string, IGeographicData> = item.fetchIndex();
41
```
42

43
### Packlets Mixin
44

45
Enables the packlets organization system for structuring source files within a single project. Packlets provide a lightweight alternative to NPM packages for organizing code.
46

47
```javascript { .api }
48
// Legacy format
49
module.exports = {
50
  extends: [
51
    "@rushstack/eslint-config/profile/node",
52
    "@rushstack/eslint-config/mixins/packlets"
53
  ],
54
  parserOptions: { tsconfigRootDir: __dirname }
55
};
56

57
// Flat format
58
import nodeProfile from "@rushstack/eslint-config/flat/profile/node";
59
import packletsMixin from "@rushstack/eslint-config/flat/mixins/packlets";
60
export default [...nodeProfile, ...packletsMixin];
61
```
62

63
**Path**: `@rushstack/eslint-config/mixins/packlets`  
64
**Flat Path**: `@rushstack/eslint-config/flat/mixins/packlets`  
65
**Plugin**: `@rushstack/eslint-plugin-packlets`  
66
**Rules**: 
67
- `@rushstack/packlets/mechanics`: Enforces packlet import/export rules
68
- `@rushstack/packlets/circular-deps`: Detects circular dependencies between packlets
69

70
### React Mixin
71

72
Adds ESLint rules specifically designed for React projects. Includes validation for JSX patterns, React-specific coding practices, and performance optimizations.
73

74
```javascript { .api }
75
// Legacy format
76
module.exports = {
77
  extends: [
78
    "@rushstack/eslint-config/profile/web-app", // Recommended profile for React
79
    "@rushstack/eslint-config/mixins/react"
80
  ],
81
  parserOptions: { tsconfigRootDir: __dirname },
82
  settings: {
83
    react: {
84
      version: "18.0" // Specify your React version
85
    }
86
  }
87
};
88

89
// Flat format
90
import webAppProfile from "@rushstack/eslint-config/flat/profile/web-app";
91
import reactMixin from "@rushstack/eslint-config/flat/mixins/react";
92
export default [
93
  ...webAppProfile,
94
  ...reactMixin
95
];
96
```
97

98
**Path**: `@rushstack/eslint-config/mixins/react`  
99
**Flat Path**: `@rushstack/eslint-config/flat/mixins/react`  
100
**Plugin**: `eslint-plugin-react`  
101
**Required Settings**: `react.version` should be specified to avoid automatic detection overhead
102

103
**Key React Rules Enabled:**
104
- `react/jsx-key`: Requires keys for array elements
105
- `react/jsx-no-bind`: Prevents performance-impacting bind calls in JSX
106
- `react/jsx-no-comment-textnodes`: Prevents common JSX mistakes
107
- `react/jsx-no-target-blank`: Security rule for external links
108
- `react/jsx-uses-react`: Compatibility with React imports
109
- `react/jsx-uses-vars`: Compatibility with JSX variable usage
110
- `react/no-children-prop`: Prevents children prop misuse
111
- `react/no-danger-with-children`: Prevents dangerous DOM manipulation
112
- `react/no-deprecated`: Prevents usage of deprecated React APIs
113

114
### TSDoc Mixin
115

116
Validates TypeScript documentation comments to ensure they follow the TSDoc standard. Essential for projects using API Extractor or other TSDoc-compatible documentation tools.
117

118
```javascript { .api }
119
// Legacy format
120
module.exports = {
121
  extends: [
122
    "@rushstack/eslint-config/profile/node",
123
    "@rushstack/eslint-config/mixins/tsdoc"
124
  ],
125
  parserOptions: { tsconfigRootDir: __dirname }
126
};
127

128
// Flat format
129
import nodeProfile from "@rushstack/eslint-config/flat/profile/node";
130
import tsdocMixin from "@rushstack/eslint-config/flat/mixins/tsdoc";
131
export default [...nodeProfile, ...tsdocMixin];
132
```
133

134
**Path**: `@rushstack/eslint-config/mixins/tsdoc`  
135
**Flat Path**: `@rushstack/eslint-config/flat/mixins/tsdoc`  
136
**Plugin**: `eslint-plugin-tsdoc`  
137
**Rules**: `tsdoc/syntax`: Validates TSDoc comment syntax
138

139
**TSDoc Example:**
140

141
```typescript
142
/**
143
 * Calculates the total price including tax
144
 * @param basePrice - The base price before tax
145
 * @param taxRate - The tax rate as a decimal (e.g., 0.1 for 10%)
146
 * @returns The total price including tax
147
 * @public
148
 */
149
function calculateTotal(basePrice: number, taxRate: number): number {
150
  return basePrice * (1 + taxRate);
151
}
152
```
153

154
## Mixin Usage Patterns
155

156
### Single Mixin
157

158
```javascript
159
// .eslintrc.js
160
require('@rushstack/eslint-config/patch/modern-module-resolution');
161

162
module.exports = {
163
  extends: [
164
    "@rushstack/eslint-config/profile/node",
165
    "@rushstack/eslint-config/mixins/tsdoc"
166
  ],
167
  parserOptions: { tsconfigRootDir: __dirname }
168
};
169
```
170

171
### Multiple Mixins
172

173
```javascript
174
// .eslintrc.js
175
require('@rushstack/eslint-config/patch/modern-module-resolution');
176

177
module.exports = {
178
  extends: [
179
    "@rushstack/eslint-config/profile/web-app",
180
    "@rushstack/eslint-config/mixins/react",
181
    "@rushstack/eslint-config/mixins/friendly-locals",
182
    "@rushstack/eslint-config/mixins/tsdoc"
183
  ],
184
  parserOptions: { tsconfigRootDir: __dirname },
185
  settings: {
186
    react: {
187
      version: "18.0"
188
    }
189
  }
190
};
191
```
192

193
### Flat Configuration with Mixins
194

195
```javascript
196
// eslint.config.js
197
import nodeProfile from "@rushstack/eslint-config/flat/profile/node";
198
import tsdocMixin from "@rushstack/eslint-config/flat/mixins/tsdoc";
199
import friendlyLocalsMixin from "@rushstack/eslint-config/flat/mixins/friendly-locals";
200

201
export default [
202
  ...nodeProfile,
203
  ...tsdocMixin,
204
  ...friendlyLocalsMixin
205
];
206
```
207

208
## Mixin Configuration Structure
209

210
```typescript { .api }
211
// Legacy mixin structure
212
interface MixinConfig {
213
  plugins?: string[];
214
  settings?: {
215
    react?: {
216
      version: string;
217
    };
218
  };
219
  overrides: Array<{
220
    files: string[]; // Typically ['*.ts', '*.tsx']
221
    rules: Record<string, RuleConfig>;
222
  }>;
223
}
224

225
// Flat mixin structure
226
interface FlatMixinConfig extends Array<{
227
  files?: string[];
228
  plugins?: Record<string, any>;
229
  rules: Record<string, RuleConfig>;
230
  settings?: Record<string, any>;
231
}> {}
232

233
type RuleConfig = 
234
  | 'off' | 'warn' | 'error'
235
  | 0 | 1 | 2
236
  | ['off' | 'warn' | 'error' | 0 | 1 | 2, ...any[]];
237
```
238

239
## Requirements and Compatibility
240

241
**General Requirements:**
242
- Must be loaded after a profile in the `extends` array
243
- TypeScript files only (mixins typically target `['*.ts', '*.tsx']`)
244
- Compatible with all profiles (node, node-trusted-tool, web-app)
245

246
**React Mixin Requirements:**
247
- Recommended to use with `web-app` profile
248
- Must specify `settings.react.version` for optimal performance
249
- Requires JSX configuration in `tsconfig.json`: `"jsx": "react"`
250

251
**TSDoc Mixin Requirements:**
252
- Best used with API Extractor or other TSDoc-compatible tools
253
- Requires proper TSDoc syntax in TypeScript comments
254

255
**Packlets Mixin Requirements:**
256
- Requires understanding of packlet organization principles
257
- See [@rushstack/eslint-plugin-packlets](https://www.npmjs.com/package/@rushstack/eslint-plugin-packlets) documentation for setup details