0
# Stylelint Configuration
1

2
Comprehensive Stylelint configuration with CSS modules support, SCSS/Less preprocessing, and opinionated rules for consistent CSS styling in Umi.js projects.
3

4
## Capabilities
5

6
### Main Stylelint Configuration
7

8
Core configuration object with base rules and plugin integration.
9

10
```javascript { .api }
11
/**
12
 * Stylelint configuration object
13
 * Provides comprehensive CSS/SCSS/Less linting with CSS modules support
14
 */
15
interface StylelintConfig {
16
  /** Extended base configurations */
17
  extends: string[];
18
  
19
  /** Stylelint plugins */
20
  plugins: string[];
21
  
22
  /** Custom rules configuration */
23
  rules: Record<string, any>;
24
  
25
  /** File-specific syntax overrides */
26
  overrides: Array<{
27
    files: string[];
28
    customSyntax: string;
29
  }>;
30
  
31
  /** Files to ignore during linting */
32
  ignoreFiles: string[];
33
}
34
```
35

36
### Default Configuration
37

38
The complete configuration as exported by @umijs/fabric.
39

40
```javascript { .api }
41
const stylelintConfig: StylelintConfig = {
42
  extends: [
43
    'stylelint-config-standard',
44
    'stylelint-config-css-modules',
45
    'stylelint-config-prettier',
46
  ],
47
  plugins: ['stylelint-declaration-block-no-ignored-properties'],
48
  rules: {
49
    'no-descending-specificity': null,
50
    'function-url-quotes': 'always',
51
    'selector-attribute-quotes': 'always',
52
    'selector-class-pattern': null,
53
    'font-family-no-missing-generic-family-keyword': null,
54
    'plugin/declaration-block-no-ignored-properties': true,
55
    'unit-no-unknown': [true, { ignoreUnits: ['rpx'] }],
56
    'selector-type-no-unknown': null,
57
    'value-keyword-case': ['lower', { ignoreProperties: ['composes'] }],
58
  },
59
  overrides: [
60
    {
61
      files: ['*.scss', '**/*.scss'],
62
      customSyntax: 'postcss-scss',
63
    },
64
    {
65
      files: ['*.less', '**/*.less'],
66
      customSyntax: 'postcss-less',
67
    },
68
  ],
69
  ignoreFiles: ['**/*.js', '**/*.jsx', '**/*.tsx', '**/*.ts'],
70
};
71
```
72

73
### Extended Configurations
74

75
Base configurations that provide the foundation rules.
76

77
```javascript { .api }
78
/**
79
 * Base configurations extended by @umijs/fabric
80
 */
81
interface ExtendedConfigs {
82
  /** Standard CSS rules and best practices */
83
  'stylelint-config-standard': StylelintConfig;
84
  
85
  /** CSS Modules specific rules and class name patterns */
86
  'stylelint-config-css-modules': StylelintConfig;
87
  
88
  /** Prettier compatibility rules (disables conflicting rules) */
89
  'stylelint-config-prettier': StylelintConfig;
90
}
91
```
92

93
**Configuration Details:**
94

95
- **stylelint-config-standard**: Provides comprehensive standard CSS rules
96
- **stylelint-config-css-modules**: Adds support for CSS Modules naming conventions
97
- **stylelint-config-prettier**: Disables rules that conflict with Prettier formatting
98

99
### Plugin Integration
100

101
Additional functionality through Stylelint plugins.
102

103
```javascript { .api }
104
/**
105
 * Stylelint plugin for detecting ignored CSS properties
106
 * Warns when CSS properties are ignored due to other property values
107
 */
108
interface DeclarationBlockPlugin {
109
  'plugin/declaration-block-no-ignored-properties': boolean;
110
}
111
```
112

113
**Plugin Features:**
114
- Detects CSS properties that are ignored due to conflicting properties
115
- Helps identify potential CSS issues and redundant declarations
116
- Improves CSS code quality and maintainability
117

118
### Custom Rules Configuration
119

120
Specific rule overrides and customizations for Umi.js projects.
121

122
```javascript { .api }
123
interface CustomRules {
124
  /** Disable specificity warnings (null = disabled) */
125
  'no-descending-specificity': null;
126
  
127
  /** Require quotes around URLs (always enforce) */
128
  'function-url-quotes': 'always';
129
  
130
  /** Require quotes around attribute selectors */
131
  'selector-attribute-quotes': 'always';
132
  
133
  /** Disable class pattern validation (allows CSS Modules) */
134
  'selector-class-pattern': null;
135
  
136
  /** Allow missing generic font families (for icon fonts) */
137
  'font-family-no-missing-generic-family-keyword': null;
138
  
139
  /** Enable ignored properties detection */
140
  'plugin/declaration-block-no-ignored-properties': boolean;
141
  
142
  /** Allow rpx units (responsive pixel units) */
143
  'unit-no-unknown': [boolean, { ignoreUnits: string[] }];
144
  
145
  /** Disable unknown selector type warnings */
146
  'selector-type-no-unknown': null;
147
  
148
  /** Enforce lowercase values except for CSS Modules 'composes' */
149
  'value-keyword-case': [string, { ignoreProperties: string[] }];
150
}
151
```
152

