0
# Configuration
1

2
Comprehensive configuration system supporting extends, plugins, rule settings, file-specific overrides, and complex linting scenarios. Enables both simple setup for common use cases and sophisticated configuration for enterprise environments.
3

4
## Capabilities
5

6
### Configuration Object
7

8
Main configuration interface supporting all Stylelint options and settings.
9

10
```typescript { .api }
11
interface Config {
12
  /** Extend existing configurations */
13
  extends?: string | string[];
14
  /** Load plugins for custom rules */
15
  plugins?: (string | Plugin)[];
16
  /** Internal plugin functions map */
17
  pluginFunctions?: { [pluginName: string]: Rule };
18
  /** Files to ignore during linting */
19
  ignoreFiles?: string | string[];
20
  /** Ignore patterns for inline matching */
21
  ignorePatterns?: string;
22
  /** Rule configuration object */
23
  rules?: { [ruleName: string]: ConfigRuleSettings<any, Object> };
24
  /** File-specific configuration overrides */
25
  overrides?: ConfigOverride[];
26
  /** Custom syntax for non-CSS files */
27
  customSyntax?: CustomSyntax;
28
  /** Output formatter configuration */
29
  formatter?: FormatterType | Formatter;
30
  /** Default severity for rules without explicit severity */
31
  defaultSeverity?: 'warning' | 'error';
32
  /** Ignore disable comments */
33
  ignoreDisables?: boolean;
34
  /** Report unnecessary disable comments */
35
  reportNeedlessDisables?: DisableSettings;
36
  /** Report invalid scope disable comments */
37
  reportInvalidScopeDisables?: DisableSettings;
38
  /** Report disable comments without descriptions */
39
  reportDescriptionlessDisables?: DisableSettings;
40
  /** Report unscoped disable comments */
41
  reportUnscopedDisables?: DisableSettings;
42
  /** Custom configuration comment prefix */
43
  configurationComment?: string;
44
  /** Automatically fix problems where possible */
45
  fix?: boolean;
46
  /** Compute edit info for fixes */
47
  computeEditInfo?: boolean;
48
  /** Enable result caching for performance */
49
  cache?: boolean;
50
  /** Only report errors, ignore warnings */
51
  quiet?: boolean;
52
  /** Allow empty input without failing */
53
  allowEmptyInput?: boolean;
54
  /** Validate rule options */
55
  validate?: boolean;
56
  /** Functions for hooking into Stylelint's pipeline (experimental) */
57
  processors?: string[];
58
  /** Language-specific options */
59
  languageOptions?: LanguageOptions;
60
}
61
```
62

63
### Configuration Resolution
64

65
Resolve effective configuration for specific files, accounting for extends, overrides, and file-specific settings.
66

67
```typescript { .api }
68
/**
69
 * Resolve the effective configuration for a given file
70
 * @param filePath - Path to the file to resolve config for
71
 * @param options - Options for config resolution
72
 * @returns Promise resolving to config or undefined if no config found
73
 */
74
function resolveConfig(
75
  filePath: string,
76
  options?: {
77
    cwd?: string;
78
    config?: Config;
79
    configBasedir?: string;
80
    configFile?: string;
81
  }
82
): Promise<Config | undefined>;
83
```
84

85
**Usage Examples:**
86

87
```javascript
88
import { resolveConfig } from "stylelint";
89

90
// Resolve config for specific file
91
const config = await resolveConfig("./src/styles/main.css");
92

93
// Resolve with custom options
94
const customConfig = await resolveConfig("./src/styles/main.scss", {
95
  cwd: process.cwd(),
96
  configFile: ".stylelintrc.custom.json"
97
});
98

99
// Check if file has configuration
100
if (config) {
101
  console.log("Rules:", config.rules);
102
  console.log("Extends:", config.extends);
103
}
104
```
105

106
### Extending Configurations
107

108
Extend existing configurations from npm packages, files, or built-in presets.
109

110
```typescript { .api }
111
type ConfigExtends = string | string[];
112

113
// Configuration examples
114
const extendsConfig = {
115
  extends: [
116
    "stylelint-config-standard",
117
    "stylelint-config-sass-guidelines",
118
    "./custom-rules.js"
119
  ],
120
  rules: {
121
    // Override or add rules
122
    "color-hex-length": "short"
123
  }
124
};
125
```
126

127
### Rule Configuration
128

129
Configure individual rules with primary options, secondary options, and severity levels.
130

131
```typescript { .api }
132
type ConfigRuleSettings<T, O extends Object> = 
133
  | null                    // Disable rule
134
  | undefined              // Default/inherited
135
  | NonNullable<T>         // Primary option
136
  | [NonNullable<T>]       // Primary option in array
137
  | [NonNullable<T>, O];   // Primary + secondary options
138

139
// Rule configuration examples
140
const rulesConfig = {
141
  rules: {
142
    // Simple boolean rule
143
    "color-no-invalid-hex": true,
144
    
145
    // Rule with primary option
146
    "color-hex-length": "short",
147
    
148
    // Rule with secondary options
149
    "property-no-unknown": [true, { 
150
      ignoreProperties: ["composes"],
151
      checkPrefixed: true 
152
    }],
153
    
154
    // Rule with severity override
155
    "font-weight-notation": [
156
      "numeric", 
157
      { severity: "error" }
158
    ],
159
    
160
    // Disabled rule
161
    "selector-max-id": null
162
  }
163
};
164
```
165

166
### File-Specific Overrides
167

168
Apply different configurations to specific files or file patterns.
169

