0
# Configuration
1

2
Sass Lint provides a flexible configuration system supporting YAML and JSON files, package.json integration, rule inheritance, and extensive customization options.
3

4
## Capabilities
5

6
### Configuration File Discovery
7

8
Sass Lint automatically discovers configuration files in this priority order:
9

10
```yaml { .api }
11
# Configuration file discovery order (highest to lowest priority):
12
1. Path specified by -c/--config CLI option or configPath parameter
13
2. .sass-lint.yml in current directory or parent directories
14
3. .sasslintrc in current directory or parent directories
15
4. sasslintConfig property in package.json
16
5. Default built-in configuration
17
```
18

19
**File Discovery Examples:**
20

21
```bash
22
# Explicit config file
23
sass-lint -c custom-config.yml
24

25
# Auto-discovery (searches up directory tree)
26
.sass-lint.yml      # Found first
27
../sass-lint.yml    # Searched if not found locally
28
../../.sasslintrc    # Searched if .sass-lint.yml not found
29
```
30

31
### Configuration File Formats
32

33
Support for multiple configuration file formats and naming conventions.
34

35
```yaml { .api }
36
# Supported configuration files:
37
.sass-lint.yml       # Primary YAML format
38
.sasslintrc         # Alternative YAML format (no extension)
39
.sass-lint.json     # JSON format (if YAML parsing fails)
40
package.json        # sasslintConfig property
41
```
42

43
**YAML Configuration (`.sass-lint.yml`):**
44

45
```yaml
46
# Global options
47
options:
48
  formatter: stylish
49
  merge-default-rules: true
50
  cache-config: false
51
  max-warnings: 50
52

53
# File inclusion/exclusion patterns
54
files:
55
  include: '**/*.s+(a|c)ss'
56
  ignore:
57
    - 'node_modules/**'
58
    - 'vendor/**'
59
    - '**/*.min.scss'
60

61
# Rule configuration
62
rules:
63
  indentation:
64
    - 2  # error severity
65
    - size: 2  # 2 spaces
66
  
67
  no-ids: 2
68
  
69
  class-name-format:
70
    - 1  # warning severity
71
    - convention: hyphenatedlowercase
72
      allow-leading-underscore: true
73
```
74

75
**JSON Configuration:**
76

77
```json
78
{
79
  "options": {
80
    "formatter": "stylish",
81
    "merge-default-rules": true,
82
    "cache-config": false
83
  },
84
  "files": {
85
    "include": "**/*.s+(a|c)ss",
86
    "ignore": ["node_modules/**", "vendor/**"]
87
  },
88
  "rules": {
89
    "indentation": [2, {"size": 2}],
90
    "no-ids": 2,
91
    "class-name-format": [1, {
92
      "convention": "hyphenatedlowercase",
93
      "allow-leading-underscore": true
94
    }]
95
  }
96
}
97
```
98

99
**package.json Integration:**
100

101
```json
102
{
103
  "name": "my-project",
104
  "sasslintConfig": {
105
    "rules": {
106
      "indentation": [2, {"size": 4}],
107
      "no-ids": 2
108
    },
109
    "files": {
110
      "ignore": ["dist/**"]
111
    }
112
  }
113
}
114
```
115

116
### Global Options
117

118
Configure global sass-lint behavior and output formatting.
119

120
```yaml { .api }
121
options:
122
  # Output formatter (uses ESLint formatters)
123
  formatter: stylish  # stylish, compact, json, junit, checkstyle, tap, unix
124
  
125
  # Rule inheritance behavior
126
  merge-default-rules: true   # Merge with built-in rules (true) or replace (false)
127
  
128
  # Configuration caching
129
  cache-config: false         # Cache parsed config for performance
130
  
131
  # Warning threshold
132
  max-warnings: 50           # Maximum warnings before error exit code
133
  
134
  # Output file path
135
  output-file: results.txt   # Write results to file instead of console
136
```
137

138
**Option Details:**
139

140
- **formatter**: Output format for results (inherits ESLint formatters)
141
- **merge-default-rules**: When `true`, user rules merge with defaults; when `false`, user rules completely replace defaults
142
- **cache-config**: Cache parsed configuration for better performance with repeated runs
143
- **max-warnings**: Exit with error code if warning count exceeds this threshold
144
- **output-file**: Write formatted results to specified file path
145

146
### File Patterns
147

148
Configure which files to include or exclude from linting.
149

