0
# Stylelint Configuration
1

2
@umijs/fabric provides a comprehensive Stylelint configuration for CSS and SCSS linting with support for CSS modules, modern CSS features, and integration with Prettier.
3

4
## Import
5

6
```javascript
7
// Direct module import
8
const { stylelint } = require("@umijs/fabric");
9

10
// Configuration file usage
11
module.exports = {
12
  extends: [require.resolve('@umijs/fabric/dist/stylelint')],
13
};
14
```
15

16
## Configuration Object
17

18
```typescript { .api }
19
/**
20
 * Stylelint configuration object for CSS/SCSS linting
21
 */
22
const stylelint: StylelintConfig;
23

24
interface StylelintConfig {
25
  extends: string[];
26
  plugins: string[];
27
  rules: StylelintRules;
28
  ignoreFiles: string[];
29
}
30

31
type StylelintRules = Record<string, any>;
32
```
33

34
## Core Configuration Structure
35

36
### Base Extensions
37

38
```typescript { .api }
39
/**
40
 * Base configurations that this stylelint config extends
41
 */
42
const extends: string[] = [
43
  'stylelint-config-standard',
44
  'stylelint-config-css-modules', 
45
  'stylelint-config-prettier',
46
];
47
```
48

49
### Plugins
50

51
```typescript { .api }
52
/**
53
 * Stylelint plugins included in the configuration
54
 */
55
const plugins: string[] = [
56
  'stylelint-declaration-block-no-ignored-properties'
57
];
58
```
59

60
### File Patterns
61

62
```typescript { .api }
63
/**
64
 * Files to ignore during stylelint processing
65
 */
66
const ignoreFiles: string[] = [
67
  '**/*.js',
68
  '**/*.jsx', 
69
  '**/*.tsx',
70
  '**/*.ts'
71
];
72
```
73

74
## Rule Configuration
75

76
### Core Rules
77

78
```typescript { .api }
79
/**
80
 * Stylelint rules configuration
81
 */
82
interface StylelintRulesConfig {
83
  /**
84
   * Disable descending specificity warning
85
   */
86
  'no-descending-specificity': null;
87
  
88
  /**
89
   * Require quotes around URLs
90
   */
91
  'function-url-quotes': 'always';
92
  
93
  /**
94
   * Require quotes around attribute selectors
95
   */
96
  'selector-attribute-quotes': 'always';
97
  
98
  /**
99
   * Allow missing generic family keywords for icon fonts
100
   */
101
  'font-family-no-missing-generic-family-keyword': null;
102
  
103
  /**
104
   * Prevent properties that are ignored due to another property
105
   */
106
  'plugin/declaration-block-no-ignored-properties': true;
107
  
108
  /**
109
   * Allow unknown units (including rpx for responsive design)
110
   */
111
  'unit-no-unknown': [true, { ignoreUnits: ['rpx'] }];
112
  
113
  /**
114
   * Allow unknown selector types (for web components)
115
   */
116
  'selector-type-no-unknown': null;
117
  
118
  /**
119
   * Enforce lowercase keywords, except for CSS modules composes
120
   */
121
  'value-keyword-case': ['lower', { ignoreProperties: ['composes'] }];
122
}
123
```
124

125
## Features
126

127
### CSS Modules Support
128

129
The configuration includes `stylelint-config-css-modules` which provides:
130

131
- Support for CSS modules syntax
132
- Proper handling of `:local()` and `:global()` pseudo-classes
133
- Recognition of `composes` property
134
- Camel case class name support
135

136
### Modern CSS Features
137

138
- CSS custom properties (CSS variables)
139
- CSS Grid and Flexbox properties
140
- Modern CSS functions and values
141
- CSS nesting support (when used with appropriate preprocessors)
142

143
### Responsive Design
144

145
- Support for `rpx` units (commonly used in mobile-first design)
146
- Flexible unit validation
147

148
### Web Components
149

150
- Allows unknown element selectors for custom elements
151
- Supports shadow DOM styling patterns
152

153
## Usage Examples
154

155
### Basic Configuration
156

157
```javascript
158
// .stylelintrc.js
159
module.exports = {
160
  extends: [require.resolve('@umijs/fabric/dist/stylelint')],
161
  rules: {
162
    // Override specific rules if needed
163
  },
164
};
165
```
166