170
```typescript { .api }
171
interface ConfigOverride {
172
  /** File patterns this override applies to */
173
  files: string | string[];
174
  /** Optional name for the override */
175
  name?: string;
176
  /** Override configuration (same as Config except no overrides) */
177
  extends?: ConfigExtends;
178
  plugins?: (string | Plugin)[];
179
  rules?: { [ruleName: string]: ConfigRuleSettings<any, Object> };
180
  customSyntax?: CustomSyntax;
181
  ignoreFiles?: string | string[];
182
  defaultSeverity?: 'warning' | 'error';
183
  ignoreDisables?: boolean;
184
}
185

186
// Override examples
187
const overrideConfig = {
188
  rules: {
189
    "color-hex-length": "short"
190
  },
191
  overrides: [
192
    {
193
      files: ["**/*.scss"],
194
      customSyntax: "postcss-scss",
195
      rules: {
196
        "at-rule-no-unknown": [true, { 
197
          ignoreAtRules: ["include", "mixin", "extend"] 
198
        }]
199
      }
200
    },
201
    {
202
      files: ["src/legacy/**/*.css"],
203
      rules: {
204
        "property-no-vendor-prefix": null,
205
        "selector-max-id": null
206
      }
207
    }
208
  ]
209
};
210
```
211

212
### Plugin Configuration
213

214
Load and configure custom plugins for additional rules and functionality.
215

216
```typescript { .api }
217
type ConfigPlugins = string | Plugin | (string | Plugin)[];
218

219
interface Plugin {
220
  ruleName: string;
221
  rule: Rule;
222
}
223

224
// Plugin configuration
225
const pluginConfig = {
226
  plugins: [
227
    "stylelint-scss",
228
    "stylelint-order", 
229
    "@stylelint/postcss-css-in-js"
230
  ],
231
  rules: {
232
    // Plugin rules
233
    "scss/at-rule-no-unknown": true,
234
    "order/properties-alphabetical-order": true,
235
    "css-in-js/no-unused-styles": "error"
236
  }
237
};
238
```
239

240
### Disable Comments Configuration
241

242
Configure how disable comments work and are reported.
243

244
```typescript { .api }
245
interface DisableSettings {
246
  except?: (string | RegExp)[];
247
  severity?: 'warning' | 'error';
248
}
249

250
const disableConfig = {
251
  // Report unnecessary disable comments
252
  reportNeedlessDisables: true,
253
  
254
  // Report disable comments without descriptions
255
  reportDescriptionlessDisables: [true, { 
256
    severity: "error" 
257
  }],
258
  
259
  // Report disable comments with invalid scope
260
  reportInvalidScopeDisables: true,
261
  
262
  // Custom configuration comment prefix
263
  configurationComment: "stylelint-custom"
264
};
265
```
266

267
### Custom Syntax Support
268

269
Configure custom syntaxes for processing non-standard CSS files.
270

271
```typescript { .api }
272
type CustomSyntax = string | PostCSS.Syntax;
273

274
const syntaxConfig = {
275
  overrides: [
276
    {
277
      files: ["**/*.scss"],
278
      customSyntax: "postcss-scss"
279
    },
280
    {
281
      files: ["**/*.less"],
282
      customSyntax: "postcss-less"
283
    },
284
    {
285
      files: ["**/*.js", "**/*.jsx"],
286
      customSyntax: "@stylelint/postcss-css-in-js"
287
    }
288
  ]
289
};
290
```
291

292
### Configuration File Formats
293

294
Stylelint supports multiple configuration file formats and loading strategies.
295

296
```javascript
297
// .stylelintrc.json
298
{
299
  "extends": "stylelint-config-standard",
300
  "rules": {
301
    "color-hex-length": "short"
302
  }
303
}
304

305
// .stylelintrc.js
306
module.exports = {
307
  extends: "stylelint-config-standard",
308
  rules: {
309
    "color-hex-length": "short"
310
  }
311
};
312

313
// package.json
314
{
315
  "stylelint": {
316
    "extends": "stylelint-config-standard",
317
    "rules": {
318
      "color-hex-length": "short"
319
    }
320
  }
321
}
322

323
// stylelint.config.js
324
export default {
325
  extends: "stylelint-config-standard",
326
  rules: {
327
    "color-hex-length": "short"
328
  }
329
};
330
```
331

332
### Complete Configuration Example
333

334
```javascript
335
const complexConfig = {
336
  extends: [
337
    "stylelint-config-standard-scss",
338
    "stylelint-config-prettier"
339
  ],
340
  
341
  plugins: [
342
    "stylelint-scss",
343
    "stylelint-order",
344
    "stylelint-declaration-block-no-ignored-properties"
345
  ],
346
  
347
  defaultSeverity: "warning",
348
  
349
  ignoreFiles: [
350
    "node_modules/**/*",
351
    "dist/**/*",
352
    "coverage/**/*"
353
  ],
354
  
355
  rules: {
356
    // Color rules
357
    "color-hex-length": "short",
358
    "color-no-invalid-hex": true,
359
    
360
    // SCSS-specific rules
361
    "scss/at-rule-no-unknown": true,
362
    "scss/dollar-variable-pattern": "^[a-z][a-zA-Z0-9]*$",
363
    
364
    // Order rules
365
    "order/properties-alphabetical-order": true,
366
    
367
    // Custom severity
368
    "selector-max-id": ["error", 0]
369
  },
370
  
371
  overrides: [
372
    {
373
      files: ["**/*.scss"],
374
      customSyntax: "postcss-scss"
375
    },
376
    {
377
      files: ["src/legacy/**/*.css"],
378
      rules: {
379
        "property-no-vendor-prefix": null,
380
        "selector-max-specificity": null
381
      }
382
    }
383
  ],
384
  
385
  reportNeedlessDisables: true,
386
  reportInvalidScopeDisables: true,
387
  reportDescriptionlessDisables: [true, { severity: "error" }]
388
};
389
```