150
```yaml { .api }
151
files:
152
  # Files to include (glob patterns)
153
  include: '**/*.s+(a|c)ss'  # Single pattern
154
  include:                   # Multiple patterns
155
    - 'src/**/*.scss'
156
    - 'components/**/*.sass'
157
  
158
  # Files to exclude (glob patterns)
159
  ignore: 'node_modules/**'  # Single pattern
160
  ignore:                    # Multiple patterns
161
    - 'node_modules/**'
162
    - 'vendor/**'
163
    - 'dist/**'
164
    - '**/*.min.scss'
165
```
166

167
**Pattern Examples:**
168

169
```yaml
170
files:
171
  include:
172
    - 'src/**/*.scss'           # All SCSS files in src directory
173
    - 'components/**/*.sass'    # All Sass files in components directory
174
    - '**/*.s+(a|c)ss'         # All Sass and SCSS files anywhere
175
  
176
  ignore:
177
    - 'node_modules/**'        # Exclude node_modules
178
    - 'vendor/**'              # Exclude vendor directory
179
    - '**/temp/**'             # Exclude any temp directories
180
    - '**/*.min.{scss,sass}'   # Exclude minified files
181
    - 'legacy/**'              # Exclude legacy code
182
```
183

184
### Rule Configuration
185

186
Configure individual linting rules with severity levels and options.
187

188
```yaml { .api }
189
rules:
190
  # Simple rule with severity only
191
  rule-name: 0  # 0 = off, 1 = warning, 2 = error
192
  
193
  # Rule with severity and options
194
  rule-name:
195
    - 2          # severity level
196
    - option1: value1
197
      option2: value2
198
```
199

200
**Severity Levels:**
201

202
```yaml { .api }
203
# Rule severity options
204
0  # Off - rule is completely disabled
205
1  # Warning - rule violation generates warning (exit code 0)
206
2  # Error - rule violation generates error (exit code 1)
207
```
208

209
**Complex Rule Configuration:**
210

211
```yaml
212
rules:
213
  # Indentation with spaces
214
  indentation:
215
    - 2
216
    - size: 2  # 2 spaces
217
  
218
  # Indentation with tabs
219
  indentation:
220
    - 2
221
    - size: tab
222
  
223
  # Class naming convention
224
  class-name-format:
225
    - 1
226
    - convention: hyphenatedlowercase  # or camelcase, snakecase, strictbem
227
      allow-leading-underscore: true
228
      ignore: ['js-*']  # Ignore classes starting with 'js-'
229
  
230
  # Property sort order
231
  property-sort-order:
232
    - 1
233
    - order: alphabetical  # or smacss, recess, concentric, or custom array
234
  
235
  # Custom property order
236
  property-sort-order:
237
    - 1
238
    - order:
239
        - display
240
        - position
241
        - top
242
        - right
243
        - bottom
244
        - left
245
        # ... etc
246
```
247

248
### Property Sort Orders
249

250
Predefined property sort orders for consistent CSS organization.
251

252
```yaml { .api }
253
property-sort-order:
254
  - 1
255
  - order: alphabetical  # Built-in orders
256
  # Built-in options: alphabetical, smacss, recess, concentric
257
```
258

259
**Built-in Sort Orders:**
260

261
- **alphabetical**: Properties sorted alphabetically
262
- **smacss**: SMACSS (Scalable and Modular Architecture for CSS) methodology
263
- **recess**: Twitter's Recess property order
264
- **concentric**: Concentric CSS property order (outside-in)
265

266
**Custom Sort Order:**
267

268
```yaml
269
property-sort-order:
270
  - 1
271
  - order:
272
      # Positioning
273
      - position
274
      - top
275
      - right
276
      - bottom
277
      - left
278
      - z-index
279
      
280
      # Display & Box Model
281
      - display
282
      - flex
283
      - flex-direction
284
      - justify-content
285
      - align-items
286
      
287
      # Dimensions
288
      - width
289
      - height
290
      - padding
291
      - margin
292
      
293
      # Visual
294
      - background
295
      - color
296
      - font-family
297
      - font-size
298
```
299

300
### Configuration Inheritance
301

302
Extend from built-in or custom configurations.
303

304
```yaml { .api }
305
# Extend built-in configurations
306
extends: sass-lint:recommended  # Use built-in recommended rules
307

308
# Override specific rules after extending
309
rules:
310
  indentation:
311
    - 2
312
    - size: 4  # Override default indentation
313
  no-ids: 0   # Disable no-ids rule
314
```
315

316
### Rule Toggles
317

318
Disable rules for specific code sections using Sass comments.
319