153
### Syntax-Specific Overrides
154

155
Custom syntax support for preprocessors.
156

157
```javascript { .api }
158
interface SyntaxOverrides {
159
  /** SCSS files configuration */
160
  scss: {
161
    files: string[];
162
    customSyntax: 'postcss-scss';
163
  };
164
  
165
  /** Less files configuration */
166
  less: {
167
    files: string[];
168
    customSyntax: 'postcss-less';
169
  };
170
}
171
```
172

173
**Supported Preprocessors:**
174
- **SCSS**: Full Sass/SCSS syntax support via postcss-scss
175
- **Less**: Complete Less syntax support via postcss-less
176
- **CSS**: Standard CSS syntax (default)
177

178
### File Exclusions
179

180
JavaScript and TypeScript files are automatically excluded from styling rules.
181

182
```javascript { .api }
183
/**
184
 * Files ignored by Stylelint
185
 * Prevents linting of JavaScript/TypeScript files that may contain CSS-in-JS
186
 */
187
const ignoreFiles: string[] = [
188
  '**/*.js',
189
  '**/*.jsx', 
190
  '**/*.tsx',
191
  '**/*.ts'
192
];
193
```
194

195
### Usage Examples
196

197
**Basic Integration:**
198

199
```javascript
200
// .stylelintrc.js
201
module.exports = {
202
  extends: [require.resolve('@umijs/fabric/dist/stylelint')],
203
};
204
```
205

206
**Custom Rule Overrides:**
207

208
```javascript
209
// .stylelintrc.js
210
module.exports = {
211
  extends: [require.resolve('@umijs/fabric/dist/stylelint')],
212
  rules: {
213
    // Override specific rules
214
    'selector-class-pattern': '^[a-z][a-zA-Z0-9]+$',
215
    'max-nesting-depth': 3,
216
    'declaration-block-no-duplicate-properties': true,
217
  },
218
};
219
```
220

221
**Additional File Types:**
222

223
```javascript
224
// .stylelintrc.js
225
module.exports = {
226
  extends: [require.resolve('@umijs/fabric/dist/stylelint')],
227
  overrides: [
228
    // Include Stylus files
229
    {
230
      files: ['*.styl', '**/*.styl'],
231
      customSyntax: 'postcss-styl',
232
    },
233
    // Include PostCSS files
234
    {
235
      files: ['*.pcss', '**/*.pcss'],
236
      customSyntax: 'postcss',
237
    },
238
  ],
239
};
240
```
241

242
**Project-Specific Ignores:**
243

244
```javascript
245
// .stylelintrc.js
246
module.exports = {
247
  extends: [require.resolve('@umijs/fabric/dist/stylelint')],
248
  ignoreFiles: [
249
    '**/*.js',
250
    '**/*.jsx',
251
    '**/*.tsx',
252
    '**/*.ts',
253
    // Additional project-specific ignores
254
    'dist/**/*',
255
    'build/**/*',
256
    'coverage/**/*',
257
  ],
258
};
259
```
260

261
**Package.json Scripts:**
262

263
```json
264
{
265
  "scripts": {
266
    "lint:style": "stylelint \"src/**/*.{css,scss,less}\"",
267
    "lint:style:fix": "stylelint \"src/**/*.{css,scss,less}\" --fix"
268
  }
269
}
270
```
271

272
### CSS Modules Support
273

274
Special handling for CSS Modules patterns and conventions.
275

276
**Supported Patterns:**
277
- Camel case class names: `.myComponent`
278
- Kebab case class names: `.my-component`
279
- Composition syntax: `composes: base from './base.css'`
280
- Local and global scoping: `:local(.class)` and `:global(.class)`
281

282
**Example CSS Modules Usage:**
283

284
```css
285
/* styles.module.css */
286
.container {
287
  padding: 16px;
288
  composes: flexCenter from './common.css';
289
}
290

291
.title {
292
  font-size: 24px;
293
  color: var(--primary-color);
294
}
295

296
:global(.ant-btn) {
297
  border-radius: 4px;
298
}
299
```
300

301
### SCSS/Less Features
302

303
Full support for preprocessor-specific syntax and features.
304

305
**SCSS Examples:**
306

307
```scss
308
// styles.scss
309
$primary-color: #1890ff;
310
$border-radius: 4px;
311

312
.component {
313
  background-color: $primary-color;
314
  border-radius: $border-radius;
315
  
316
  &:hover {
317
    opacity: 0.8;
318
  }
319
  
320
  .nested-element {
321
    margin: 8px;
322
  }
323
}
324
```
325

326
**Less Examples:**
327

328
```less
329
// styles.less
330
@primary-color: #1890ff;
331
@border-radius: 4px;
332

333
.component {
334
  background-color: @primary-color;
335
  border-radius: @border-radius;
336
  
337
  &:hover {
338
    opacity: 0.8;
339
  }
340
  
341
  .nested-element {
342
    margin: 8px;
343
  }
344
}
345
```