167
### Extended Configuration
168

169
```javascript
170
// .stylelintrc.js
171
module.exports = {
172
  extends: [require.resolve('@umijs/fabric/dist/stylelint')],
173
  rules: {
174
    // Add project-specific rules
175
    'color-hex-length': 'short',
176
    'declaration-block-trailing-semicolon': 'always',
177
  },
178
  ignoreFiles: [
179
    // Add additional ignore patterns
180
    '**/vendor/**/*.css',
181
  ],
182
};
183
```
184

185
### Package.json Configuration
186

187
```json
188
{
189
  "stylelint": {
190
    "extends": "@umijs/fabric/dist/stylelint"
191
  }
192
}
193
```
194

195
### Programmatic Usage
196

197
```javascript
198
const { stylelint: stylelintConfig } = require('@umijs/fabric');
199
const stylelint = require('stylelint');
200

201
// Lint CSS files using the configuration
202
const result = await stylelint.lint({
203
  config: stylelintConfig,
204
  files: 'src/**/*.css',
205
});
206
```
207

208
## Supported File Types
209

210
The configuration processes these file types:
211

212
- **CSS**: `.css`
213
- **SCSS**: `.scss`, `.sass`
214
- **Less**: `.less`
215
- **SugarSS**: `.sss`
216

217
JavaScript and TypeScript files are explicitly ignored to prevent conflicts with other linting tools.
218

219
## Integration with Build Tools
220

221
### Webpack
222

223
```javascript
224
// webpack.config.js
225
const StylelintPlugin = require('stylelint-webpack-plugin');
226

227
module.exports = {
228
  plugins: [
229
    new StylelintPlugin({
230
      configFile: require.resolve('@umijs/fabric/dist/stylelint'),
231
      files: 'src/**/*.{css,scss,sass}',
232
    }),
233
  ],
234
};
235
```
236

237
### Vite
238

239
```javascript
240
// vite.config.js
241
import { defineConfig } from 'vite';
242
import stylelint from 'vite-plugin-stylelint';
243

244
export default defineConfig({
245
  plugins: [
246
    stylelint({
247
      config: require('@umijs/fabric/dist/stylelint'),
248
    }),
249
  ],
250
});
251
```
252

253
## IDE Integration
254

255
### VS Code
256

257
```json
258
// .vscode/settings.json
259
{
260
  "stylelint.enable": true,
261
  "stylelint.configFile": ".stylelintrc.js",
262
  "css.validate": false,
263
  "scss.validate": false,
264
  "less.validate": false
265
}
266
```
267

268
Install the Stylelint extension for VS Code to get inline error reporting and auto-fixing.
269

270
## Git Hooks Integration
271

272
```json
273
// package.json
274
{
275
  "husky": {
276
    "hooks": {
277
      "pre-commit": "lint-staged"
278
    }
279
  },
280
  "lint-staged": {
281
    "*.{css,scss,sass}": [
282
      "stylelint --fix",
283
      "git add"
284
    ]
285
  }
286
}
287
```
288

289
## Rule Categories
290

291
### Syntax Rules
292

293
- Validates CSS syntax correctness
294
- Ensures proper nesting and structure
295
- Checks for valid property-value combinations
296

297
### Best Practices
298

299
- Enforces consistent naming conventions
300
- Prevents common CSS mistakes
301
- Promotes maintainable CSS patterns
302

303
### Formatting Rules
304

305
- Consistent indentation and spacing
306
- Proper ordering of properties
307
- Standardized quote usage
308

309
### Modern CSS
310

311
- Support for CSS custom properties
312
- Modern layout techniques (Grid, Flexbox)
313
- Contemporary CSS functions and values
314

315
## Performance Considerations
316

317
The configuration is optimized for performance:
318

319
- Excludes non-CSS files from processing
320
- Uses efficient rule configurations
321
- Leverages community-maintained presets
322
- Includes only necessary plugins
323

324
## Integration with Prettier
325

326
The configuration includes `stylelint-config-prettier` which:
327

328
- Disables formatting-related rules that conflict with Prettier
329
- Allows Stylelint to focus on code quality rather than formatting
330
- Ensures seamless integration in projects using both tools
331

332
This prevents conflicts and allows both tools to work together effectively.