320
```scss { .api }
321
// sass-lint:disable rule-name
322
.exception {
323
  color: red !important;  // !important allowed here
324
}
325
// sass-lint:enable rule-name
326

327
// Disable multiple rules
328
// sass-lint:disable no-important, no-color-literals
329
.special {
330
  color: red !important;
331
}
332
// sass-lint:enable no-important, no-color-literals
333

334
// Disable rule for single line
335
color: red !important; // sass-lint:disable-line no-important
336

337
// Disable all rules for block
338
// sass-lint:disable-all
339
.legacy-code {
340
  // Any violations ignored
341
}
342
// sass-lint:enable-all
343
```
344

345
### Environment-Specific Configuration
346

347
Configure different rules for different environments or file types.
348

349
```yaml
350
# Base configuration
351
options:
352
  formatter: stylish
353

354
# Stricter rules for production
355
rules: &strict-rules
356
  no-important: 2
357
  no-color-literals: 2
358
  max-nesting-depth: [2, {max-depth: 2}]
359

360
# Development overrides
361
rules:
362
  <<: *strict-rules
363
  no-important: 1      # Warnings only in development
364
  no-color-literals: 1
365
```
366

367
### CLI Integration
368

369
Command-line options override configuration file settings.
370

371
```yaml { .api }
372
# Priority order (highest to lowest):
373
1. CLI options (--format, --config, etc.)
374
2. Configuration file rules
375
3. Default configuration
376
```
377

378
**CLI Override Examples:**
379

380
```bash
381
# Override formatter
382
sass-lint --format json  # Overrides config formatter
383

384
# Override config file
385
sass-lint --config strict.yml  # Uses strict.yml instead of .sass-lint.yml
386

387
# Override ignore patterns
388
sass-lint --ignore 'vendor/**, temp/**'
389
```
390

391
### Configuration Validation
392

393
Sass Lint validates configuration files and provides helpful error messages.
394

395
```yaml { .api }
396
# Common configuration errors:
397
# - Invalid YAML syntax
398
# - Unknown rule names
399
# - Invalid rule options
400
# - Invalid severity levels (not 0, 1, or 2)
401
# - Invalid file patterns
402
```
403

404
**Error Examples:**
405

406
```yaml
407
# Invalid severity level
408
rules:
409
  no-ids: 3  # Error: severity must be 0, 1, or 2
410

411
# Unknown rule name
412
rules:
413
  no-typo: 2  # Error: unknown rule 'no-typo'
414

415
# Invalid rule option
416
rules:
417
  indentation:
418
    - 2
419
    - invalid-option: true  # Error: unknown option
420
```
421

422
### Complete Configuration Example
423

424
```yaml
425
# Complete .sass-lint.yml example
426
options:
427
  formatter: stylish
428
  merge-default-rules: true
429
  cache-config: false
430
  max-warnings: 25
431

432
files:
433
  include: 
434
    - 'src/**/*.scss'
435
    - 'components/**/*.sass'
436
  ignore:
437
    - 'node_modules/**'
438
    - 'vendor/**'
439
    - 'dist/**'
440
    - '**/*.min.scss'
441

442
rules:
443
  # Extends
444
  extends-before-mixins: 2
445
  extends-before-declarations: 2
446
  placeholder-in-extend: 2
447
  
448
  # Mixins
449
  mixins-before-declarations: 2
450
  
451
  # Line Spacing
452
  one-declaration-per-line: 2
453
  empty-line-between-blocks: 1
454
  single-line-per-selector: 2
455
  
456
  # Naming Conventions
457
  class-name-format:
458
    - 2
459
    - convention: hyphenatedlowercase
460
      allow-leading-underscore: true
461
  
462
  variable-name-format:
463
    - 2
464
    - convention: hyphenatedlowercase
465
      allow-leading-underscore: true
466
  
467
  # Style Guide
468
  indentation:
469
    - 2
470
    - size: 2
471
  
472
  quotes:
473
    - 2
474
    - style: single
475
  
476
  property-sort-order:
477
    - 1
478
    - order: smacss
479
  
480
  # Restrictions
481
  no-ids: 2
482
  no-important: 1
483
  no-color-literals:
484
    - 2
485
    - allow-rgba: true
486
      allow-variable-identifiers: true
487
  
488
  nesting-depth:
489
    - 2
490
    - max-depth: 3
491
  
492
  # Spacing
493
  space-after-colon: 2
494
  space-before-brace: 2
495
  space-after-comma: 2
496
  
497
  # Final formatting
498
  trailing-semicolon: 2
499
  final-newline: 2
500
```